Getting Started

Jumpstart & Grow as You Go...

• Initial Setup
  • Node.js and cds-dk
  • Java and Maven
  • Git and GitHub
  • Visual Studio Code
• Command Line Interface
  • The cds command
  • cds version
• Jumpstart Projects
  • cds init
  • cds watch
• Grow as You Go...
  • cds add
  • cds up
• Stay up to Date!
• Next: Bookshop

Initial Setup

A most minimalistic setup needs CAP's cds-dk installed, which in turn requires Node.js. Add optional setups for Java, GitHub, and Visual Studio Code, as appropriate, and as outlined below.

On macOS (and Linux), we recommend using Homebrew, and run the commands in the subsequent sections in your terminal to get everything set up.

bash -c "$( curl https://raw.githubusercontent.com/homebrew/install/HEAD/install.sh )"

Alternative setup (required on Windows) ...

Instead of using Homebrew – which is not available on Windows –, you can manually download and install the required packages from their respective websites:

Package	Install from	Remarks
Node.js	https://nodejs.org	required
Java	https://sapmachine.io	optional
Git	https://git-scm.com	optional
VS Code	https://code.visualstudio.com	+ recommended extensions
SQLite	https://sqlite.org/download.html	required on Windows

Then install CAP's cds-dk globally:

npm add -g @sap/cds-dk

Node.js and cds-dk

brew install node      # Node.js latest LTS
npm i -g @sap/cds-dk   # CAP's cds-dk

Java and Maven

brew install sapmachine-jdk
brew install maven

Git and GitHub

brew install git       # Git CLI
brew install gh        # GitHub CLI
brew install github    # GitHub Desktop App

Visual Studio Code

brew install --cask visual-studio-code            # VS Code itself

code --install-extension sapse.vscode-cds         # for .cds models
code --install-extension mechatroner.rainbow-csv  # for .csv files
code --install-extension qwtel.sqlite-viewer      # for .sqlite files
code --install-extension humao.rest-client        # for REST requests
code --install-extension dbaeumer.vscode-eslint   # for linting

code --install-extension oracle.oracle-java       # for Java
code --install-extension vscjava.vscode-maven     # for Maven

You can of course also use other IDEs or editors of your choice, such as IntelliJ IDEA, for which we also provide support. Yet we strongly recommend Visual Studio Code for the best experience with CAP.

Command Line Interface

The cds command

Run the cds command in your terminal to verify your installation and see an overview of available commands, as shown below:

cds

SYNOPSIS

  cds <command> [ <args> ]
  cds <src>  =  cds compile <src>
  cds        =  cds help

COMMANDS

  i | init        jumpstart cap projects
  a | add         add facets to projects to grow as you go
  s | serve       run your services in local server
  w | watch       run with auto-restarts on changes
    | mock        mock a single service
  r | repl        read-eval-event loop
  e | env         inspect effective configuration
  c | compile     compile cds models to various outputs
  b | build       prepare for deployment
  d | deploy      deploy to databases or cloud
    | up          one stop build and deploy to cloud
  v | version     get detailed version information
  ? | help        get detailed usage information

Learn more about each command using:
cds <cmd> --help
cds help <cmd>

Use cds help to get help on any command.

cds version

Use cds version to check your installed versions of cds-dk , as well as your project's local dependencies, with an output similar to this:

cds version

@sap/cds-dk:  9.6.1    /opt/homebrew/lib/node_modules/@sap/cds/dk
npm root -l:           ~/cap/bookshop/node_modules
npm root -g:           /opt/homebrew/lib/node_modules
Node.js:      24.12.0  /opt/homebrew/bin/node

Jumpstart Projects

cds init

Use cds init to jumpstart CAP projects, which creates a project root folder with a default layout as shown below:

cds init bookshop
cd bookshop

bookshop/           # the project's root folder
├─ app/             # UI-related content
├─ srv/             # Service-related content
├─ db/              # Domain models and database-related content
└─ readme.md        # Project readme file

Convention over configuration

CAP uses defaults for many things you'd have to configure in other frameworks. The idea is that things just work out of the box, with zero configuration. While you can override these defaults, of course, you should not do so, but rather stick to the defaults, for the sake of simplicity.

cds watch

We can run cds watch to start a server, which would respond like this:

cds watch

  No models found in db/,srv/,app/,app/*.
  Waiting for some to arrive...

Let's feed it with a simple service definition by running that in a secondary terminal, which adds a simple service definition as shown below:

cds add tiny-sample

srv/cat-service.cds

service CatalogService {
  entity Books {
    key ID:Integer; title:String; author:String;
  }
}

cds watch would react automatically with some output containing this:

[cds] - loaded model from 1 file(s):
  srv/cat-service.cds
[cds] - connect to db > sqlite { url: ':memory:' }
[cds] - serving CatalogService { at: ['/odata/v4/catalog'] }
[cds] - server listening on { url: 'http://localhost:4004' }

Served out of the box

Et voilà! Your first CAP service is up and running, with automatically bootstrapped in-memory database, and a full-fledged OData service, generically serving requests like that: http://localhost:4004/odata/v4/catalog/Books

Grow as You Go...

When your project evolves, you'd use cds add to add features and facets as needed, for example, to add initial data, Java-specific setups, or deployment options, as outlined below. And finally, use cds up to build and deploy your project in one go.

cds add

Use cds add to grow your project as you go:

cds add data
cds add nodejs
cds add java

Use cds add to add deployment options:

cds add hana
cds add xsuaa
cds add ias
cds add multitenancy
cds add mta
cds add kyma
cds add github-actions

cds up

Use cds up to build and deploy your project in one go:

cds up
cds up --to cf
cds up --to k8s

Stay up to Date!

Staying up to date is crucial to receive important security fixes.

In order to benefit from the latest features and improvements, as well as receiving crucial security fixes, it's of utter importance to stay up to date with latest releases of CAP. Regularly run the following commands to do so.

Keep your development environment up to date:

brew upgrade
npm upgrade --global

Keep your project dependencies up to date:

# within your project folder
npm upgrade

Use npm outdated to check which dependencies are outdated before upgrading.

Do not use pinned versions

For such upgrades to work, always use open version ranges in your project dependencies – with a leading caret, as in ^9.7.0, and as shown below –, combined with package-lock.json, and npm ci for repeatable builds and deployments.

package.json

  "dependencies": {
    "@sap/cds": "9.7.0",   // DON'T use pinned versions
    "@sap/cds": "^9.7.0",  // DO allow new minor versions
    ...
  }

Automate dependency updates

Consider using tools like Dependabot or Renovate to automate dependency updates for you. These tools automatically open pull requests in your Git repositories whenever new versions of your dependencies are released. They are also highly recommended for managing Maven dependencies in CAP Java projects.

Next: Bookshop

Continue with The Bookshop Sample for a step-by-step walkthrough of the most common development tasks in CAP projects. Then explore the Core Concepts and Key Features of CAP, before going on to the other Learning Sources within this documentation, or outside.