• 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

Start with a guide

Create your first Dynatrace app with our 5 minutes Quickstart

Start with a tutorial

Learn how to create your first Dynatrace app, query data from Grail and deploy it to an environment of your choice

Tip

Updating from Dynatrace App Toolkit 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:
  • https://dt-cdn.net/
  • https://registry.npmjs.org/
  • Access to your desired Dynatrace environment.
• 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.

Argument	Description
[name]	The name of the app.

Option	Description
--cwd [dir]	Set the current working directory.
--dry-run	Do not write any changes to the file system.
--environment-url <name>	Specify your environment.
--no-color	Terminal output renders without color.
--no-git	Do not initialize a git repository.
--non-interactive	Run in non-interactive mode. Throws error when a required command option or argument is missing.
--skip-install	Do 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.

Argument	Description
[name]	The name of the action.

Option	Description
--cwd [dir]	Set the current working directory.
--dry-run	Do not write any changes to the file system.
--no-color	Terminal output renders without color.
--non-interactive	Run in non-interactive mode. Throws error when a required command option or argument is missing.
--skip-tests	Do 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.

Argument	Description
[name]	The name of the function.

Option	Description
--cwd [dir]	Set the current working directory.
--dry-run	Do not write any changes to the file system.
--generate-tests	Generate test files for functions without tests.
--no-color	Terminal output renders without color.
--non-interactive	Run in non-interactive mode. Throws error when a required command option or argument is missing.
--skip-tests	Do 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.

Option	Description
--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-color	Terminal output renders without color.
--no-live-reload	Disable file watching and browser live reloading
--no-open	Do not open the browser with the dev server.
--no-type-check	Skip type checking.
--non-interactive	Run 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, --open	Open the browser with the dev server.
-p, --port <number>	The port where the files should be served.
-w, --show-warnings	Display build warnings.

dt-app build

Build the app and analyze the bundle.

Option	Description
--cwd [dir]	Set the current working directory.
--no-color	Terminal output renders without color.
--no-type-check	Skip type checking.
--non-interactive	Run 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.

Argument	Description
[packages...]	The packages that should be updated.

Option	Description
--cwd [dir]	Set the current working directory.
--no-color	Terminal output renders without color.
--non-interactive	Run in non-interactive mode. Throws error when a required command option or argument is missing.
--skip-install	Do 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, --interactive	Choose the packages you want to update manually.

dt-app migration execute

Execute a migration.

Option	Description
--cwd [dir]	Set the current working directory.
--from <currentVersion>	The current version of the package.
--no-color	Terminal output renders without color.
--non-interactive	Run 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.

Option	Description
--cwd [dir]	Set the current working directory.
--no-color	Terminal output renders without color.
--non-interactive	Run 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.

Option	Description
--cwd [dir]	Set the current working directory.
--no-color	Terminal output renders without color.
--non-interactive	Run 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.

Option	Description
--no-color	Terminal output renders without color.
--non-interactive	Run 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.

Option	Description
--cwd [dir]	Set the current working directory.
--dry-run	Perform a dry run without app deployment.
--environment-url [url]	Set the target environment for app deployment.
--no-color	Terminal output renders without color.
--no-open	Do not open the browser with the dev server.
--no-type-check	Skip type checking.
--non-interactive	Run in non-interactive mode. Throws error when a required command option or argument is missing.
--sign-archive	Sign 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-build	Skip 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.

Option	Description
--cwd [dir]	Set the current working directory.
--dry-run	Do not actually remove the app only perform a dry run.
--environment-url [url]	Set the target environment for app deployment.
--no-color	Terminal output renders without color.
--no-open	Do not open the browser with the dev server.
--non-interactive	Run 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.

Option	Description	Type	Required	Default Value
environmentUrl	URL to the environment of the project.	string	true

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

Option	Description	Type	Required
app.id	The unique identifier of the app. Limited to 50 characters. Must be an alphanumeric string containing only lowercase characters.	string	true
app.name	The name of the app. Limited to 40 characters.	string	true
app.version	The version of the app.	string	true
app.description	The description of the app. Limited to 80 characters.	string	true
app.icon	Path 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.	string	false
app.hidden	Hides the listing in the App Launcher. Useful for widget apps.	boolean	false
app.intents	The list of app capabilities of handling the intents.	IntentsDeclarations	false
app.pageTokens	The list of page tokens exposed by the app.	Record<string,string>	false
app.csp.font-src	The font-src directive specifies valid sources for fonts loaded.	DirectiveValue[]	false
app.csp.img-src	The img-src directive specifies valid sources of images and favicons.	DirectiveValue[]	false
app.csp.media-src	The media-src directive specifies valid sources for loading media.	DirectiveValue[]	false
app.csp.style-src	The style-src directive specifies valid sources for stylesheets.	DirectiveValue[]	false
app.csp.script-src	The 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.scopes	The list of scopes required by the app.	OAuthScope[]	true
app.selfMonitoringAgent	The self monitoring agent url	string	false

Build options

Options for customizing the build process.

Option	Description	Type	Required	Default Value
build.mode	Whether the build should be performed in production or development mode.	'production' | 'development'	false	'production' when building and 'development' when using development server
build.sourceMaps	Output 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'	false	undefined
build.sourceRoot	Location of source files.	string	false	./

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 UI	es2021
Functions	esnext

Server options

Options for the development server.

Example:

app.config.json

{
   server: {
     open: false,
     port: 3001,
     host: '127.0.0.1',
     showWarnings: true
   }
}

Option	Description	Type	Required	Default Value
server.open	Whether the project should be opened in the browser after startup or not.	boolean	false	true
server.port	Port where the app should be served.	number	false	3000
server.host	The host IP to bind the dev server on.	string	false	127.0.0.1
server.showWarnings	Whether build warnings should be displayed in the dev server or not.	boolean	false	false
server.enableCSP	Whether 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 *	boolean	false	true
server.https.cert	Path to cert in PEM format	string	true
server.https.key	Path to private key in PEM format	string	true

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',
      },
    ];
  }
}

Option	Description	Type	Required
glob	Pattern to specify which files inside the input folder are assets. Always use UNIX style separators.	string	true
ignore	Glob Patterns to exclude. Always use UNIX style separators.	string[]	false
input	Relative (from root) or absolute path where the glob is executed.	string	true
output	Relative path (from distDir) to directory where assets are copied to.	string	true

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.

Name	Description	Values	Default Value
DT_APP_PLATFORM_TOKEN	Token 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_TELEMETRY	Disables the sending of anonymous usage statistics and crash reports to dynatrace by setting it to 1.	not set or 1	not set
DT_APP_OAUTH_CLIENT_ID	Alternative 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_SECRET	ClientSecret used for authenticating with the Dynatrace Platform.
DT_APP_ENVIRONMENT_URL	Alternative to setting environmentUrl in app.config.json.
DT_APP_SIGN_URL	Custom signing URL for fetching certificate.
DT_APP_OAUTH_SIGN_CLIENT_ID	Client ID if you're authenticated to a different environment than the one you want to sign your archive for.
DT_APP_OAUTH_SIGN_CLIENT_SECRET	Client secret if you're authenticated to a different environment than the one you want to sign your archive for.
DT_APP_HTTPS_PROXY	Configure 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.

Related topics

• Troubleshoot connectivity