Build configuration

On this page

Import defineBuild from @maligator/cli in a trusted maligator.build.ts. These types describe build choices; the CLI validates the resulting value when loading configuration.

maligator.build.ts

import { defineBuild } from "@maligator/cli";

export default defineBuild({
	entry: "src/index.ts",
	outputName: "my-app",
	surface: { webPlatform: true },
});

All configuration fields are optional. Entries and asset paths resolve from the project root (the working directory), and an explicit CLI entry takes precedence. outputName must be a safe single filename component. Without it, the CLI uses the unscoped package name or directory name.

Configure a build explains feature selection. Embed files covers asset patterns and materialization. The signatures and field documentation below are extracted from the shipped declarations.

MaligatorIntlFeature

Service selections used when Intl is enabled; an empty list includes every service.

typescript

export type MaligatorIntlFeature =
	| "collator"
	| "number-format"
	| "date-time-format"
	| "plural-rules"
	| "list-format"
	| "segmenter"
	| "display-names"
	| "relative-time-format"
	| "duration-format";

AssetInclusion

Capture a regular file or a directory tree at build time. Paths are relative to the project root. Directory patterns support *, ?, and whole-segment **; every pattern must match a regular file. Symlinks are rejected.

typescript

export type AssetInclusion =
	| { type: "file"; path: string }
	| { type: "directory"; path: string; include: Array<string> };

MaligatorBuildConfig

Trusted, strictly validated configuration evaluated for each CLI invocation.

Full TypeScript declaration

typescript

export interface MaligatorBuildConfig {
	/** Project-root-relative entry; an explicit CLI entry takes precedence. */
	entry?: string;
	/** Binary name; otherwise inferred from the unscoped package name or project directory. */
	outputName?: string;
	/** Named build-time snapshots. Requires surface.maligator; portable serialized images cannot carry these filesystem resources. */
	assets?: Record<string, AssetInclusion>;
	modules?: {
		/** Exact specifier replacements applied before module resolution. Defaults to an empty map. */
		aliases?: Record<string, string>;
	};
	engine?: {
		/** Lock built-in objects for the entire build. Mutable is intended for compatibility experiments.
		 * @default "locked"
		 */
		primordials?: "locked" | "mutable";
		/** Control dynamic compilation. false leaves eval/Function present but makes calls throw;
		 * true embeds the compiler; compile-check also rejects statically visible calls at build time.
		 * @default false
		 * @see https://maligator.ddv.tools/api/build#engine.eval
		 */
		eval?: boolean | "compile-check";
		/** Include Realm support.
		 * @default false
		 */
		realms?: boolean;
		/** Include RegExp; disabling it trades compatibility for binary size.
		 * @default true
		 */
		regexp?: boolean;
		/** Include Temporal and its calendar/time-zone data.
		 * @default false
		 */
		temporal?: boolean;
		intl?: {
			/** Include internationalization services and their native data.
			 * @default false
			 */
			enabled?: boolean;
			/** Select services. An empty list includes all services when enabled.
			 * @default []
			 */
			features?: Array<MaligatorIntlFeature>;
			/** Locale-data filtering is not implemented; only an empty list is accepted.
			 * @default []
			 */
			languages?: Array<string>;
		};
	};
	surface?: {
		/** Include Web APIs and Mal.serve. Declarations alone do not enable them.
		 * @default false
		 */
		webPlatform?: boolean;
		/** Include supported node: modules; see the compatibility table for coverage.
		 * @default false
		 */
		node?: boolean;
		/** Include the mal namespace. Required for configured assets.
		 * @default true
		 */
		maligator?: boolean;
	};
}

Types: MaligatorIntlFeature, AssetInclusion

entry

Project-root-relative entry; an explicit CLI entry takes precedence.

typescript

entry?: string;

outputName

Binary name; otherwise inferred from the unscoped package name or project directory.

typescript

outputName?: string;

assets

Named build-time snapshots. Requires surface.maligator; portable serialized images cannot carry these filesystem resources.

typescript

assets?: Record<string, AssetInclusion>;

Types: AssetInclusion

modules

Full TypeScript declaration

typescript

modules?: {
		/** Exact specifier replacements applied before module resolution. Defaults to an empty map. */
		aliases?: Record<string, string>;
	};

