projen/lib/typescript/typescript-runner.d.ts

CDK for software projects

import { type RunScriptConfig, ScriptRunner } from "../script-runner";
/**
 * Options for the ts-node runner.
 */
export interface TsNodeRunnerOptions {
    /**
     * Whether to type-check the script during executing.
     *
     * @see https://github.com/TypeStrong/ts-node#typecheck
     *
     * @default true
     */
    readonly typeCheck?: boolean;
    /**
     * Path to the tsconfig file to use.
     *
     * @default - ts-node default discovery
     */
    readonly tsconfig?: string;
    /**
     * Whether to use SWC for transpilation.
     *
     * This will disable type-checking.
     *
     * @see https://github.com/TypeStrong/ts-node#swc
     *
     * @default false
     */
    readonly swc?: boolean;
}
/**
 * Options for the tsx runner.
 */
export interface TsxRunnerOptions {
    /**
     * Whether to type-check the entrypoint before executing.
     *
     * Because tsx does not type check code, you may want to enable this for additional type safety.
     * When enabled, runs `tsc --noEmit`, using the provided tsconfig.
     *
     * @default false
     */
    readonly typeCheck?: boolean;
    /**
     * Path to the tsconfig file to use.
     * When specified, will use this tsconfig for running tsx and type-checking (if enabled).
     *
     * @default - tsx/typescript default discovery
     */
    readonly tsconfig?: string;
}
/**
 * Options for the native Node.js TypeScript runner.
 */
export interface NodeRunnerOptions {
    /**
     * Whether to type-check the entrypoint before executing.
     *
     * Because the native Node.js TypeScript does not type check code,
     * you may want to enable this for additional type safety.
     * When enabled, runs `tsc --noEmit`, using the provided tsconfig.
     *
     * @default false
     */
    readonly typeCheck?: boolean;
    /**
     * Path to the tsconfig file for type-checking.
     * When specified, will use this tsconfig for type-checking (if enabled).
     *
     * @default - typescript default discovery
     */
    readonly tsconfig?: string;
    /**
     * Whether to also enable `--experimental-transform-types`.
     * @deprecated This flag has been removed from Node.js 26. Use `transformTypes` instead.
     * @default false
     */
    readonly experimentalTransformTypes?: boolean;
    /**
     * Whether to enable transformation of TypeScript-only syntax (e.g. enums, namespaces).
     *
     * Uses `amaro` (the TypeScript transformer used internally by Node.js) as an
     * external loader via `--import=amaro/transform`. Adds a dependency on the
     * `amaro` package and enables `--enable-source-maps` to preserve accurate
     * stack traces.
     *
     * @see https://github.com/nodejs/amaro
     * @default false
     */
    readonly transformTypes?: boolean;
}
/**
 * The options that can be adjusted on any {@link TypeScriptRunner}, regardless
 * of its runtime.
 *
 * This is the override type for {@link TypeScriptRunner.copy}. Runtime-specific
 * creation options (such as `swc` for ts-node) are set via the static factories
 * and are preserved - but cannot be changed - by `copy`, so a copy can never
 * change the runtime of a runner.
 */
export interface TypeScriptRunnerOptions {
    /**
     * Whether to type-check the entrypoint.
     */
    readonly typeCheck?: boolean;
    /**
     * Path to the tsconfig file to use.
     */
    readonly tsconfig?: string;
}
/**
 * The runner used to execute TypeScript files.
 *
 * A runner is a {@link FutureComponent}: create it standalone (e.g. via one of
 * the static factories) and it is attached to a project by the component that
 * consumes it. Use {@link TypeScriptRunner.copy} to derive a new runner with
 * adjusted options.
 */
export declare class TypeScriptRunner extends ScriptRunner {
    /**
     * Use ts-node to execute TypeScript files.
     */
    static tsNode(options?: TsNodeRunnerOptions): TypeScriptRunner;
    /**
     * Use tsx to execute TypeScript files.
     *
     * tsx is a fast TypeScript runtime that does not perform type-checking.
     * You may opt-in to an explicit type-checking step before the script is run.
     */
    static tsx(options?: TsxRunnerOptions): TypeScriptRunner;
    /**
     * Use the native Node.js TypeScript support.
     *
     * Requires Node.js 22.18.0 or later.
     * The script must use ESM style imports (no directories, include file endings, etc.).
     *
     * Named `nodejs` (not `node`) because a runner is a construct, and `node` is
     * reserved by `constructs.Construct` for the construct's tree node.
     */
    static nodejs(options?: NodeRunnerOptions): TypeScriptRunner;
    private readonly _kind;
    private readonly _options;
    private constructor();
    /**
     * Returns a new (detached) runner of the same kind, with `overrides` merged
     * over the current options.
     *
     * Safe to call while detached.
     */
    copy(overrides?: TypeScriptRunnerOptions): TypeScriptRunner;
    /**
     * Produce the {@link RunScriptConfig} to run the given entrypoint with this
     * runner.
     */
    configFor(entrypoint: string): RunScriptConfig;
    private renderTsNode;
    private renderTsx;
    private renderNode;
}