dt-app/lib/src/utils/config/cli-options.d.ts

The Dynatrace App Toolkit is a tool you can use from your command line to create, develop, and deploy apps on your Dynatrace environment.

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 { ExecutionMode } from '../../dev/fastify';
import { AppFunctionsBuildPlatform } from '../../build/build-functions';
export type { UiCommands } from '../../interfaces';
export { OperatingSystem } from '../../interfaces';
/** @deprecated The constant will be removed in 1.0 */
export declare const DEFAULT_SSO_URL = "https://sso.dynatrace.com";
/** @deprecated The constant will be removed in 1.0 */
export declare const DEFAULT_SSO_CLIENT_ID = "dt0s08.dt-app-local";
/**
 * 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 Default
 * assets: [
 *    {
 *      glob: '**\/*',
 *      ignore: [],
 *      input: 'src/assets',
 *      output: 'assets'
 *    },
 * ]
 */
export type CliAsset = {
    /**
     * Pattern to specify which files inside the `input` folder are assets. Always use UNIX style separators.
     */
    glob: string;
    /**
     * Glob Patterns to exclude. Always use UNIX style separators.
     */
    ignore?: string[];
    /**
     * Relative (from `root`) or absolute path where the glob is executed.
     */
    input: string;
    /**
     * Relative path (from `distDir`) to directory where assets are copied to.
     */
    output: string;
};
export type 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.
     * @deprecated
     * @default undefined
     */
    sourceMaps?: boolean | 'all';
};
export type CliUiSource = {
    /**
     * Relative path to the file that serves as the main entry point for the UI.
     * @default src/main.tsx
     * @deprecated This property will be removed.
     */
    entryPoint?: string;
    /**
     * Additional entry points for custom modules and web workers. Bundles will be
     * generated for each entry point respectively in addition to the main entry point.
     * @internal
     * @deprecated This property will be removed.
     */
    additionalEntryPoints?: string[];
    /**
     * Relative path (from `root`) to tsconfig file.
     * @default tsconfig.json
     * @deprecated This property will be removed.
     */
    tsconfig?: string;
    /**
     * Assets that should be bundled and served.
     * @internal
     */
    assets?: CliAsset[];
};
/** @deprecated The type will be removed in 1.0 */
export type CliFunctionSource = {
    /**
     * Relative path to function files.
     * @default api/
     * @deprecated This property will be removed.
     */
    input?: string;
    /**
     * Pattern to specify which files should be built and deployed as functions. Always use UNIX style separators.
     * @default \*\*​/*.ts
     * @deprecated This property will be removed.
     */
    glob?: string;
    /**
     * Relative path (from `input`) to tsconfig file.
     * @default tsconfig.json
     * @deprecated This property will be removed.
     */
    tsconfig?: string;
};
/** @deprecated The type will be removed in 1.0 */
export type CliActionSource = {
    /**
     * Relative path (from `/widgets/actions/<name>`) to the file that serves as the main entry point for the UI.
     * @default src/main.tsx
     */
    entryPoint?: string;
    /**
     * Relative path (from `/widgets/actions/<name>`) to tsconfig file.
     * @default tsconfig.json
     */
    tsconfig?: string;
};
/**
 * 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. `npm ls esbuild` can help to debug a version conflicts.
 */
export type EsbuildPlugin = Plugin;
export type PluginConfiguration = {
    /**
     * Plugins that should be used to inject code into various parts of the build process.
     * @default []
     */
    plugins?: EsbuildPlugin[];
};
/**
 * Options for customizing the build process.
 */
