sap-cap-nodejs-dev

SAP CAP Node.js Development Skill

1. Scope guardrails (read first, every time)

Before doing anything, classify the request:

1. CAP Node.js development? → proceed.
2. UI / frontend work? → refuse: "This skill is SAP CAP Node.js only. UI/frontend

implementation (Fiori custom code, UI5, React, Vue, plain HTML/CSS/JS) is out of scope. CAP-side UI annotations in .cds are in scope; the UI app itself is not."

1. Backend in another language or stack? → refuse: "This skill is SAP CAP Node.js only.

Java CAP, Spring, plain Node/Express, NestJS, Python, Go, .NET, and non-CAP microservices are out of scope."

1. Non-CAP architecture (custom OData/REST/GraphQL outside CAP)? → refuse with the same

message. CAP must be the framework (@sap/cds + cds.ApplicationService, or documented @cap-js/* plugins).

1. Uses a private / protected / deprecated API? → refuse and propose the documented public

alternative. If none exists, say so and stop.

When in doubt, ask the user to confirm the request fits the CAP Node.js scope before writing code.

2. Public-API rule

• Only import from documented, stable entry points: @sap/cds, @sap/cds/common,

@cap-js/sqlite, @cap-js/hana, @cap-js/postgres, @cap-js/attachments, @cap-js/audit-logging, @cap-js/change-tracking, @cap-js/telemetry, @cap-js/graphql, @cap-js/mcp-server, @sap/cds-mtxs.

• Never reach into @sap/cds/lib/, node_modules/@sap/cds/lib/, or any path the docs do not

describe.

• Never use methods/options that the changelog flags as deprecated or removed.
• Never rely on undocumented behavior of a documented API ("it happens to work today").
• If the public surface cannot do what the user wants, say so — do not fall back to internals.

3. Domain-first / Less code → Less mistakes

"Every line of code not written is free of errors." — SAP Capire

https://cap.cloud.sap/docs/get-started/features#less-code-%E2%86%92-less-mistakes

CAP captures domain knowledge and intent declaratively ("What, not How"). This skill follows that principle: prefer the CDS model, annotations, projections, and CAP's generic providers over hand-written handlers and SQL.

CAP's generic providers already handle: CRUD, nested documents, drafts, media, search, pagination, sorting, authentication / authorization, localization, input validation, auto-generated keys, concurrency control. Do not re-implement these in code.

Decision order when adding a new behavior — only drop to the next step if the previous one cannot express it:

1. Schema — types, associations, compositions, aspects from @sap/cds/common.
2. Annotations — @mandatory, @assert.*, @readonly, @insertonly, @requires,

@restrict, @cds.persistence., @cds.search, @odata.draft.enabled, @odata.etag, @UI..

1. Views / projections — expose subsets, filter rows, compute fields, join entities in CDS.
2. Status Flows — when the behavior is a state machine (row walks through named states),

use @flow.status + @from + @to. CAP validates the entry state and writes the target state. See [references/status-flow.md](references/status-flow.md). ⚠ Currently Gamma in capire — only adopt with explicit team acceptance.

1. CAP plugins — @cap-js/attachments, @cap-js/audit-logging, @cap-js/change-tracking,

@cap-js/telemetry, @cap-js/graphql, etc.

1. Concurrency control — @odata.etag (via managed.modifiedAt) for optimistic locking;

cds.tx(req) with .forUpdate() on the base entity when invariants span multiple rows. See [references/concurrency-control.md](references/concurrency-control.md) and [references/race-conditions.md](references/race-conditions.md).

1. Event handlers (last resort) — only for behavior that is genuinely business logic and

cannot be expressed declaratively by steps 1–6. Never re-implement what @from/@to, @odata.etag, @assert.*, @requires, or a projection already does for free.

Full explanation, examples, and the "is this PR domain-first?" checklist: [references/domain-first.md](references/domain-first.md).

4. Where to put what

| Concern | Where it lives | |--------------------------------------|--------------------------------------------------| | Keys, types, relationships | db/schema.cds | | Required / range / format / unique | CDS @mandatory, @assert. | | Computed fields | CDS calculated elements (= expr, stored) | | Exposed subset / filtered rows | srv/.cds projection | | Joins across entities | CDS view (as select from … join …) | | Authorization (who can do what) | @requires, @restrict | | Fiori UI shape | @UI., @Common. annotations in CDS | | i18n texts | _i18n/ .properties files | | Seed / reference data | CSV in db/data/ | | Cross-cutting concerns | @cap-js/ plugin (configured, not coded) | | Genuine business logic | Node.js event handler in srv/.js |

The app/ folder (UI applications) is out of scope for this skill.

5. Project structure

project/
├── app/              # UI content                            ← out of scope
├── srv/              # Service definitions (.cds, .js/.ts)  ← in scope
├── db/               # Data models, views, seed data         ← in scope
│   ├── schema.cds
│   └── data/
├── package.json      # Dependencies + CDS config             ← in scope
└── .cdsrc.json       # CDS configuration (optional)

6. Quick start (minimal)

npm i -g @sap/cds-dk @sap/cds-lsp
cds init <project-name>
cds watch

Add capabilities as needed (cds add hana | sqlite | xsuaa | mta | multitenancy | typescript). Full CLI reference: [references/cli-complete.md](references/cli-complete.md) and [references/tools-complete.md](references/tools-complete.md).

Domain-first starter — model first, expose with a projection, no handler needed:

// db/schema.cds
using { cuid, managed } from '@sap/cds/common';
namespace my.bookshop;

entity Books : cuid, managed {
  title : String(111) @mandatory;
  stock : Integer     @assert.range: [0, 99999];
  price : Decimal(9,2);
}

// srv/catalog-service.cds
using { my.bookshop as my } from '../db/schema';

@requires: 'authenticated-user'
service CatalogService {
  @readonly entity Books as projection on my.Books where stock > 0;
}

That's a working, validated, authorized, searchable OData service — zero JS.

For more entity / projection / view / annotation patterns, see the templates folder and the references below.

7. MCP integration

The skill integrates with the official CAP MCP server, giving the agent live access to the project's compiled CSN model and CAP docs:

• search_model — fuzzy search entities, services, actions, and relationships in the CSN.
• search_docs — semantic search through CAP documentation.

Setup: [references/mcp-integration.md](references/mcp-integration.md). Use cases: [references/mcp-use-cases.md](references/mcp-use-cases.md).

8. Bundled resources (index)

Philosophy & rules

• [domain-first.md](references/domain-first.md) — "Less code → less mistakes", decision order,

annotations and views to prefer over code, anti-patterns.

• [best-practices.md](references/best-practices.md) — full DO / DON'T, code smells, review

checklist.

• [security-audit.md](references/security-audit.md) — audit matrix against the AI-agent /

supply-chain attack surface (prompt injection, MCP poisoning, supply chain, eval, SSRF, credential leakage, etc.) and the standing rules the skill enforces on agent