Configuration

The dt-app toolkit will automatically try to resolve a config file named app.config.\{json,js,ts} in the project's root when running a command.

General options

Option	Description	Type	Required	Default Value
root	Project root directory (where the app.config.\{json,js,ts} file is located). Has to be an absolute path.	string	false	process.cwd()
environmentUrl	URL to the environment of the project.	string	true
oauthClientId	Provides the client ID for authenticating via SSO.	string	false	dt0s08.dtp-cli-local
distDir	Relative path to the output directory.	string	false	dist/
oauth2File	The secret file where the oauth2 tokens are stored. Can either be an absolute path or a relative path from root.	string	false	${process.cwd()}/.dt-app/.tokens.json
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
deploy.build	Whether the app should automatically be built before deployment or not.	boolean	false	true
injectSdk	Whether the SDK should be injected or not.	boolean	false	true
dev.fileWatcher.ignore	Glob pattern to specify which files should be ignored by the file-watcher that triggers a rebuild.	string[]	false	[**​/*.spec.{ts,tsx}, **​/*.test.ts]
dev.fileWatcher.include	Glob pattern to specify which files should be watched (apart from the root) by the file-watcher that triggers a rebuild.	string[]	false	[]

App options

Options that are used to generate the manifest.

Option	Description	Type	Required
app.id	The unique identifier of the app. Limited to 50 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.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

Setting app options inside the app.config.json

{
  "app": {
     "id": "my.app",
     "name": "My App",
     "description": "My description",
     "version": "1.0.0"
   }
}

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
build.settingsPath	A path to custom settings json files.	string	false	settings/schemas
build.ui.entryPoint	Relative path to the file that serves as the main entry point for the UI.	string	false	src/main.tsx
build.ui.tsconfig	Relative path (from root) to tsconfig file.	string	false	tsconfig.json
build.ui.assets	Assets that should be bundled and served.	Asset[]	false
build.ui.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.ui.plugins	Plugins that should be used to inject code into various parts of the build process.	EsbuildPlugin[]	false	[]
build.functions.input	Relative path to function files.	string	false	api/
build.functions.glob	Pattern to specify which files should be built and deployed as functions. Always use UNIX style separators.	string	false	**​/*.ts
build.functions.tsconfig	Relative path (from input) to tsconfig file.	string	false	tsconfig.json
build.functions.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.functions.plugins	Plugins that should be used to inject code into various parts of the build process.	EsbuildPlugin[]	false	[]

Server options

Options for the development server.

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

Example

{
   server: {
     open: false,
     port: 3001,
     host: '127.0.0.1',
     showWarnings: 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.

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

Default

assets: [
  {
    glob: '**/*',
    ignore: [],
    input: 'src/assets',
    output: 'assets',
  },
];

CLI Flags

Flags to manipulate dt-app commands.

Option	Description	Type	Required
dryRun	Don't actually perform the command. Used for deploy and uninstall. Can only be set with CLI flag --dry-run	boolean	false
forceOverwrite	Overwrite an existing app with the same id if it has been deployed by another user. Please make sure the required permissions are set. Used for the deploy command. Can only be set with CLI flag --force-overwrite. Note: this flag can't be used to overwrite specific versions of apps.	boolean	false
noLiveReload	Disable live reload (file watcher) of development server. Used for dev command. Can only be set with CLI flag --no-live-reload.	boolean	false

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)

Build target

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

	Target
App UI	es2021
Actions UI	es2021
Functions	esnext

Supported file types

App functions can't access the file system. Files types that are allowed and can be imported are: .js, .ts, .json, .txt

Environment Variables

Name	Description	Values	Default Value
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,js,ts}. 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,js,ts}.
DT_APP_SIGNING_PK	Private key to sign the app.
DT_APP_SIGNING_CERT	Certificate to sign the app.
DEBUG	Print debug logs to the console for more information.	set or not set
DT_APP_SERVERLESS_MAX_CONNECTIONS	The maximum number of app function connections.		128

Logs

Logs can be found in .dt-app/logs inside your app directory.