typescript.md

status
released

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 tsx

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

   cds add typescript

   You can modify this configuration file to match your project setup. See the official TypeScript documentation for more details. Note that adding the typescript facet, cds-typer is also automatically added to your project.

Writing TypeScript Files

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

Samples

For a full TypeScript application, check out the SFlight application. It features both CAP service handlers and client-side code for SAP Fiori Elements written in TypeScript.

Developing TypeScript Projects

Using cds watch { #cds-watch}

Preferably use cds watch in a TypeScript project as if it was a JavaScript project. It detects TypeScript mode based on a tsconfig.json and run cds-tsx under the hood.

cap/sflight $ cds watch

Detected tsconfig.json. Running with tsx.
...
[cds] serving TravelService { impl: 'srv/travel-service.ts', path: '/processor' }
...

The same applies to cds serve.

Using cds-tsx { #cds-tsx}

Alternatively, you can use the cds-tsx CLI command instead of cds for automatic TypeScript transpilation:

::: code-group

cds-tsx watch

cds-tsx serve

:::

Under the hood, the tsx engine is used to run the files instead of the default node engine. Install it globally with:

npm i -g tsx

::: warning Not for production Use cds-watch and cds-tsx / tsx during development only. For productive usage, always precompile TypeScript code to JavaScript for best performance and use cds-serve as usual. :::

Using cds-ts { #cds-ts}

Much like cds-tsx, you can also use the cds-ts CLI command:

::: code-group

cds-ts watch

cds-ts serve

:::

It uses the ts-node engine under the hood.

::: tip tsx or ts-node? In general, tsx is the better choice, as tsx is considerably faster than ts-node because it doesn't perform type checks. See a closer comparison between the two of them. :::

Testing with ts-jest

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

1. Install ts-jest locally:

   npm install -D ts-jest

2. Tell Jest to use the preset ts-jest, for example, 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

Building TypeScript Projects

A dedicated build task for cds build is provided as part of the cds-typer package.

Learn more about integrating it into your build process.{.learn-more}

TypeScript APIs in @sap/cds

The package @cap-js/cds-types contains all TypeScript declarations for @sap/cds APIs. 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. Just add the @cap-js/cds-types package to your project as follows:

npm add @cap-js/cds-types

Use the Typescript declarations 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.