How to build a CAP plugin

// cds-plugin.js, next to the package's package.json
const cds = require('@sap/cds')
cds.on('served', (services) => {
  // the application's services are bootstrapped here;
  // register handlers on them as needed
})

Auto-configuration and configuration schema in the plugin's package.json

Node.js

package.json "cds" section / cds.schema

capire documents that a plugin adds configuration by putting a cds section in its own package.json, which is merged into cds.env of the consuming project, and uses @cap-js/sqlite as the example. The same section may declare additions to the cds configuration schema under schema (buildTaskType, databaseType, cds, marked Beta), so a consuming project gets code completion for the plugin's settings.

CDS plugins in CAP 104

jsonAdapted from cap.cloud.sap ↗

{
  "cds": {
    "requires": {
      "db": "sql",
      "kinds": {
        "sql": { "[development]": { "kind": "sqlite" } },
        "sqlite": { "impl": "@cap-js/sqlite" }
      }
    }
  }
}

Service implementations selected by cds.requires.<srv>.kind and .impl

Node.js

cds.requires.<srv>.kind / cds.requires.<srv>.impl

capire documents that a required service's implementation is configured in cds.requires with impl (a module path), and that service configurations inherit from each other along kind chains, so a project writes kind: 'sqlite' or kind: 'odata' and gets the implementation configured for that kind. A reuse package that offers an alternative implementation of a service ships its own kinds with an impl and lets the consuming project pick one by kind, as @cap-js/audit-logging does with audit-log-to-console in development and audit-log-to-restv2 in production.

jsonAdapted from cap.cloud.sap ↗

"cds": { "requires": {
  "some-service": { "impl": "some/node/module/path" },
  "db": { "kind": "sqlite" },
  "remote-service": { "kind": "odata" }
}}

Event handlers srv.before / srv.on / srv.after

Node.js

srv.before, srv.on, srv.after

capire documents three phases of request processing: .before handlers run before the .on handlers (for example validating inbound data), .on handlers fulfil requests, and .after handlers run after them (for example enriching outbound data); the event may be '*' and the entity '*' to match everything. capire notes that custom domain logic mostly goes into .before or .after handlers because cds.ApplicationService provides generic .on handlers for CRUD; a plugin registers the same handlers on services it did not write.

class BooksService extends cds.ApplicationService {
  init() {
    const { Books, Authors } = this.entities
    this.before ('READ', Authors, req => {...})
    this.after ('READ', Books, books => {...})
    this.on ('submitOrder', req => {...})
    return super.init()
  }
}

Reuse aspects

CDS

aspect / entity Foo : aspectA, aspectB

capire's Aspect-Oriented Modeling guide marks separate reuse aspects as the preferred form over a central base class: each aspect (cuid, managed, temporal and the like) is defined on its own and consumers combine them with the ':' include syntax, which works as mixins rather than inheritance. A reuse package that adds fields or relationships to consumers' entities ships them as aspects, and @sap/cds/common already provides some of them.

aspect managed {
  createdAt  : DateTime;
  createdBy  : User;
  modifiedAt : DateTime;
  modifiedBy : User;
}

// consumer
using { cuid, managed, temporal } from 'your-reuse-aspects';
entity Bar : cuid, managed, temporal {...}

Extending and annotating reused definitions

CDS

extend / annotate

