Search

    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:

       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:

    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.

    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.

    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.

    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.

    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.

    Show/Hide Beta Features