Skip to main content
  • Getting-started
  • 2 minutes

Dynatrace App Toolkit

A powerful CLI toolkit for creating, developing, and deploying Dynatrace Apps. Streamline your development workflow.

Create
Step 1

Create a new Dynatrace app from a template

npx dt-app create
Develop
Step 2

Start development server to see changes with hot replacement.

npx dt-app dev
Deploy
Step 3

Deploy your app to your Dynatrace environment

npx dt-app deploy

Getting started

Tip

Updating from Dynatrace App Tookit v0.x to v1.x needs a few manual steps for your older workspaces. Please check out: Migrating from v0.x to v1.x

Dynatrace App Toolkit requirements

To use the Dynatrace App Toolkit, ensure your environment meets the following prerequisites:

  • NodeJS version 20 must be installed on your local machine.
  • Access to the following URLs:
  • Local port range 3000-3005 must be available for local app development. Alternatively, configure a custom port.
  • Local port 30000 must be available for local app function execution.
  • Local port 5343 must be available for the SSO authentication process. If the port is unavailable, the toolkit will try the next port.
  • Access to localhost.
  • Access to a command line interface (for example, PowerShell, cmd, Linux terminal, macOS terminal) and the ability to execute scripts.
  • Read/write access to the directory where your app is located.
  • Access to read app templates on github.com.

Command reference

Complete reference for all available commands and their options.

Create and initialize

Everything related to starting a new project or adding new components:

dt-app create

Create new Dynatrace App.

ArgumentDescription
[name]The name of the app.
OptionDescription
--cwd [dir]Set the current working directory.
--dry-runDo not write any changes to the file system.
--environment-url <name>Specify your environment.
--no-colorTerminal output renders without color.
--no-gitDo not initialize a git repository.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--skip-installDo not install dependencies after initialization.
--template [name]Choose the template to generate the app from.
--template-dir <dir>Specify the directory that contains the template your app should be created from.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%"

dt-app action create

Create a custom workflow action.

ArgumentDescription
[name]The name of the action.
OptionDescription
--cwd [dir]Set the current working directory.
--dry-runDo not write any changes to the file system.
--no-colorTerminal output renders without color.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--skip-testsDo not generate test files.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%"

dt-app function create

Create an app function.

ArgumentDescription
[name]The name of the function.
OptionDescription
--cwd [dir]Set the current working directory.
--dry-runDo not write any changes to the file system.
--generate-testsGenerate test files for functions without tests.
--no-colorTerminal output renders without color.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--skip-testsDo not generate test files.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%"

Develop and operate

Commands used during development, testing, and maintaining:

dt-app dev

Start the development server.

OptionDescription
--cwd [dir]Set the current working directory.
--environment-url [url]Set the target environment for app deployment.
--host [name]The host IP to bind the dev server on.
--no-colorTerminal output renders without color.
--no-live-reloadDisable file watching and browser live reloading
--no-openDo not open the browser with the dev server.
--no-type-checkSkip type checking.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%"
-o, --openOpen the browser with the dev server.
-p, --port <number>The port where the files should be served.
-w, --show-warningsDisplay build warnings.

dt-app build

Build the app and analyze the bundle.

OptionDescription
--cwd [dir]Set the current working directory.
--no-colorTerminal output renders without color.
--no-type-checkSkip type checking.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%"

dt-app update

Update @dynatrace-scoped packages and the App Toolkit to the latest version and apply automatic migrations.

ArgumentDescription
[packages...]The packages that should be updated.
OptionDescription
--cwd [dir]Set the current working directory.
--no-colorTerminal output renders without color.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--skip-installDo not install dependencies after migrations.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%"
--yes[DEPRECATED use --non-interactive instead] Update all outdated packages without prompt for confirmation.
-i, --interactiveChoose the packages you want to update manually.

dt-app migration execute

Execute a migration.

OptionDescription
--cwd [dir]Set the current working directory.
--from <currentVersion>The current version of the package.
--no-colorTerminal output renders without color.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--package <name>The name of the package.
--to <newVersion>The new version of the package.

dt-app analyze

Analyze app to check for valid app configurations, security issues and bundle statistics.

OptionDescription
--cwd [dir]Set the current working directory.
--no-colorTerminal output renders without color.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%"

dt-app info

Output detailed information about the App Toolkit and the environment.

OptionDescription
--cwd [dir]Set the current working directory.
--no-colorTerminal output renders without color.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%"

dt-app version

Print the version of the App Toolkit.

OptionDescription
--no-colorTerminal output renders without color.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.

dt-app help

Display a set of dt-app commands with a description.

No options available.

Deploy

Commands used for deploying your app:

dt-app deploy

