dt-app
Version:
The Dynatrace App Toolkit is a tool you can use from your command line to create, develop, and deploy apps on your Dynatrace environment.
778 lines (777 loc) • 27.6 kB
TypeScript
import type { Plugin } from 'esbuild';
import type { DynatraceApplicationManifest } from '../../interfaces/manifest';
import { type ValidationLevel } from './validate-wave-config';
import type { IntentsDeclarations } from '../../interfaces/intents';
import type { UiCommands } from '../../interfaces';
import { AppFunctionsBuildPlatform } from '../../build/build-functions';
export type { UiCommands } from '../../interfaces';
export { OperatingSystem } from '../../interfaces';
export declare const DEFAULT_SSO_URL = "https://sso.dynatrace.com";
/**
* Configuration for static assets that are bundled with the application.
* Assets are served by the development server and included in the deployed app package.
* Supports file patterns, exclusions, and custom output paths for flexible asset management.
* @internal
* @example Default
* assets: [
* {
* glob: '**\/*',
* ignore: [],
* input: 'src/assets',
* output: 'assets'
* },
* ]
*/
export type CliAsset = {
/**
* Glob pattern specifying which files to include from the input directory.
* Use UNIX-style path separators ('/') regardless of operating system.
* Supports standard glob syntax like wildcards (*) and directory recursion (**).
*/
glob: string;
/**
* Array of glob patterns for files to exclude from the asset bundle.
* Useful for filtering out development files, tests, or temporary resources.
*/
ignore?: string[];
/**
* Source directory containing the assets to be processed.
* Can be relative to project root or an absolute file system path.
* All glob patterns are executed within this directory.
*/
input: string;
/**
* Destination directory where assets will be copied in the build output.
* Path is relative to the build distribution directory (distDir).
* Maintains directory structure from the input folder.
*/
output: string;
};
/**
* Frontend UI build configuration controlling asset processing and bundling behavior.
* Manages static resources like images, fonts, and other files served with the application.
*/
export type CliUiSource = {
/**
* Static asset configurations defining how files are copied and served.
* Each asset configuration handles different types of static resources.
* @internal
*/
assets?: CliAsset[];
};
/**
* Build configuration for individual workflow action components.
* Defines entry points and TypeScript configuration for action-specific UI builds.
*/
export type CliActionSource = {
/**
* Main TypeScript/React entry file for the action's user interface.
* Path is relative to the action's directory (`/widgets/actions/<name>`).
* This file typically exports the action's main React component.
* @default src/main.tsx
*/
entryPoint?: string;
/**
* TypeScript configuration file for compiling the action's code.
* Path is relative to the action's directory (`/widgets/actions/<name>`).
* Should contain action-specific compiler options and path mappings.
* @default tsconfig.json
*/
tsconfig?: string;
};
/**
* ESBuild plugin type alias for build process customization.
* When using third-party ESBuild plugins, ensure they use the same ESBuild version as dt-app
* to avoid compatibility issues. Version mismatches can lead to unexpected build failures or
* runtime errors. Use `npm ls esbuild` to debug version conflicts.
* @internal
*/
export type EsbuildPlugin = Plugin;
/**
* Configuration for build process plugins that extend compilation and bundling capabilities.
* Plugins can modify code transformation, add custom loaders, or integrate with external tools.
* @internal
*/
export type PluginConfiguration = {
/**
* Array of ESBuild plugins to integrate into the build pipeline.
* Plugins execute during compilation to transform code, handle assets, or perform custom processing.
* Order matters as plugins are executed sequentially.
* @experimental
* @default []
*/
plugins?: EsbuildPlugin[];
};
/**
* Configuration options for customizing the application build process.
* Controls compilation, bundling, asset processing, and output generation.
*/
export type BuildOptions = {
/**
* Path to the main HTML entry point file, relative to the project root.
* This file serves as the template for the generated application.
* @default ui/index.html
*/
index?: string;
/**
* Build environment mode affecting optimization, minification, and debugging features.
* Production mode enables optimizations while development mode preserves debugging info.
* @default 'production' when building and 'development' when using development server
*/
mode?: 'production' | 'development';
/**
* Controls source map generation for debugging support.
* - `true`: Generate source maps for application code only
* - `'all'`: Include source maps for both application code and node_modules
* - `false`: No source maps generated
* @default undefined (treated as 'all' for development, 'false' for production builds)
*/
sourceMaps?: boolean | 'all';
/**
* Root directory containing the application source files, relative to project root.
* All source file paths are resolved relative to this directory.
* @default ./
*/
sourceRoot?: string;
/**
* Base path for application assets in the final build output.
* Used to configure routing and asset loading in the deployed application.
* @internal
* @default ui/
*/
baseHref?: string;
/**
* UI-specific build configuration including asset management and plugin settings.
* Controls how frontend resources are processed and bundled.
*/
ui?: CliUiSource & PluginConfiguration;
/**
* API-specific build configuration for backend processing and plugin integration.
* Manages server-side code compilation and plugin execution.
*/
api?: PluginConfiguration;
/**
* Advanced configuration for modifying Dynatrace platform dependencies.
* Allows overriding or ignoring specific platform dependencies during build.
* @experimental
* @internal
*/
dynatraceDependencies?: {
/**
* Override specific Dynatrace dependencies with custom versions.
* Key is the dependency name, value is the semver-compliant version string.
*/
addOrOverride?: Record<string, string>;
/**
* List of Dynatrace dependency names to exclude from the build.
*/
ignore?: string[];
};
};
/**
* Configuration options for the local development server.
* Controls how the application is served during development including network settings,
* security policies, and SSL configuration.
*/
export type ServerOptions = {
/**
* TCP port number for the development server to listen on.
* Choose an available port that doesn't conflict with other services.
* @default 3000
*/
port?: number;
/**
* Network interface IP address to bind the development server.
* Use '127.0.0.1' for localhost only
* @default 127.0.0.1
*/
host?: string;
/**
* Controls visibility of build warnings in the development server console output.
* Useful for debugging build issues during development.
* @default false
*/
showWarnings?: boolean;
/**
* Enables Content Security Policy (CSP) headers for enhanced security during development.
* When enabled, generates default CSP directives and merges with any custom directives.
* Frame-related directives are set to allow all sources in local development.
* @default true
*/
enableCSP?: boolean;
/**
* SSL/TLS certificate configuration for HTTPS development server.
* Provides secure local development environment with custom certificates.
*/
https?: ServerHttpsOptions;
};
/**
* HTTPS configuration options for the development server.
*/
export type ServerHttpsOptions = {
/**
* File system path to the SSL certificate in PEM format.
*/
cert: string;
/**
* File system path to the private key file in PEM format.
*/
key: string;
};
/**
* Core application metadata and configuration options used to generate the Dynatrace app manifest.
* Defines the app's identity, capabilities, security requirements, and integration features.
*/
export type AppOptions = {
/**
* Globally unique application identifier used for registration and deployment.
* Must be alphanumeric lowercase string, maximum 50 characters.
* Follow reverse domain notation (e.g., 'com.company.app').
*/
id: string;
/**
* Human-readable application name displayed in the Dynatrace interface.
* Maximum 40 characters, should be descriptive and user-friendly.
*/
name: string;
/**
* Semantic version string following semver specification (e.g., '1.0.0').
* Used for app lifecycle management and compatibility checks.
*/
version: string;
/**
* Brief application description explaining its purpose and functionality.
* Maximum 80 characters, displayed in app catalogs and listings.
*/
description: string;
/**
* Document type definitions for apps that handle custom document formats.
* Defines how the app processes and displays specific document types.
* @internal
*/
documentTypes?: DocumentTypes;
/**
* Path to the application icon file, relative to the project root.
* Supports SVG (recommended) or PNG formats. Auto-generated if not specified.
* Icon appears in app launchers and navigation interfaces.
*/
icon?: string;
/**
* Controls visibility in the Dynatrace App Launcher.
* Set to true for widget-only apps or background services that don't need launcher presence.
*/
hidden?: boolean;
/**
* Application capabilities for handling system intents and cross-app communication.
* Defines what types of data and actions the app can process from other apps.
*/
intents?: IntentsDeclarations;
/**
* Named page routes exposed by the app for deep linking and navigation.
* Maps logical page names to URL paths within the application.
*/
pageTokens?: Record<string, string>;
/**
* Workflow automation actions provided by the app.
* Enables integration with Dynatrace automation workflows and external systems.
* @internal
*/
actions?: Action[];
/**
* Content Security Policy directives specific to this application.
* Defines allowed sources for fonts, images, scripts, and other resources.
*/
csp?: CSPAppDirectives;
/**
* OAuth scopes required by the application for accessing Dynatrace APIs and data.
* Each scope must include a descriptive comment explaining its necessity.
*/
scopes: OAuthScope[];
/**
* URL endpoint for the self-monitoring agent script.
* Enables application performance monitoring and diagnostics within Dynatrace.
*/
selfMonitoringAgent?: string;
/**
* UI command definitions for extending Dynatrace interface functionality.
* Allows apps to contribute commands to menus, toolbars, and context actions.
* @experimental
* @internal
*/
uiCommands?: UiCommands;
/**
* Configuration widgets for app-specific settings management.
* Provides structured forms for users to configure app behavior and preferences.
* @experimental
* @internal
*/
settings?: SettingsManifest;
/**
* Document handling configuration for apps that process custom document types.
* Defines document schemas, rendering, and interaction capabilities.
* @experimental
* @internal
*/
documents?: DocumentsManifest;
};
/**
* Base configuration for workflow automation actions.
* Actions provide reusable automation components that can be triggered by workflows,
* other apps, or external systems within the Dynatrace platform.
*/
export type ActionBase = {
/**
* Human-readable title displayed in workflow editors and action catalogs.
* Should be concise and descriptive of the action's primary function.
*/
title: string;
/**
* Detailed description explaining the action's purpose, inputs, and behavior.
* Used in documentation and workflow design interfaces.
*/
description: string;
/**
* Unique identifier for the action within the application scope.
* Used for action registration, invocation, and workflow references.
*/
name: string;
/**
* Legacy flag indicating whether the action maintains state between executions.
* @deprecated State management is now handled by the workflow engine
*/
stateful?: boolean;
/**
* Build configuration specific to this action's UI components and compilation.
* @deprecated Build configuration is now handled at the application level
*/
build?: CliActionSource & PluginConfiguration;
};
type ActionExtension = {
/**
* @deprecated
* Further properties that need to be part of the manifest.
*/
[key: string]: any;
};
export type Action = ActionBase & ActionExtension;
/**
* @internal
*/
export type ActionManifest = Omit<Action, 'build'> & FunctionManifest;
/**
* Configuration manifest for application settings widgets.
* Defines structured configuration forms that users can interact with to customize app behavior.
* @internal
*/
export type SettingsManifest = {
[key: string]: {
/**
* Display name for the settings widget shown in the configuration interface.
*/
name: string;
/**
* Optional description explaining the purpose and impact of these settings.
*/
description?: string;
/**
* Array of JSON schema identifiers that define the structure and validation rules
* for the configuration data managed by this settings widget.
*/
schemaIds: string[];
};
};
/**
* Manifest configuration for document handling capabilities within the application.
* Defines how the app processes, displays, and interacts with custom document types.
* @internal
*/
export type DocumentsManifest = {
[key: string]: {
/**
* Optional display name for the document handler in the Dynatrace interface.
*/
name?: string;
/**
* Optional description of the document type and its processing capabilities.
*/
description?: string;
};
};
/**
* Manifest for document type definitions including visual representation.
* Maps document type identifiers to their display properties and iconography.
* @internal
*/
export type DocumentTypesManifest = {
[key: string]: {
/**
* Human-readable name for the document type displayed in interfaces.
*/
name: string;
/**
* Optional icon identifier or path for visual representation of the document type.
*/
icon?: string;
};
};
/**
* Runtime configuration for serverless functions and workflow actions.
* Controls execution behavior and lifecycle management.
* @internal
*/
export type FunctionManifest = {
/**
* Indicates whether the function can be paused and resumed across execution cycles.
* Enables long-running workflows that can survive platform restarts or scaling events.
*/
resumable?: boolean;
};
/**
* Content Security Policy (CSP) directives configuration for enhanced application security.
* Defines trusted sources for various types of resources to prevent XSS and data injection attacks.
* Each directive type corresponds to a specific CSP header directive.
*/
export type CSPAppDirectives = {
/**
* Specifies valid sources for web fonts loaded by the application.
*/
'font-src'?: DirectiveValue[];
/**
* Defines allowed sources for images and favicons used in the application.
* Includes img elements, CSS background images, and favicon resources.
*/
'img-src'?: DirectiveValue[];
/**
* Controls valid sources for audio and video media content.
* Applies to HTML5 audio/video elements and media streaming resources.
*/
'media-src'?: DirectiveValue[];
/**
* Specifies trusted sources for CSS stylesheets and style resources.
* Covers external stylesheets, inline styles, and CSS imports.
*/
'style-src'?: DirectiveValue[];
/**
* Defines allowed sources for JavaScript code execution and script resources.
* Includes external scripts, inline event handlers, eval(), and XSLT transformations.
* Critical for preventing XSS attacks through script injection.
*/
'script-src'?: DirectiveValue[];
};
/**
* Individual CSP directive value with documentation for security compliance.
* Combines the actual directive value with explanatory context for security audits.
*/
export type DirectiveValue = {
/**
* The CSP directive value (e.g., URL, keyword like 'self', 'unsafe-inline').
* Must follow CSP specification syntax for the corresponding directive type.
*/
value: string;
/**
* Human-readable explanation for why this directive value is necessary.
* Required for security audits and compliance documentation.
*/
comment: string;
};
/**
* OAuth 2.0 scope definition for Dynatrace API access permissions.
* Defines specific API capabilities required by the application with justification.
* @internal
*/
export type OAuthScope = {
/**
* The OAuth scope identifier as defined by Dynatrace API documentation.
* Corresponds to specific API endpoints or data access permissions.
*/
name: string;
/**
* Explanation of why this scope is required by the application.
* Used for permission reviews and compliance documentation.
*/
comment: string;
};
/**
* Main configuration object for the dt-app toolkit. The toolkit automatically resolves
* a config file named `app.config.json` from the project's root directory when running commands.
* This type defines all available configuration options for building, serving, and managing Dynatrace apps.
*/
export type CliOptions = {
/**
* The target Dynatrace environment URL where the app will be deployed.
* Must be a valid HTTPS URL pointing to your Dynatrace tenant.
*/
environmentUrl: string;
/**
* Configuration options for the build process including source paths, output settings,
* bundling behavior, and asset management. Controls how your app is compiled and packaged.
*/
build?: BuildOptions;
/**
* Core application metadata and configuration including app ID, name, version, description,
* permissions, intents, actions, and other manifest properties required for app registration.
*/
app: AppOptions;
/**
* Controls whether the Dynatrace SDK is automatically injected into your application.
* When enabled, provides access to Dynatrace platform APIs and services.
* @internal
* @default true
*/
injectSdk?: boolean;
/**
* Development server configuration including port, host, SSL settings, and CSP options.
* Used when running the app locally during development.
*/
server?: ServerOptions;
/**
* Array of plugin module paths that extend CLI functionality.
* Plugins can modify build processes, add new commands, or integrate with external tools.
* @experimental
*/
plugins?: string[];
};
/**
* Document type definitions for applications that handle custom document formats.
* Maps document type identifiers to their display properties and metadata.
* @internal
*/
export type DocumentTypes = {
[key: string]: {
/**
* Human-readable name for the document type displayed in the Dynatrace interface.
* Used in file browsers, document listings, and type selection dialogs.
*/
name: string;
};
};
/**
* @internal
* @deprecated The type will be removed in 1.0
*/
export type CliEnvFlags = {
/**
* Provides the client credentials when authenticating against SSO.
*/
oauthClientSecret?: string | undefined;
};
/**
* Flags to manipulate dt-app commands.
* @internal
*/
export type CliFlags = {
/**
* The root directory of the project.
* @default process.cwd()
*/
root?: string;
/**
* Don't actually perform the command. Used for deploy and uninstall. Can only be set with CLI flag `--dry-run`
* @default false
*/
dryRun?: boolean;
/**
* Disable live reload (file watcher) of development server.
* Used for dev command. Can only be set with CLI flag `--no-live-reload`.
* @default false
*/
noLiveReload?: boolean;
build?: {
typeCheck?: boolean;
};
server?: {
/**
* Whether the dev server should open the browser automatically after startup.
* @default true
*/
open: boolean;
};
};
/**
* @internal
*/
export type CliFlagOptions = CliOptions & CliFlags;
/**
* @internal
*/
export type ResolvedCliAsset = Required<CliAsset>;
/**
* @internal
*/
export type ResolvedCliUiSource = Omit<Required<CliUiSource> & Partial<PluginConfiguration>, 'assets'> & {
assets: ResolvedCliAsset[];
};
type ResolvedCliActionSource = Required<CliActionSource> & Partial<PluginConfiguration>;
/**
* @internal
*/
export type ResolvedAction = Omit<ActionBase, 'build'> & {
build: ResolvedCliActionSource;
};
/**
* @internal
*/
export type ResolvedBuildOptions = Omit<Required<BuildOptions>, 'ui' | 'api' | 'functions' | 'sourceMaps'> & {
sourceMaps?: boolean | 'all';
ui: ResolvedCliUiSource;
api: PluginConfiguration;
typeCheck: boolean;
};
/**
* @internal
*/
export type ResolvedAppOptions = Omit<DynatraceApplicationManifest, 'actions' | 'icon' | 'app-bundle-version'> & {
actions?: ResolvedAction[];
selfMonitoringAgent?: string;
};
/**
* @internal
*/
export type ResolvedServerOptions = Omit<Required<ServerOptions>, 'https'> & {
https?: {
cert: string;
key: string;
};
/**
* Whether the project should be opened in the browser after startup or not.
* @default true
*/
open: boolean;
};
/**
* @internal
*/
export type ResolvedCliOptions = Omit<Required<CliFlagOptions>, 'build' | 'server' | 'dev' | 'icon'> & {
root: string;
distDir: string;
oauth2File: string;
appFunctionsBuildPlatform: AppFunctionsBuildPlatform;
build: ResolvedBuildOptions;
server: ResolvedServerOptions;
app: ResolvedAppOptions;
};
export type DefaultableCliOptions = Omit<ResolvedCliOptions, 'environmentUrl' | 'app' | 'icon' | 'oauth2File'>;
/**
* Configurations from config file (if one exists), from command line flags and default
* configurations get merged and returned
* @internal
*/
export declare function mergeOptions(argsConfig: Partial<CliFlagOptions & {
appFunctionsBuildPlatform: AppFunctionsBuildPlatform;
}>, fileConfig: any, envConfig: Record<string, string | undefined>, validationLevel?: ValidationLevel, isDev?: boolean): Promise<ResolvedCliOptions>;
/** Returns the path to the OAuth2 token file. */
export declare function getOAuth2FilePath(root: string): string;
export interface UiFilePaths {
entryPoint: string;
assetsInput: string;
tsConfigFullPath: string;
}
/**
* Resolves UI file paths for projects using legacy or fallback structure patterns.
*
* This function handles three distinct project structure scenarios:
* 1. **New structure**: `<sourceRoot>/ui/main.tsx` - Returns `undefined` (handled in cli-options.ts)
* 2. **Legacy structure**: `<sourceRoot>/main.tsx` - Returns legacy-specific paths
*
* @param root - Absolute path to the project root directory
* @param sourceRoot - Relative path from root to source directory (e.g., 'src', './')
* @param uiOptions - UI build source configuration from app.config options assets
*
* @returns {UiFilePaths} Resolved UI file paths or undefined
* - Returns `UiFilePaths` object for legacy or fallback scenarios
*
*/
export declare function resolveUiFilePaths(root: string, sourceRoot: string, uiOptions: ResolvedCliUiSource): Promise<UiFilePaths>;
/**
* Helper function that will return default CLI options based on the isDev flag
* @internal
*/
export declare function getDefaultCliOptions(isDev: boolean, sourceRoot?: string, root?: string): DefaultableCliOptions;
/**
* Normalize the baseHref to always end with a slash.
* @returns Normalized baseHref
*/
export declare function getNormalizedBaseHrefWithSlash(baseHref: string): string;
/**
* Merges b onto a. Merges value by value for simple properties and complex object but overrides arrays
*/
export declare function mergeRecursively(a: any, b: any): any;
/**
* @deprecated The type will be removed in 1.0
*/
export type DeprecatedPluginConfiguration = {
/**
* Plugins that should be used to inject code into various parts of the build process.
* @deprecated This property will be removed
* @default []
*/
plugins?: EsbuildPlugin[];
};
/**
* @deprecated The type will be removed in 1.0
*/
export type ActionPluginConfiguration = {
/**
* Plugins that should be used to inject code into various parts of the build process.
* By default it is inherited from the `build.functions.plugins`
* @deprecated This property will be removed.
* @default build.functions.plugins
*/
plugins?: EsbuildPlugin[];
};
/**
* @deprecated The type will be removed in 1.0
*/
export type WidgetPluginConfiguration = {
/**
* Plugins that should be used to inject code into various parts of the build process.
* By default it is inherited from the `build.ui.plugins`
* @deprecated This property will be removed.
* @default build.ui.plugins
*/
plugins?: EsbuildPlugin[];
};
type FileConfigPathConfigurations = {
root: string;
oauthClientId: string;
distDir: string;
oauth2File: string;
build: {
baseHref: string;
settingsPath: string;
ui: {
entryPoint: string;
tsconfig: string;
assets: string;
additionalEntryPoints: string[];
sourceMaps?: boolean | 'all';
};
functions: {
input: string;
glob: string;
tsconfig: string;
sourceMaps?: boolean | 'all';
} & DeprecatedPluginConfiguration;
widgets: WidgetPluginConfiguration;
actions: ActionPluginConfiguration;
};
dev?: {
fileWatcher?: {
ignore: string[];
include: string[];
};
};
server?: {
open: boolean;
};
};
declare const enum ExecutionMode {
RUNTIME_SIMULATOR = "runtime-simulator",
RUNTIME = "js-runtime"
}
/** Prints warning to the terminal if app config has deprecated options defined */
export declare function printPathConfigurationsWarnings(fileConfig: Partial<FileConfigPathConfigurations>, argsConfig: Partial<CliOptions & CliFlags & CliEnvFlags & {
executionMode: ExecutionMode;
appFunctionsBuildPlatform: AppFunctionsBuildPlatform;
global: string;
}>, root: string, sourceRoot: string): void;