export type BuildOptions = {
    /**
     * Relative path (from `root`) to index.html file.
     * @default src/index.html
     */
    index?: string;
    /**
     * Whether the build should be performed in production or development mode.
     * @default 'production' when building and 'development' when using development server
     */
    mode?: 'production' | 'development';
    /**
     * 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.
     * @default undefined
     */
    sourceMaps?: boolean | 'all';
    /**
     * Location of source files.
     * @default ./
     */
    sourceRoot?: string;
    /**
     * A path to custom settings json files.
     * @default settings/schemas
     * @deprecated This property will be removed.
     */
    settingsPath?: string;
    /**
     * BaseHref that will be set in the `index.html`.
     * @internal
     * @deprecated
     * @default ui/
     */
    baseHref?: string;
    ui?: CliUiSource & SourceMaps & UIPluginConfiguration;
    /** @deprecated */
    functions?: CliFunctionSource & SourceMaps & DeprecatedPluginConfiguration;
    api?: SourceMaps;
    /** @internal */
    widgets?: WidgetPluginConfiguration;
    /** @internal */
    actions?: ActionPluginConfiguration;
    /**
     * **Experimental:** Alter the dynatrace dependencies of the app.
     * @experimental
     * @internal
     */
    dynatraceDependencies?: {
        /**
         * Add or override dynatrace dependencies where the key is the dependency name and the value is the semvers compliant version as string.
         * e.g. 'some/dynatrace/dependency/v1': '1.1.0'
         */
        addOrOverride?: Record<string, string>;
        /** Ignore a list of dynatrace dependencies. */
        ignore?: string[];
    };
};
export type UIPluginConfiguration = {
    /**
     * Plugins that should be used to inject code into various parts of the build process.
     * @experimental
     * @default []
     */
    plugins?: EsbuildPlugin[];
};
/**
 * @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[];
};
/**
 * Options for the development server.
 * @example Example
 * {
 *    server: {
 *      open: false,
 *      port: 3001,
 *      host: '127.0.0.1',
 *      showWarnings: true
 *    }
 * }
 */
export type ServerOptions = {
    /**
     * Whether the project should be opened in the browser after startup or not.
     * @deprecated
     * @default true
     */
    open?: boolean;
    /**
     * Port where the app should be served.
     * @default 3000
     */
    port?: number;
    /**
     * The host IP to bind the dev server on.
     * @default 127.0.0.1
     */
    host?: string;
    /**
     * Whether build warnings should be displayed in the dev server or not.
     * @default false
     */
    showWarnings?: boolean;
    /**
     * 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 *
     * @default true
     */
    enableCSP?: boolean;
    /** Certificate for local ssl connection */
    https?: {
        /** Path to cert in PEM format */
        cert: string;
        /** Path to private key in PEM format */
        key: string;
    };
};
/**
 * Options that are used to generate the manifest.
 *
 * @example Setting app options inside the app.config.json
 * {
 *   "app": {
 *      "id": "my.app",
 *      "name": "My App",
 *      "description": "My description",
 *      "version": "1.0.0"
 *    }
 * }
 */
export type AppOptions = {
    /**
     * The unique identifier of the app. Limited to 50 characters. Must be an alphanumeric string containing only lowercase characters.
     */
    id: string;
    /**
     * The name of the app. Limited to 40 characters.
     */
    name: string;
    /**
     * The version of the app.
     */
    version: string;
    /**
     * The description of the app. Limited to 80 characters.
     */
    description: string;
    /**
     * Specify types of the documents
     * @internal
     */
    documentTypes?: DocumentTypes;
    /**
     * 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.
     */
    icon?: string;
    /**
     * Hides the listing in the App Launcher. Useful for widget apps.
     */
    hidden?: boolean;
    /**
     * The list of app capabilities of handling the intents.
     */
    intents?: IntentsDeclarations;
    /**
     * The list of page tokens exposed by the app.
     */
    pageTokens?: Record<string, string>;
    /**
     * @internal
     */
    actions?: Action[];
    /**
     * CSP directives for the app.
     */
    csp?: CSPAppDirectives;
    /**
     * The list of scopes required by the app.
     */
    scopes: OAuthScope[];
    /**
     * The self monitoring agent url
     */
    selfMonitoringAgent?: string;
    /**
     * **Experimental:** The list UI commands provided by the app.
     * @experimental
     * @internal
     */
    uiCommands?: UiCommands;
    /**
     * **Experimental:** The list of settings widgets provided by the app.
     * @experimental
     * @internal
     */
    settings?: SettingsManifest;
    /**
     * **Experimental:** Config for documents provided by the app.
     * @experimental
     * @internal
     */
    documents?: DocumentsManifest;
};
export type ActionBase = {
    /**
     * The title of the action.
     */
    title: string;
    /**
     * The description of the action.
     */
    description: string;
    /**
     * The name of the action.
     */
    name: string;
    /**
     * @deprecated
     * Indicates if action is stateful.
     */
    stateful?: boolean;
    /**
     * Options to configure the build.
     * @deprecated
     */
    build?: CliActionSource & SourceMaps & PluginConfiguration;
};
type ActionExtension = {
    /**
     * @deprecated
     * Further properties that need to be part of the manifest.
     */
    [key: string]: any;
};
export type Action = ActionBase & ActionExtension;
export type ActionManifest = Omit<Action, 'build'> & FunctionManifest;
export type SettingsManifest = {
    [key: string]: {
        name: string;
        description?: string;
        schemaIds: string[];
    };
};
export type DocumentsManifest = {
    [key: string]: {
        name?: string;
        description?: string;
    };
};
export type DocumentTypesManifest = {
    [key: string]: {
        name: string;
        icon?: string;
    };
};
export type FunctionManifest = {
    resumable?: boolean;
};
export type CSPAppDirectives = {
    /** The font-src directive specifies valid sources for fonts loaded.  */
    'font-src'?: DirectiveValue[];
    /** The img-src directive specifies valid sources of images and favicons. */
    'img-src'?: DirectiveValue[];
    /** The media-src directive specifies valid sources for loading media. */
    'media-src'?: DirectiveValue[];
    /** The style-src directive specifies valid sources for stylesheets. */
    'style-src'?: DirectiveValue[];
    /** 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. */
    'script-src'?: DirectiveValue[];
};
export type DirectiveValue = {
    /** The directive value. */
    value: string;
    /** A short comment on why this directive value is needed. */
    comment: string;
};
/**
 * @internal
 * @deprecated The type will be removed in 1.0
 */
