@sap/mdk-tools

CLI tools for the mobile development kit (MDK) — build, deploy, migrate, and validate MDK metadata projects from the command line.

Table of Contents

• Installation
• Commands at a Glance
• Usage
  • mdk build
  • mdk deploy
  • mdk migrate
  • mdk validate
• License

Installation

Prerequisites

| Requirement | Notes | |-------------|-------| | Node.js ≥ 22.13.1, npm ≥ 10.9.2 | LTS recommended | | Space Developer role | Required for CF deployments | | Cloud Foundry CLI + cf login | Required for all CF targets | | MTA Build Tool | Required for web (cf) deployments | | MultiApps CF CLI plugin | Required for web (cf) deployments | | CF HTML5 Applications Repository CLI plugin | Required for web (cf) deployments |

Install the CF plugins:

cf install-plugin -r CF-Community "multiapps"
cf install-plugin -r CF-Community "html5-plugin"

Install mdk-tools globally:

npm install -g @sap/mdk-tools

Commands at a Glance

| Command | Purpose | |---------|---------| | mdk build | Bundle an MDK metadata project to js, zip, or source | | mdk deploy | Deploy a project to Mobile Services or an HTML5 repository on CF | | mdk migrate | Migrate project metadata to the latest schema version | | mdk validate | Validate a project against the MDK language schema |

Usage

mdk build

Bundles an MDK metadata project using webpack.

mdk build --target <target> [options]

Targets

| Target | Output | Description | |--------|--------|-------------| | js | bundle.js, bundle.js.map | Use to update a local run project | | zip | uploadBundle.zip | Upload to Mobile Services | | source | source zip | Multi-tenant extension scenario |

Options

| Option | Description | |--------|-------------| | --target <target> | Build target: js, zip, or source | | --project <folder> | Path to the MDK metadata project (defaults to current directory) | | --externals <module…> | Space-separated npm modules to exclude from the bundle | | --filters <path…> | Space-separated project paths/files to exclude from the bundle | | --devtool <style> | Source map style, e.g. source-map | | --bundle-definition-path <folder> | Custom definition factory path (defaults to the out folder in mdk-tools) |

Built-in externals (always excluded): @nativescript/core, mdk-core.
Built-in filters (always excluded): /Web/.
Build results are placed in the .build folder under the project.

Examples

# Build a local run bundle
mdk build --target js

# Build an upload bundle for a specific project
mdk build --target zip --project /path/to/Your-MDK-Project

# Build a source zip
mdk build --target source --project /path/to/Your-MDK-Project

# Exclude a third-party library from the bundle
mdk build --target zip --externals "@nativescript/geolocation"

# Exclude project folders from the bundle
mdk build --target zip --filters "/FolderA/" "/FolderB/readme.txt"

# Enable source map debugging
mdk build --target zip --devtool "source-map"

mdk deploy

Deploys an MDK metadata project to SAP BTP Cloud Foundry. Requires an active CF login (cf login).

mdk deploy --target <target> [options]

Targets

| Target | Description | |--------|-------------| | mobile | Deploy to Mobile Services on Cloud Foundry (runs as a mobile application) | | cf | Deploy to the HTML5 repository on Cloud Foundry (runs as a web application) |

Common options

| Option | Description | |--------|-------------| | --target <target> | Deploy target: mobile or cf | | --name <app-id> | Application ID (Mobile Services) or application name (HTML5 repo). Falls back to MobileService:AppId or CF:Deploy:Name in .project.json. | | --project <folder> | Path to the MDK metadata project (defaults to current directory) | | --externals <module…> | Space-separated npm modules to exclude from the bundle | | --devtool <style> | Source map style, e.g. source-map |

Deploy to Mobile Services (--target mobile)

Bundles the project, uploads the bundle to Mobile Services, and publishes it. The --name option is the application ID in Mobile Services. If omitted, the command reads MobileService:AppId from .project.json in the project root (set automatically when exporting from SAP Business Application Studio). Projects exported from SAP Web IDE do not include this key — --name is required in that case.

# Standard deploy
mdk deploy --target mobile --name "com.mdk.myapp" --project /path/to/Your-MDK-Project

# Show QR code for onboarding after deploy
mdk deploy --target mobile --name "com.mdk.myapp" --project /path/to/Your-MDK-Project --showqr

# Use source maps for debugging
mdk deploy --target mobile --name "com.mdk.myapp" --devtool "source-map"

# Exclude a third-party library
mdk deploy --target mobile --name "com.mdk.myapp" --externals "@nativescript/geolocation"