modules.aliases

Exact specifier replacements applied before module resolution. Defaults to an empty map.

typescript

aliases?: Record<string, string>;

engine

Full TypeScript declaration

typescript

engine?: {
		/** Lock built-in objects for the entire build. Mutable is intended for compatibility experiments.
		 * @default "locked"
		 */
		primordials?: "locked" | "mutable";
		/** Control dynamic compilation. false leaves eval/Function present but makes calls throw;
		 * true embeds the compiler; compile-check also rejects statically visible calls at build time.
		 * @default false
		 * @see https://maligator.ddv.tools/api/build#engine.eval
		 */
		eval?: boolean | "compile-check";
		/** Include Realm support.
		 * @default false
		 */
		realms?: boolean;
		/** Include RegExp; disabling it trades compatibility for binary size.
		 * @default true
		 */
		regexp?: boolean;
		/** Include Temporal and its calendar/time-zone data.
		 * @default false
		 */
		temporal?: boolean;
		intl?: {
			/** Include internationalization services and their native data.
			 * @default false
			 */
			enabled?: boolean;
			/** Select services. An empty list includes all services when enabled.
			 * @default []
			 */
			features?: Array<MaligatorIntlFeature>;
			/** Locale-data filtering is not implemented; only an empty list is accepted.
			 * @default []
			 */
			languages?: Array<string>;
		};
	};

Types: MaligatorIntlFeature

engine.primordials

Lock built-in objects for the entire build. Mutable is intended for compatibility experiments. Default: "locked".

typescript

primordials?: "locked" | "mutable";

engine.eval

Control dynamic compilation. false leaves eval/Function present but makes calls throw; true embeds the compiler; compile-check also rejects statically visible calls at build time. Default: false.

typescript

eval?: boolean | "compile-check";

engine.realms

Include Realm support. Default: false.

typescript

realms?: boolean;

engine.regexp

Include RegExp; disabling it trades compatibility for binary size. Default: true.

typescript

regexp?: boolean;

engine.temporal

Include Temporal and its calendar/time-zone data. Default: false.

typescript

temporal?: boolean;

engine.intl

Full TypeScript declaration

typescript

intl?: {
			/** Include internationalization services and their native data.
			 * @default false
			 */
			enabled?: boolean;
			/** Select services. An empty list includes all services when enabled.
			 * @default []
			 */
			features?: Array<MaligatorIntlFeature>;
			/** Locale-data filtering is not implemented; only an empty list is accepted.
			 * @default []
			 */
			languages?: Array<string>;
		};

Types: MaligatorIntlFeature

engine.intl.enabled

Include internationalization services and their native data. Default: false.

typescript

enabled?: boolean;

engine.intl.features

Select services. An empty list includes all services when enabled. Default: [].

typescript

features?: Array<MaligatorIntlFeature>;

Types: MaligatorIntlFeature

engine.intl.languages

Locale-data filtering is not implemented; only an empty list is accepted. Default: [].

typescript

languages?: Array<string>;

surface

Full TypeScript declaration

typescript

surface?: {
		/** Include Web APIs and Mal.serve. Declarations alone do not enable them.
		 * @default false
		 */
		webPlatform?: boolean;
		/** Include supported node: modules; see the compatibility table for coverage.
		 * @default false
		 */
		node?: boolean;
		/** Include the mal namespace. Required for configured assets.
		 * @default true
		 */
		maligator?: boolean;
	};

surface.webPlatform

Include Web APIs and Mal.serve. Declarations alone do not enable them. Default: false.

typescript

webPlatform?: boolean;

surface.node

Include supported node: modules; see the compatibility table for coverage. Default: false.

typescript

node?: boolean;

surface.maligator

Include the mal namespace. Required for configured assets. Default: true.

typescript

maligator?: boolean;

defineBuild

Preserve the inferred config type. Validation happens when the CLI loads the config.

typescript

export declare function defineBuild<const Config extends MaligatorBuildConfig>(
	config: Config,
): Config;

Types: MaligatorBuildConfig

typescript

import { defineBuild } from "@maligator/cli";
export default defineBuild({ entry: "src/index.ts" });