export type OAuthScope = {
    /** Represents the scope that should be requested. */
    name: string;
    /** A short comment on why this scope is required. */
    comment: string;
};
/**
 * The dt-app toolkit will automatically try to resolve a config file named `app.config.json` in
 * the project's `root` when running a command.
 */
export type CliOptions = {
    /**
     * Project root directory (where the `app.config.json` file is located). Has to be an absolute path.
     * @deprecated
     * @default process.cwd()
     */
    root?: string;
    /**
     * URL to the environment of the project.
     */
    environmentUrl: string;
    /**
     * Provides the client ID for authenticating via SSO.
     * @deprecated
     * @default dt0s08.dt-app-local
     */
    oauthClientId?: string;
    /**
     * Relative path to the output directory.
     * @deprecated
     * @default dist/
     */
    distDir?: string;
    /**
     * The secret file where the oauth2 tokens are stored.
     * Can either be an absolute path or a relative path from root.
     * @deprecated
     * @default ${process.cwd()}/.dt-app/.tokens.json
     */
    oauth2File?: string;
    /**
     * 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.
     * @deprecated
     */
    icon?: string;
    /** Build options */
    build?: BuildOptions;
    /** Deploy options */
    deploy?: {
        /**
         * Whether the app should automatically be built before deployment or not.
         * @default true
         */
        build?: boolean;
    };
    app: AppOptions;
    /**
     * Whether the SDK should be injected or not.
     * @internal
     * @default true
     */
    injectSdk?: boolean;
    server?: ServerOptions;
    /** Dev options */
    dev?: {
        /**
         * @deprecated
         */
        fileWatcher?: {
            /**
             * Glob pattern to specify which files should be ignored by the file-watcher that triggers a rebuild.
             * @deprecated
             * @default [\*\*&#x200B;/\*.spec.{ts,tsx}, \*\*&#x200B;/\*.test.ts]
             */
            ignore?: string[];
            /**
             * Glob pattern to specify which files should be watched (apart from the root) by the file-watcher that triggers a rebuild.
             * @deprecated
             * @default []
             */
            include?: string[];
        };
    };
    /**
     * Plugins that can be used to extend commands.
     * @experimental
     */
    plugins?: string[];
};
export type DocumentTypes = {
    [key: string]: {
        /** Name for the document  */
        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.  */
export type CliFlags = {
    /**
     * 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;
    };
};
export type CliFlagOptions = CliOptions & CliFlags & CliEnvFlags;
/**
 * @internal
 * @deprecated The type will be removed in 1.0
 */
export type ResolvedCliAsset = Required<CliAsset>;
/**
 * @internal
 * @deprecated The type will be removed in 1.0
 */
export type ResolvedCliUiSource = Omit<Required<CliUiSource> & SourceMaps & Partial<PluginConfiguration>, 'assets'> & {
    assets: ResolvedCliAsset[];
};
/**
 * @internal
 * @deprecated The type will be removed in 1.0
 */
export type ResolvedCliFunctionSource = Omit<Required<CliFunctionSource> & SourceMaps & Partial<PluginConfiguration>, 'assets'>;
/**
 * @internal
 * @deprecated The type will be removed in 1.0
 */
export type ResolvedCliApiSource = Omit<SourceMaps, 'assets'>;
type ResolvedCliActionSource = Required<CliActionSource> & SourceMaps & Partial<PluginConfiguration>;
/**
 * @internal
 * @deprecated The type will be removed in 1.0.
 */
export type ResolvedAction = Omit<ActionBase, 'build'> & {
    build: ResolvedCliActionSource;
    isUiAction: boolean;
};
/**
 * @internal
 * @deprecated The type will be removed in 1.0
 */
export type ResolvedBuildOptions = Omit<Required<BuildOptions>, 'ui' | 'functions' | 'sourceMaps'> & {
    sourceMaps?: boolean | 'all';
    ui: ResolvedCliUiSource;
    /** @deprecated */
    functions: ResolvedCliFunctionSource;
    api: ResolvedCliApiSource;
    typeCheck: boolean;
};
/**
 * @internal
 * @deprecated The type will be removed in 1.0
 */
export type ResolvedAppOptions = Omit<DynatraceApplicationManifest, 'actions' | 'icon' | 'app-bundle-version'> & {
    actions?: ResolvedAction[];
    selfMonitoringAgent?: string;
};
/**
 * @internal
 * @deprecated The type will be removed in 1.0
 */
export type ResolvedServerOptions = Omit<Required<ServerOptions>, 'https'> & {
    https?: {
        cert: string;
        key: string;
    };
};
/**
 * @internal
 * @deprecated The type will be removed in 1.0
 */
export type ResolvedCliOptions = Omit<Required<CliFlagOptions>, 'build' | 'server' | 'deploy' | 'dev' | 'icon'> & {
    executionMode: ExecutionMode;
    appFunctionsBuildPlatform: AppFunctionsBuildPlatform;
    build: ResolvedBuildOptions;
    server: ResolvedServerOptions;
    app: ResolvedAppOptions;
    deploy: {
        build: boolean;
    };
    dev: {
        fileWatcher: {
            ignore: string[];
            include: string[];
        };
    };
    icon?: string;
};
/**
 * @deprecated The type will be removed in 1.0
 */
export type DefaultableCliOptions = Omit<ResolvedCliOptions, 'environmentUrl' | 'app' | 'icon' | 'oauthClientId' | 'oauthClientSecret' | 'oauth2File'>;
/**
 * Configurations from config file (if one exists), from command line flags and default
 * configurations get merged and returned
 * @internal
 * @deprecated The function will be removed in 1.0
 */
export declare function mergeOptions(argsConfig: Partial<CliFlagOptions & {
    executionMode: ExecutionMode;
    appFunctionsBuildPlatform: AppFunctionsBuildPlatform;
    global: string;
}>, fileConfig: any, envConfig: Record<string, string | undefined>, validationLevel?: ValidationLevel, isDev?: boolean): Promise<ResolvedCliOptions>;
interface UiFilePaths {
    entryPoint: string;
    assetsInput: string;
    tsConfig: 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
 * 3. **Old structure (will be deleted in v1.0)**: ./src/main.tsx - Returns default paths with config overrides
 *
 * @param options - Configuration object containing project paths and build settings
 * @param options.root - Absolute path to the project root directory
 * @param options.sourceRoot - Relative path from root to source directory (e.g., 'src', './')
 * @param options.buildUi - UI build configuration from app.config options containing entry points and assets
 *
 * @returns {UiFilePaths | undefined} Resolved UI file paths or undefined
 * - Returns `undefined` when new UI structure (`<sourceRoot>/ui/main.tsx`) is detected
 * - Returns `UiFilePaths` object for legacy or fallback scenarios
 *
 * @see {@link resolveTsConfigForLegacy} For legacy tsconfig resolution logic
 * @see {@link resolveTsConfigForOld} For default tsconfig resolution logic
 *
 */
export declare function resolveLegacyUiFilePaths(options: {
    root: string;
    sourceRoot: string;
    buildUi: ResolvedCliUiSource;
}): UiFilePaths | undefined;
/** Helper function that will return default CLI options based on the isDev flag */
export declare function getDefaultCliOptions(isDev: boolean, sourceRoot?: string): DefaultableCliOptions;
/**
 * Normalize the baseHref to always end with a slash.
 * @param build The build options passed in a command
 * @returns Normalized baseHref
 * @deprecated The function will be removed in 1.0
 */
export declare function getNormalizedBaseHrefWithSlash(baseHref: string): string;
/**
 * Merges b onto a. Merges value by value for simple properties and complex object but overrides arrays
 * @deprecated The function will be removed in 1.0
 */
export declare function mergeRecursively(a: any, b: any): any;