# Deploy a pre-built bundle zip (e.g. exported from SAP Business Application Studio)
mdk deploy --target mobile --name "com.mdk.myapp" --zip Your-MDK-bundle.zip

# Deploy a source zip (multi-tenant base project scenario)
mdk deploy --target mobile --name "com.mdk.myapp" --zip Your-MDK-source.zip --source

Additional mobile options

| Option | Description | |--------|-------------| | --showqr | Display a QR code for onboarding after deploy | | --preview | Use the Mobile Services preview runtime | | --zip <file> | Deploy a pre-built bundle or source zip instead of building from source | | --source | Treat the zip as a source zip (multi-tenant scenario) | | --create | Create the mobile application if it does not yet exist |

Deploy to HTML5 Repository (--target cf)

Bundles the project, builds an MTA project from it, and deploys the result to the HTML5 repository. The --name option is the application name in SAP BTP cockpit. If omitted, the command reads CF:Deploy:Name from .project.json (set automatically when exporting from SAP Business Application Studio). Projects exported from SAP Web IDE do not include this key — --name is required in that case.

# Standard web deploy
mdk deploy --target cf --name "MyWebApplication" --project /path/to/Your-MDK-Project

# Use a preview web runtime
mdk deploy --target cf --name "MyWebApplication" --runtime preview

# Use a custom runtime URL
mdk deploy --target cf --name "MyWebApplication" --runtime "https://your-runtime-url"

# Exclude a third-party library
mdk deploy --target cf --name "MyWebApplication" --externals "@nativescript/geolocation"

Additional cf options

| Option | Description | |--------|-------------| | --runtime <value> | Runtime to use: preview, production, or a custom https:// URL | | --force | Replace the entire MTA on redeploy |

Deploy to NEO (legacy)

Note: SAP BTP NEO is end-of-life. New projects should target Cloud Foundry.

mdk deploy --target mobile --name "com.mdk.myapp" --project /path/to/Your-MDK-Project --neo

Use --adminApi, --user, and --pwd to skip interactive prompts. If omitted, the command reads adminApi and user from .project.json and prompts for the password.

mdk migrate

Migrates an MDK metadata project to the latest schema version. Both JSON metadata files and JavaScript rule files are migrated. Use --preview to do a dry run that lists affected files without writing any changes.

mdk migrate --project <folder> [options]

Options

| Option | Description | |--------|-------------| | --project <folder> | Path to the MDK metadata project | | --target-version <version> | Migrate to a specific schema version instead of the latest. Run mdk migrate --help for the versions bundled with this release. | | --preview | List files that would be migrated without performing the migration | | --log-file <file> | Write migration output to a file (created automatically if absent) |

Examples

# Migrate to the latest schema version
mdk migrate --project /path/to/Your-MDK-Project

# Preview which files would be migrated (dry run)
mdk migrate --project /path/to/Your-MDK-Project --preview

# Migrate to a specific schema version
mdk migrate --project /path/to/Your-MDK-Project --target-version 6.3

# Write migration output to a log file
mdk migrate --project /path/to/Your-MDK-Project --log-file /path/to/migration.log

mdk validate

Validates an MDK metadata project against the MDK language schema. Exits with 0 when there are no errors and with a non-zero code when issues are found — making it suitable for use as a git pre-commit hook. Warnings are not included in the exit code unless --show-warnings is set.

mdk validate --project <folder> [options]

Options

| Option | Description | |--------|-------------| | --project <folder> | Path to the MDK metadata project | | --log-file <file> | Write validation output to a file | | --log-level <number> | Minimum log level: 0 Debug, 1 Info (default), 2 Warn, 3 Error | | --show-warnings | Include warnings in the validation result and let them affect the exit code (default: false) | | --config-file <file> | JSON file with validation exclusion rules. Defaults to .project.json in the project root. |

Exclusion config format (in .project.json or a custom --config-file):

{
  "validation": {
    "exclude": {
      "ui": [
        "#Page:myFormCell",
        "#Control:myControl"
      ],
      "i18n": [
        "test"
      ]
    }
  }
}

Examples

# Validate with default settings
mdk validate --project /path/to/Your-MDK-Project

# Validate and write results to a log file, errors only
mdk validate --project /path/to/Your-MDK-Project --log-file /path/to/validate.log --log-level 3

# Include warnings in the result
mdk validate --project /path/to/Your-MDK-Project --show-warnings

# Use a custom exclusion config
mdk validate --project /path/to/Your-MDK-Project --config-file /path/to/config.json

License