Getting Started

Jumpstart & Grow as You Go...

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.

Preparation

On macOS, Linux and WSL (Windows Subsystem for Linux), we recommend using Homebrew, and run the commands in the subsequent sections in your terminal to get everything set up. We use multiline console commands to improve usability in Windows PowerShell. PowerShell will ask for confirmation when you paste these commands, adding an extra safety step.

macOSLinux / WSL

shell

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

shell

# install curl (required to get Homebrew) and git (required to run Homebrew)
sudo apt install curl git -y
bash -c "$( curl https://raw.githubusercontent.com/homebrew/install/HEAD/install.sh )"

Node.js and cds-dk

macOS / Linux / WSLWindows

shell

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

PowerShell

winget install --silent OpenJS.NodeJS.LTS

# Reload PATH from registry to access newly installed tools
$env:PATH = [Environment]::GetEnvironmentVariable("PATH","Machine") `
    + ";" + [Environment]::GetEnvironmentVariable("PATH","User")

npm i -g @sap/cds-dk  # install CAP's cds-dk globally
cds -v                # check cds version
# done

SQLite (Windows)

Windows

PowerShell

winget install --silent SQLite.SQLite

# Reload PATH from registry to access newly installed tools
$env:PATH = [Environment]::GetEnvironmentVariable("PATH","Machine") `
    + ";" + [Environment]::GetEnvironmentVariable("PATH","User")

sqlite3 -version
# done

Java and Maven

macOS / Linux / WSLWindows

shell

brew install sapmachine-jdk
brew install maven
mvn -version  # display Maven and Java versions

PowerShell

winget install --silent SAP.SapMachine.25.JDK

# Apache Maven is not available using winget so download it directly
$v="3.9.12"; `
$url="https://dlcdn.apache.org/maven/maven-3/$v/binaries/apache-maven-$v-bin.zip"; `
$mvnzip="$env:LOCALAPPDATA\maven.zip"; `
curl $url -o $mvnzip; `
tar -xf $mvnzip -C "$env:LOCALAPPDATA"; `
setx PATH "$env:PATH;$env:LOCALAPPDATA\apache-maven-$v\bin"; `
rm $mvnzip

# Reload PATH from registry to access newly installed tools
$env:PATH = [Environment]::GetEnvironmentVariable("PATH","Machine") `
    + ";" + [Environment]::GetEnvironmentVariable("PATH","User")

mvn -version  # display Maven and Java versions
# done

Git and GitHub

macOS / Linux / WSLWindows

shell

brew install git  # Git CLI (for completeness, already installed for Homebrew)
brew install gh   # GitHub CLI
git -v # display Git cli version

PowerShell

winget install --silent Git.Git
winget install --silent GitHub.cli

# Reload PATH from registry to access newly installed tools
$env:PATH = [Environment]::GetEnvironmentVariable("PATH","Machine") `
    + ";" + [Environment]::GetEnvironmentVariable("PATH","User")

git -v # display Git cli version
# done

macOSLinux / WSLWindows

shell

brew install github    # GitHub Desktop App

shell

# Github-Desktop on Homebrew is only supported for macOS
GHD_VERSION="3.3.12"
GHD_HOST="https://github.com/shiftkey/desktop/releases/download"

curl -L ${GHD_HOST}/release-${GHD_VERSION}-linux1/
GitHubDesktop-linux-amd64-${GHD_VERSION}-linux1.deb -o github-desktop.deb

sudo apt install ./github-desktop.deb
rm ./github-desktop.deb

PowerShell

winget install --silent GitHub.GitHubDesktop

Visual Studio Code

macOSLinux / WSLWindows

shell

brew install --cask visual-studio-code # VS Code itself
code -v # display VS Code's version

bash

# VS Code on Homebrew is only supported for macOS
sudo snap install --classic code
code -v # display VS Code's version

PowerShell

winget install --silent Microsoft.VisualStudioCode

# Reload PATH from registry to access newly installed tools
$env:PATH = [Environment]::GetEnvironmentVariable("PATH","Machine") `
    + ";" + [Environment]::GetEnvironmentVariable("PATH","User")

code -v # display VS Code's version
# done

Visual Studio Code Proposed Extensions

shell

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

shell

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.

Alternative setup ...

You can also 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

Command Line Interface

The `cds` command

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

shell

cds

zsh

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:

shell

cds version

zsh

@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:

shell

cds init bookshop
cd bookshop

zsh

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:

shell

cds watch

zsh

  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:

shell

cds add tiny-sample

srv/cat-service.cds

cds

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

cds watch would react automatically with some output containing this:

shell

[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:

shell

cds add data
cds add nodejs
cds add java

Use cds add to add deployment options:

shell

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:

shell

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:

shell

brew upgrade
npm upgrade --global

Keep your project dependencies up to date:

shell

# 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

jsonc

  "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.

SAP HANA

Authentication

Data Privacy

Getting Started ​

Initial Setup ​

Preparation ​

Node.js and cds-dk ​

SQLite (Windows) ​

Java and Maven ​

Git and GitHub ​

Visual Studio Code ​

Visual Studio Code Proposed Extensions ​

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 ​

Getting Started

Initial Setup

Preparation

Node.js and cds-dk

SQLite (Windows)

Java and Maven

Git and GitHub

Visual Studio Code

Visual Studio Code Proposed Extensions

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