build.md

synopsis	status
The guide provides an overview of custom build processes for CAP projects, explaining how to tailor the standard build process to specific project requirements.	released

Customizing cds build

[[toc]]

Automatic Build Tasks

cds build runs build tasks on your project to prepare it for deployment.

Build tasks compile source files (typically CDS sources) and create required artifacts, for example, EDMX files or SAP HANA design-time artifacts.

For a full production build, this command should be enough for most projects:

cds build --production

Build tasks are derived from the CDS configuration and project context. By default, CDS models are resolved from these sources:

• db/, srv/, app/ — default root folders of a CAP project
• fts/ and its subfolders when using feature toggles
• CDS model folders and files defined by required services
  • Built-in examples: persistent queue or MTX-related services
• Explicit src folder configured in the build task

Feature toggle folders and required built-in service models will also be added if user-defined models have been configured as a model option in your build tasks.

Learn more about cds.resolve{.learn-more}

Extending cds build

Provide additional service integrations by writing a cds build plugin:

// cds-plugin.js
const cds = require('@sap/cds')
cds.build?.register?.('my-plugin',
  class extends cds.build.Plugin {
    async build() { /* ... */ }
  }
)

Learn more about cds build plugins{.learn-more}{style="margin-top: 0px"}

Custom Build Tasks

If custom build tasks are configured, those properties have precedence.

For example, you want to configure the src folder and add the default models. To achieve this, do not define the model option in your build task:

::: code-group

{ "cds": {
  "build": {
   "target": "gen",
   "tasks": [
     { "for": "nodejs", "src": "srv" }
    ]
  }
}}

:::

This way, the model paths will still be dynamically determined, but the src folder is taken from the build task configuration. You still benefit from the automatic determination of models – for example when adding a new external services or when CAP is changing any built-in service defaults.

To control which tasks cds build executes, you can add them as part of your project configuration in package.json or .cdsrc.json, as outlined in the following chapter.

Build Task Types

The for property defines the executed build task type creating its part of the deployment layout. Currently supported types are:

<style lang="scss" scoped> th { min-width: 160px; } </style>

Type	Description
hana	SAP HANA Development Infrastructure (HDI) artifacts Learn more about configuring SAP HANA{.learn-more}
nodejs	Node.js applications
java	Java applications
mtx-sidecar	MTX-enabled projects with sidecar architecture. Learn more about Multitenant Saas Application Deployment{.learn-more}
mtx	MTX-enabled projects without sidecar architecture (Node.js only). Required services are served by the Node.js application itself.
mtx-extension	MTX extension project (extension.tgz), which is required for extension activation using cds push. Extension point restrictions defined by the SaaS app provider are validated by default. If any restriction is violated the build aborts and the errors are logged. The build task is created by default for projects that have "cds": { "extends": "\<SaaS app name\>" } configured in their package.json. Learn more about Extending and Customizing SaaS Solutions{.learn-more}

Additional types may be supported by build plugin contributions.

Build Task Properties

Build tasks can be customized using the following properties:

Property	Description
src	Source folder of module to be built.
dest	Optional destination of the module's build destination, relative to the enclosing project. The src folder is used by default.
options	model: string or array of string The given list of folders or individual .cds file names is resolved based on the current working directory or project folder passed to cds build. CDS built-in models (prefix @sap/cds*) are added by default to the user-defined list of models.

Note: Alternatively you can execute build tasks and pass the described arguments to the command line. See also cds build --help for further details.

Build Target Folder {#build-target-folder}

To change the default target folder, use the cds.build.target=path/to/my/folder. It is resolved based on the root folder of your project.

Node.js

Node.js projects use the folder ./gen below the project root as build target folder by default.
Relevant source files from db or srv folders are copied into this folder, which makes it self-contained and ready for deployment. The default folder names can be changed with the cds.folders.db, cds.folders.srv, cds.folders.app configuration. Or you can go for individual build task configuration for full flexibility.

Project files like .cdsrc.json or .npmrc located in the root folder or in the srv folder of your project are copied into the application's deployment folder (default gen/srv). Files located in the srv folder have precedence over the corresponding files located in the project root directory. As a consequence these files are used when deployed to production. Make sure that the folders do not contain one of these files by mistake. Consider using profiles development or production in order to distinguish environments. CDS configuration that should be kept locally can be defined in a file .cdsrc-private.json.

The contents of the node_modules folder is not copied into the deployment folder. For security reasons the files default-env.json and .env are also not copied into the deployment folder.

You can verify the CDS configuration settings that become effective in production deployments. Executing cds env --profile production in the deployment folder gen/srv will log the CDS configuration used in production environment.

Learn more about cds env get{.learn-more}

Note: cds build provides options you can use to switch the copy behavior of specific files on or off on build task level:

::: code-group

{
  "build": {
    "tasks": [
      { "for": "nodejs", "options": { "contentCdsrcJson": false, "contentNpmrc": false } },
      { "for": "hana", "options": { "contentNpmrc": false } }
    ]
  }
}

:::

npm Workspace Support {#build-ws}

Use CLI option --ws-pack to enable tarball based deployment of npm workspace dependencies. Workspaces are typically used to manage multiple local packages within a singular top-level root package. Such a setup is often referred to as a monorepo.

As an effect, your workspace dependencies can be deployed to SAP BTP without them being published to an npm registry before.

Behind the scenes, cds build --ws-pack creates a tarball in folder gen/srv for each workspace dependency of your project that has a * version identifier. Dependencies in gen/package.json will be adapted to point to the correct tarball file URL:

::: code-group

{
  "dependencies": {
    "some-package": "^1",  // regular package
    "some-workspace": "*"  // workspace dependency, marked as such via "*"
  }
}

:::

Packaging of the tarball content is based on the rules of the npm pack command:

• Files and folders defined in .gitignore will not be added
• If an optional files field is defined in the workspace's package.json, only those files will be added.

Java

Java projects use the project's root folder ./ as build target folder by default.
This causes cds build to create the build output below the individual source folders. For example, db/src/gen contains the build output for the db/ folder. No source files are copied to db/src/gen because they're assumed to be deployed from their original location, the db/ folder itself.