Skip to content
On this page

Using TypeScript

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

Enable TypeScript Support

Follow these steps to add TypeScript support:

  1. Install typescript packages globally:

    sh
    npm i -g typescript ts-node
    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

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

sh
cds-ts serve world.cds
cds-ts serve world.cds
sh
cds-ts watch
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:

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

    js
    module.exports = {
      preset: "ts-jest",
      globalSetup: "./test/setup.ts"
    };
    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:

    js
    module.exports = async () => {
      process.env.CDS_TYPESCRIPT = "true";
    };
    module.exports = async () => {
      process.env.CDS_TYPESCRIPT = "true";
    };
  4. Run your tests as usual:

    sh
    jest
    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.

WARNING

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.

TIP

We invite you to contribute and help us complete the typings as appropriate. Sounds interesting? Reach out to us.

Enhanced TypeScript Support

CAP envisions to enhance the TypeScript support and, for example, generate TypeScript interfaces for definitions in CDS models. But it's important to know, that this isn't planned in our roadmap (yet).

There are already community contributions that fill in this gap.
See the blog post by Simon Gaudeck for more details.