Build and deploy your app to a configured Dynatrace environment.

OptionDescription
--cwd [dir]Set the current working directory.
--dry-runPerform a dry run without app deployment.
--environment-url [url]Set the target environment for app deployment.
--no-colorTerminal output renders without color.
--no-openDo not open the browser with the dev server.
--no-type-checkSkip type checking.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--sign-archiveSign the archive that will be deployed. If you need to specify a different signing endpoint, set the appropriate environment variables. For more details, refer to the Environment Variables section.
--skip-buildSkip the build before deploying.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%".

dt-app uninstall

Uninstall the app from the specified environment.

OptionDescription
--cwd [dir]Set the current working directory.
--dry-runDo not actually remove the app only perform a dry run.
--environment-url [url]Set the target environment for app deployment.
--no-colorTerminal output renders without color.
--no-openDo not open the browser with the dev server.
--non-interactiveRun in non-interactive mode. Throws error when a required command option or argument is missing.
--verbose [context]Output additional debug logs. Add optional context to filter. % at the end as wildcard possible. Example: "--verbose cli-%"

Configuration

Comprehensive guide to configuring your Dynatrace App Toolkit.

App Toolkit configurations

These configurations are set in the app.config.json in your Dynatrace App's workspace.

General options

Project related options.

OptionDescriptionTypeRequiredDefault Value
environmentUrlURL to the environment of the project.stringtrue

App options

Configures your app's appreance and more.

Example:

app.config.json
{
"app": {
"id": "my.app",
"name": "My App",
"description": "My description",
"version": "1.0.0"
}
}
OptionDescriptionTypeRequired
app.idThe unique identifier of the app. Limited to 50 characters. Must be an alphanumeric string containing only lowercase characters.stringtrue
app.nameThe name of the app. Limited to 40 characters.stringtrue
app.versionThe version of the app.stringtrue
app.descriptionThe description of the app. Limited to 80 characters.stringtrue
app.iconPath to the app icon, can either be a .svg (recommended) or .png file. An icon will be auto-generated if no icon path is set.stringfalse
app.hiddenHides the listing in the App Launcher. Useful for widget apps.booleanfalse
app.intentsThe list of app capabilities of handling the intents.IntentsDeclarationsfalse
app.pageTokensThe list of page tokens exposed by the app.Record<string,string>false
app.csp.font-srcThe font-src directive specifies valid sources for fonts loaded.DirectiveValue[]false
app.csp.img-srcThe img-src directive specifies valid sources of images and favicons.DirectiveValue[]false
app.csp.media-srcThe media-src directive specifies valid sources for loading media.DirectiveValue[]false
app.csp.style-srcThe style-src directive specifies valid sources for stylesheets.DirectiveValue[]false
app.csp.script-srcThe script-src directive specifies valid sources for JavaScript. This includes not only URLs loaded directly into script elements, but also things like inline script event handlers (onclick) and XSLT stylesheets which can trigger script execution.DirectiveValue[]false
app.scopesThe list of scopes required by the app.OAuthScope[]true
app.selfMonitoringAgentThe self monitoring agent urlstringfalse

Build options

Options for customizing the build process.

OptionDescriptionTypeRequiredDefault Value
build.modeWhether the build should be performed in production or development mode.'production' | 'development'false'production' when building and 'development' when using development server
build.sourceMapsOutput source maps for app code and libraries. If set to 'true', only source maps for app code is included. Source maps for node_modules are included if the option is set to 'all'. By default, the option is treated as 'all' for development and 'false' for builds.boolean | 'all'falseundefined
build.sourceRootLocation of source files.stringfalse./

Apps built with the Dynatrace App Toolkit currently target es2021. The target standard is not configurable and based on the state of the JavaScript ecosystem, required features and browser support.

Target
App UIes2021
Functionsesnext

Server options

Options for the development server.

Example:

app.config.json
{
server: {
open: false,
port: 3001,
host: '127.0.0.1',
showWarnings: true
}
}
OptionDescriptionTypeRequiredDefault Value
server.openWhether the project should be opened in the browser after startup or not.booleanfalsetrue
server.portPort where the app should be served.numberfalse3000
server.hostThe host IP to bind the dev server on.stringfalse127.0.0.1
server.showWarningsWhether build warnings should be displayed in the dev server or not.booleanfalsefalse
server.enableCSPWhether the dev server should add CSP headers to all requests. If true, the dev server will generate a set of default CSP Directives and add the custom CSP Directives to this set if specified. In local development, frame-src and frame-ancestors are always set to *booleanfalsetrue
server.https.certPath to cert in PEM formatstringtrue
server.https.keyPath to private key in PEM formatstringtrue

Assets

