typescript.md

status	redirect_from
released	get-started/using-typescript

Using TypeScript

While CAP itself is written in JavaScript, it's possible to use TypeScript within your project as outlined here.

[[toc]]

Enable TypeScript Support

Follow these steps to add TypeScript support:

1. Install typescript packages globally:

   npm i -g typescript ts-node

2. Add a tsconfig.json file to your project.

   You need to provide a tsconfig.json file in which you configure how you want to use TypeScript. See the official TypeScript documentation for more details.

Developing with cds-ts { #cds-ts}

Use the cds-ts CLI command instead of cds to avoid having to precompile TypeScript files to JavaScript each time and speed up development:

cds-ts serve world.cds

cds-ts watch

When using the binary cds-ts, the ts-node engine is used to start the project instead of the default node engine.

::: warning Note that this binary should be used for development only. For productive usage always precompile TypeScript code to JavaScript due to performance reasons and use the cds binary. :::

Writing TypeScript Files

Once you've setup everything correctly, you can start writing TypeScript files instead of JavaScript files. This applies for service handlers, as well as a custom server.ts file or database init.ts seeding files.

Samples

You can also download the Hello World! TypeScript sample or try out the Full Stack TypeScript App.

Testing with ts-jest

Run your Jest tests with preset ts-jest without precompiling TypeScript files.

1. Install ts-jest locally:

   npm add ts-jest

2. Tell Jest to use the preset ts-jest, e.g. in your jest.config.js:

   module.exports = {
     preset: "ts-jest",
     globalSetup: "./test/setup.ts"
   };

3. Set CDS_TYPESCRIPT environment variable:

   This is necessary, because it isn't possible to programmatically detect that the preset ts-jest is used and we've to know whether we need to look for .ts or .js files.

   File ./test/setup.ts, content:

   module.exports = async () => {
     process.env.CDS_TYPESCRIPT = "true";
   };

4. Run your tests as usual:

   jest

TypeScript APIs in @sap/cds

The package @sap/cds is shipped with TypeScript declarations. These declarations are used automatically when you write TypeScript files, but also enable IntelliSense and type checking for standard JavaScript development in Visual Studio Code.

Use them like this:

import { Request } from '@sap/cds'

function myHandler(req: Request) { }

Types are available even in JavaScript through JSDoc comments:

/**
 * @param { import('@sap/cds').Request } req
 */
function myHandler(req) { }

Type Imports

Import types through the cds facade class only:

Good: {.good}

import { ... } from '@sap/cds' // [!code ++]

Bad: {.bad}

Never code against paths inside @sap/cds/apis/:

import { ... } from '@sap/cds/apis/events' // [!code --]

Community

Help us improve the types

We invite you to contribute and help us complete the typings as appropriate. Find the sources on GitHub and open a pull request or an issue.

Still, as @sap/cds is a JavaScript library, typings aren't always up to date. You should expect a delay for typings related to the latest release, even gaps, and errors.

Generating Model Types Automatically

The cds-typer package offers a way to derive TypeScript definitions from a CDS model to give you enhanced code completion and a certain degree of type safety when implementing services.

class CatalogService extends cds.ApplicationService { init() {
    const { Book } = require('#cds-models/sap/capire/bookshop')

    this.before('CREATE', Book, req => {
        req.data.…  // known to be a Book. Code completion suggests:
              // ID (number)
              // title (string)
              // author (Author)
              // createdAt (Date)
              // …
    })
}}

You can find extensive documentation in a dedicated chapter, together with a quickstart guide to get everything up and running.