capire documents that a consumer adapts definitions it obtained from a reuse package with extend (adding fields, adapting a field's length, adding associations and compositions, adding aspects) and with annotate, without editing the package. The same guide shows extend managed adding a composition that every entity using the aspect then receives, own or reused.

using { CodeList, Currencies, Languages } from 'some-reuse-package';
extend CodeList with { descr: localized String }
extend Currencies with { symbol: String(2) }
extend Languages:locale with (length:15);

Annotations as a plugin's trigger

CDSNode.jsJava

annotate <Entity> with @<Annotation>

capire's plugin page describes the usual flow for a plugin as adding the package, adding annotations to the model, and binding the platform service, using annotate Customer with @PersonalData for Audit Logging on both runtimes. The CAP Java Building Plugins guide names handlers that react to model characteristics, common types or annotations, as the case for an event-handler plugin.

// after: npm add @cap-js/audit-logging   (Node.js)
//   or: cds-feature-auditlog-v2 dependency  (Java)
annotate Customer with @PersonalData ...;

Reuse package entry points and @impl for handlers

CDSNode.js

index.cds, @impl

capire's Service Composition guide states that CDS has no public/private mechanism and calls an index.cds in the package root good and proven practice, so consumers write using ... from 'package-name', with further entry points such as a schema.cds for partial use. In a Node.js reuse package, custom handlers are named explicitly with the @impl annotation and a fully qualified module path, and a consumer can override @impl to replace or wrap the package's implementation.

Packages in CAP 37

// provider/index.cds
namespace my.reuse.package;
using from './db/schema';
using from './srv/cat-service';

// bookshop/srv/cat-service.cds
service CatalogService @(impl: '@sap/bookshop/srv/cat-service.js') {...}

Packaged APIs with cds export (the 'Calesi' pattern)

CDSNode.js

cds export --plugin

capire's CAP-Level Service Integration guide, subtitled the 'Calesi' pattern, describes exporting a service's interface with cds export into a package that is published to npm or Maven and imported by consuming apps, which then use the remote service as if it were local and get it mocked for local development. With --plugin the exported package gets a cds-plugin.js tag file and a cds.requires entry, so the consumer gets plug-and-play configuration.

Packages in CAP 37

cds export srv/data-service.cds --plugin
npm publish ./apis/data-service

Plugins for cds add

Node.js

cds.add.register(name, impl)

capire documents public APIs for writing cds add plugins, registered from cds-plugin.js with cds.add?.register?.(name, class extends cds.add.Plugin), and states that the built-in cds add plugins of @sap/cds-dk use the same APIs. A reuse package uses it to add its own project configuration, with run() for its own files and combine() to integrate with other facets such as mta or kyma; the example is cds add postgres.

CDS plugins in CAP 104

// cds-plugin.js
cds.add?.register?.('postgres',
  class extends cds.add.Plugin {
    async run() { /* ... */ }
    async combine() { /* ... */ }
  }
)

Build plugins for cds build

Node.js

cds.build.register(id, class extends cds.build.Plugin)

capire documents build plugins, run by cds build to produce deployment artifacts, as Node.js modules following the CDS plugin architecture and registered in a top-level cds-plugin.js; the build system calls taskDefaults, hasTask(), init(), clean and build in that order. The reference implementation is the @cap-js/postgres plugin, which combines runtime and design-time integration in one package.

Build tools in CAP 8

const { fs, path } = cds.utils;
cds.build?.register?.('postgres', class PostgresBuildPlugin extends cds.build.Plugin {
  static taskDefaults = { src: cds.env.folders.db }
  static hasTask() {
    return cds.requires.db?.kind === 'postgres';
  }
  async build() {
    const model = await this.model();
    if (!model) return;
    await this.write(cds.compile.to.json(model)).to(path.join('db', 'csn.json'))
  }
})

03Depending on @sap/cds

capire does not say which @sap/cds versions a plugin declares. npm's own documentation describes peerDependencies as the way a plugin states which versions of its host it works with, without installing a second copy of it. What the published plugins declare, read from the npm registry:

Package	Version	peerDependencies @sap/cds	engines.node
@cap-js/audit-logging	1.3.0	>=9	none declared
@cap-js/attachments	4.0.0	>=9	none declared
@cap-js/change-tracking	2.2.2	>=8.5	none declared
@cap-js/telemetry	2.1.0	^10 \|\| ^9	none declared
@cap-js/notifications	1.1.0	>=8.0	>=20.0.0
@cap-js/ord	1.9.3	>=8.9.4	>=20 <25
@cap-js/sqlite	3.1.1	^10	none declared
@cap-js/hana	3.1.1	^10	none declared
@cap-js-community/event-queue	2.3.1	none declared	^22.13.0 \|\| >=24
@cap-js-community/websocket	1.11.2	none declared	>=18

Read from the npm registry 2026-09-29

04Tests, checks, types and releases

Each as CAP's own documentation describes it, with the pages to read. Where a source recommends something, the recommendation is its own.

Testing (Node.js): cds.test

@cap-js/cds-testcds testnode --testVitestJestMochacds bind --exec

capire documents adding @cap-js/cds-test as a dev dependency; cds.test() launches a CAP server for a given project and returns HTTP helpers (GET, POST, ...), expect and defaults, and services can also be tested programmatically with cds.connect.to. Tests run with Node's built-in test runner, Vitest, Jest, Mocha or cds test, and capire recommends runner-agnostic tests via cds.test.expect, calling cds.test() before loading cds.env, and cds.test.in() instead of process.chdir(). Its best practices name minimal assumptions (stable error codes, not messages) and no snapshot tests; cds.test() is also one of the commands that load plugins.

const cds = require ('@sap/cds')
const { GET, expect } = cds.test ('@capire/bookshop')

it('Allows testing programmatic APIs', async () => {
  const AdminService = await cds.connect.to('AdminService')
  const { Authors } = AdminService.entities
  expect (await SELECT.from(Authors))
  .to.eql(await AdminService.read(Authors))
})

Plugin testing across @sap/cds and CAP Java majors

cds-services-bomcds-services-apiMaven

For CAP Java plugins, capire recommends building against the current LTS version (last minor and patch of the maintenance release) of cds-services-bom so the plugin is consumable by most applications, and running integration tests with embedding applications configured for each major version (current and prior). It also recommends Java 17 bytecode for plugins and reserves the com.sap.cds groupId and package names for the CAP Java team.

Linting: CDS Lint

@sap/eslint-plugin-cdscds lintcds add lintESLint

capire documents CDS Lint as the ESLint plugin @sap/eslint-plugin-cds together with the cds lint command of @sap/cds-dk; cds add lint installs ESLint, the plugin and the configuration, including VS Code settings. capire recommends the cds lint CLI over the plain ESLint CLI because it comes preconfigured, and the rules are listed on a rules reference page.

CDS Lint (capire) ↗

cds add lint
cds lint

Typing: cds-typer and TypeScript

@cap-js/cds-typercds add typercds add typescriptcds-tsxcds-tstsc

capire documents @cap-js/cds-typer, added with cds add typer, which generates types from the CDS model into @cds-models so that handlers such as srv.before('CREATE', Books, ...) receive typed data; cds add typescript adds a tsconfig.json and cds-typer. capire recommends not committing the generated types and running cds-typer in CI before tests, with npx @cap-js/cds-typer "*" --outputDirectory @cds-models, and with typescript installed cds build includes a typescript build task. Type definitions of @sap/cds ship since version 8, and incomplete types are reported in the cap-js/cds-types repository.

npx @cap-js/cds-typer "*" --outputDirectory @cds-models

Reuse package structure and publishing

npm publishnpm packmvn packagecds export

capire's Service Composition guide says every CAP-based project can serve as a reuse package; as a provider it describes an index.cds entry point (and optional further ones), @impl with a fully qualified module path for Node.js handlers, a CdsRuntimeConfiguration or Spring auto-configuration for Java handlers, CDS/CSV/i18n files under src/main/resources/cds/<groupId>/<artifactId>/ for Maven, and a README naming what is provided and the stable entry points. It names publishing to registries such as npmjs.org, pkg.github.com or Maven Central as the preferred way to share, because consumers then get version management; npm pack or mvn package work as well.

Versioning against @sap/cds and CAP Java majors

@sap/cdscds-services-bompeerDependencies

capire's release schedule states that CAP Node.js majors follow the Node.js release schedule, with a new major when a Node.js LTS reaches end of life, that major upgrades may carry breaking changes to public APIs, and that public APIs are only those documented in capire; minor releases come monthly without breaking changes to public APIs. CAP Java majors have no fixed schedule, the previous major stays in maintenance for at most twelve months with critical fixes only, and capire recommends importing BOM poms such as cds-services-bom to keep versions consistent. capire does not state a peerDependencies rule for plugins; @cap-js/audit-logging, for example, declares "@sap/cds": ">=9" as a peer dependency in its package.json.

CI

cds add github-actionsGitHub ActionsSAP Continuous Integration and DeliveryProject Piper

capire's CI/CD guide documents cds add github-actions (shortcut cds add gha), which adds GitHub Actions workflows to test, deploy to staging on pushes to main and deploy to production on a GitHub release, as used in the capire samples. It also names SAP Continuous Integration and Delivery, with a ready-to-use pipeline for CAP Node.js, Java and MTA projects, and project Piper for more flexible pipelines.

shAdapted from cap.cloud.sap ↗

cds add github-actions

05Using open source

Taking open source into a project, and publishing your own under an open licence, as CAP's projects and documentation describe it. Every artifact in the atlas carries the same readings, maintenance and licence among them, before it goes into a project.

Open version ranges when publishing a reuse package

npm

capire's Node.js best practices apply to consumers and providers of reuse packages alike. For a package published for reuse, capire says to keep open (caret) ranges in package.json, run npm update before publishing and test, and not to publish an npm-shrinkwrap.json. Its stated reasons: exact pins give consuming projects duplicate copies of @sap/cds and other shared packages, withhold fixes, and break reuse of shared CDS models such as @sap/cds/common.

jsonAdapted from cap.cloud.sap ↗

"dependencies": {
  "@sap/cds": "^9.1.0",
  "@sap/some-reuse-package": "^1.1.0",
  "express": "^4.17.0"
}

Lock dependencies before deploying, not before publishing

npmpackage-lock.jsonnpm ci

capire separates the two cases: an application released to end consumers commits a package-lock.json so that cloud deployers and build packs install the versions that were tested and checked for vulnerabilities. npm documents package-lock.json as the exact generated tree, intended to be committed, and npm ci as a clean install for automated environments that requires an existing lockfile. The lockfile of a library is not what its consumers install, which is why capire keeps ranges open for reuse packages.

npm config set package-lock true  # enables package-lock.json
npm update   # update it with latest versions
git add package-lock.json # add it to version control

# conduct all test and vulnerability checks

Keep open-source dependencies of a plugin to a minimum

OpenSSF Scorecard

capire states that end-of-chain projects have to run vulnerability checks for every open-source package they use directly or inherit transitively from reuse packages, and that providers of reuse packages keep open-source usage to a reasonable minimum. It names keeping third-party integrations optional, as express.js does, as one approach. OpenSSF Scorecard offers automated checks for evaluating a project before depending on it, among them whether it is maintained, declares a licence, has a security policy and uses dependency-update tooling.

Software bill of materials for npm and Maven

npm sbomCycloneDX Maven plugincds-services-bom

npm documents npm sbom, which generates a Software Bill of Materials of a project's dependencies in SPDX or CycloneDX format. For Maven builds, the CycloneDX Maven plugin generates a CycloneDX SBOM aggregating all direct and transitive dependencies. On the Java side, capire describes the cds-services-bom, a bill-of-materials POM imported into dependencyManagement to keep the versions of all CAP modules in sync.

Declaring a licence: package.json, LICENSE and REUSE

SPDXREUSEreuse lint

npm documents the package.json license field as an SPDX identifier or SPDX expression, with "SEE LICENSE IN <filename>" for a custom licence. SAP's repository template, the base of every repository on github.com/SAP, ships a LICENSE (Apache 2.0 by default), a LICENSES directory and REUSE metadata. cap-js plugins follow it: @cap-js/audit-logging declares "license": "Apache-2.0" and a REUSE.toml annotating every file with its copyright text and SPDX-License-Identifier. The REUSE tutorial describes the three steps: provide licences in LICENSES/, add copyright and licence information per file, and confirm compliance with reuse lint.

tomlAdapted from github.com ↗

version = 1
SPDX-PackageName = "audit-logging"
SPDX-PackageDownloadLocation = "https://github.com/cap-js/audit-logging"

[[annotations]]
path = "**"
precedence = "aggregate"
SPDX-FileCopyrightText = "2023 SAP SE or an SAP affiliate company and audit-logging contributors."
SPDX-License-Identifier = "Apache-2.0"

Contribution terms: Apache 2.0 and the DCO

DCO

SAP's organisation-wide CONTRIBUTING asks contributors to comply with the project licence and accept a Developer Certificate of Origin, requested automatically with the first pull request, using the Linux Foundation's standard DCO text; it also links a separate guideline for contributions made with generative AI. The CONTRIBUTING files of cap-js and cap-js-community plugins state the same rule: contributions are licensed under Apache 2.0 and contributors accept the DCO.

Community health files: code of conduct and security policy

GitHub uses default community health files from an organisation's public .github repository for any repository that has no file of that type. The cap-js, cap-java and cap-js-community organisations each keep a CODE_OF_CONDUCT.md and a SECURITY.md in their .github repository, and cap-js plugin CONTRIBUTING files point to the SAP Open Source Code of Conduct. SAP's repository template README tells maintainers to replace its placeholders and links the REUSE API for licensing details.

Where CAP plugins live and who supports them

capire's plugin page lists @cap-js-scoped plugins as created and maintained in shared ownership of CAP and other SAP development teams, and points to the cap-js-community organisation and bestofcapjs.org for community plugins. It states that plugins by external parties such as the CAP JS community are out of scope for SAP incidents. SAP's GitHub profile lists cap-js, cap-java, cap-js-community and capire as the CAP organisations.

06Security

What CAP's documentation and its projects state about security, with the pages to read. A project's SECURITY.md, where it has one, says how to report a vulnerability.

Secure by default, and what stays the application's job

capire's Product Security guide lists CAP's secure defaults: no credentials needed to protect communication, all endpoints authenticated when bound to XSUAA, isolated multitenancy, and INFO-level logging. Index page, mock users and the Java developer dashboard are development-only features that the production profile turns off, and capire warns against enabling them manually in production. It also states that authorizations and sizing need application-specific configuration, and advises checking security settings with automated integration tests.

Authorization is declared in CDS and enforced by the generic providers

capire states that CDS services have no access control by default, so authenticated users can reach all entities, and that applications must implement proper authorization. Restrictions are declared with @requires on services and @restrict privileges (grant, to, where) on entities and actions, enforced by CAP's generic service providers. A plugin-provided service that is only meant for in-process use can be annotated @protocol: 'none', so that no protocol adapter exposes it.

entity Orders @(restrict: [
    { grant: 'READ', to: 'Auditor', where: (AuditBy = $user) }
  ]) {/*...*/}

Privileged users bypass authorization checks

In Node.js, cds.User.Privileged and the ready-made cds.User.privileged run a transaction that bypasses authorization checks when consuming a local service, and capire shows it for writing a request log from a before handler. In production, capire states that services without @restrict or @requires implicitly get @requires: 'authenticated-user', which can be switched off with cds.requires.auth.restrict_all_services: false. Java's mock users include a privileged flag whose user passes all authorization checks.

this.before('*', function (req) {
  const user = new cds.User.Privileged
  return this.tx({ user }, tx => tx.run(
    INSERT.into('RequestLog').entries({
      url: req._.req.url,
      user: req.user.id
    })
  )
})

Untrusted input: CQL, constraints, CSRF

capire states that CQL statements become prepared statements, so parameter values from user input cannot inject SQL, but injection is still possible when the query structure (target entity, columns) comes from user input, which then needs validation such as a positive list. Declarative constraints (@mandatory, @assert) express input validation in the model. For CSRF, capire states that the Application Router enforces x-csrf-token protection, so CAP services that keep no client session do not handle it themselves.

const entity = <from user input>
const column = <from user input>
validate(entity, column) // for example, by comparing with positive list
SELECT.from(entity).columns(column)

Secrets come from bindings, never from the package

cds bindcds.envSAP Credential Store

capire states that a CAP application does not need to manage keys, tokens or passwords, and that CAP stores none but relies on platform injection or destinations; for secrets that must be stored it points to SAP Credential Store. cds.env reads credentials from the process environment and VCAP_SERVICES bindings, and .cdsrc-private.json is for private settings that are not committed. cds bind saves only where credentials can be obtained, not the credentials. A plugin's own package.json cds section is auto-configuration shipped to every consumer, and npm's files field and .npmignore control what goes into the published package.

Personal data and audit logging

@cap-js/audit-logging

capire describes annotating entities and elements that hold personal data with @PersonalData (EntitySemantics, DataSubjectRole, FieldSemantics, IsPotentiallyPersonal, IsPotentiallySensitive), which drives audit logging, personal data management and retention. The @cap-js/audit-logging plugin logs changes to personal data and reads of sensitive data automatically, and brings its own default configuration as a CDS plugin package. Its AuditLogService can also be used for custom events such as security events.