In the UI build configuration, it is possible to specify an array of assets. These assets are served statically by the development server and the app registry once the app is deployed.

Example:

app.config.json
build: {
ui: {
assets: [
{
glob: '**/*',
ignore: [],
input: 'src/assets',
output: 'assets',
},
];
}
}
OptionDescriptionTypeRequired
globPattern to specify which files inside the input folder are assets. Always use UNIX style separators.stringtrue
ignoreGlob Patterns to exclude. Always use UNIX style separators.string[]false
inputRelative (from root) or absolute path where the glob is executed.stringtrue
outputRelative path (from distDir) to directory where assets are copied to.stringtrue

NodeJS environment variables

For more information on how to set and read environment variables see the nodejs documentation.

Environment Variables

All variables to configure the toolkit for your CI.

NameDescriptionValuesDefault Value
DT_APP_PLATFORM_TOKENToken that is used for authenticating platform requests. You can use it when you want to skip the default authentication flow of the dt-app.
DT_APP_DISABLE_TELEMETRYDisables the sending of anonymous usage statistics and crash reports to dynatrace by setting it to 1.not set or 1not set
DT_APP_OAUTH_CLIENT_IDAlternative to setting oauthClientId in app.config.json. Should only be set as an environment variable in combination with DT_APP_OAUTH_CLIENT_SECRET to automate retrieving a SSO-Token. This can be useful for using the CLI in a CI-Pipeline.
DT_APP_OAUTH_CLIENT_SECRETClientSecret used for authenticating with the Dynatrace Platform.
DT_APP_ENVIRONMENT_URLAlternative to setting environmentUrl in app.config.json.
DT_APP_SIGN_URLCustom signing URL for fetching certificate.
DT_APP_OAUTH_SIGN_CLIENT_IDClient ID if you're authenticated to a different environment than the one you want to sign your archive for.
DT_APP_OAUTH_SIGN_CLIENT_SECRETClient secret if you're authenticated to a different environment than the one you want to sign your archive for.
DT_APP_HTTPS_PROXYConfigure a proxy server for the dt-app.http{s}://{<username>:<password>@}<host>:<port>not set

Telemetry

Help to improve Dynatrace’s features and performance. The Dynatrace App Toolkit automatically sends usage statistics and crash reports to Dynatrace anonymously.

To deactivate telemetry reporting for the current session:

export DT_APP_DISABLE_TELEMETRY=1

To deactivate telemetry reporting for your profile in all sessions

  1. Run:

    echo "export DT_APP_DISABLE_TELEMETRY=1" >>~/.profile
  2. Run:

    source ~/.profile

To deactivate telemetry reporting for your profile in all sessions for Windows

  1. Run:

    setx DT_APP_DISABLE_TELEMETRY 1
  2. Run:

    refreshenv (it might be necessary to restart your terminal)

Additional information

Supported file types

App functions cannot access the file system. The only file types that can be imported are: .js, .ts, .json, and .txt.

Logs

Toolkit logs are stored in the .dt-app/logs directory within your app workspace.

Migrating from v0.x to v1.x

The default sourceRoot is now set to ./, and all UI-related files are organized under the ./ui folder. To customize the sourceRoot, refer to the build.sourceRoot option.

  • Move UI files to ./ui

    v0.x structure:

      my-first-app/
    ├── src/
    │ ├── <UI files and folders>
    │ └── main.tsx
    ├── app.config.json
    └── tsconfig.json

    v1.x structure:

      my-first-app/
    - ├── src/
    - │ ├── <UI files and folders>
    - │ └── main.tsx
    + ├── ui/
    + │ ├── <UI files and folders>
    + │ ├── main.tsx
    + │ └── tsconfig.json
    ├── app.config.json
    - └── tsconfig.json
  • Special handling for app.config.ts/.cts

    If you use app.config.json, no changes are required.
    For configuration files with a .ts or .cts suffix, a default tsconfig.json is used from the .dt-app folder:

      my-first-app/
    ├── ui/
    │ └── tsconfig.json // Moved here during v0.x to v1.x migration
    └── app.config.ts

    To customize TypeScript settings, place a new tsconfig.json next to app.config.ts:

      my-first-app/
    ├── ui/
    │ └── tsconfig.json // Moved here during v0.x to v1.x migration
    ├── app.config.ts
    + └── tsconfig.json
  • Documents moved to sourceRoot

    v0.x:

      my-first-app/
    └── src/documents/

    v1.x (with default sourceRoot):

      my-first-app/
    - ├── src/documents/
    + └── documents/
  • Removed build option --prod

    In v1.0, the dt-app build command performs a production build by default.

Still have questions?
Find answers in the Dynatrace Community