# Build configuration

Maligator 0.1.0-alpha.27 · Experimental
Source revision: 96c331078104a0c9275238dbd0a714f5c48a53b6
Canonical: https://maligator.ddv.tools/api/build

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.

```typescript 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](/guides/build-configuration) explains feature selection. [Embed files](/guides/assets) covers asset patterns and materialization. The signatures and field documentation below are extracted from the shipped declarations.

<a id="MaligatorIntlFeature"></a>

## 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";
```


<a id="AssetInclusion"></a>

## 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> };
```


<a id="MaligatorBuildConfig"></a>

## MaligatorBuildConfig

Trusted, strictly validated configuration evaluated for each CLI invocation.
<details><summary>Full TypeScript declaration</summary>


```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`](/api/build#MaligatorIntlFeature), [`AssetInclusion`](/api/build#AssetInclusion)


</details>


<a id="entry"></a>

### entry

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

```typescript
entry?: string;
```


<a id="outputName"></a>

### outputName

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

```typescript
outputName?: string;
```


<a id="assets"></a>

### assets

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

```typescript
assets?: Record<string, AssetInclusion>;
```

Types: [`AssetInclusion`](/api/build#AssetInclusion)



<a id="modules"></a>

### modules


<details><summary>Full TypeScript declaration</summary>


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

</details>


<a id="modules.aliases"></a>

### modules.aliases

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

```typescript
aliases?: Record<string, string>;
```


<a id="engine"></a>

### engine


<details><summary>Full TypeScript declaration</summary>


```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`](/api/build#MaligatorIntlFeature)


</details>


<a id="engine.primordials"></a>

### engine.primordials

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

```typescript
primordials?: "locked" | "mutable";
```


<a id="engine.eval"></a>

### 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";
```


<a id="engine.realms"></a>

### engine.realms

Include Realm support.
Default: `false`.

```typescript
realms?: boolean;
```


<a id="engine.regexp"></a>

### engine.regexp

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

```typescript
regexp?: boolean;
```


<a id="engine.temporal"></a>

### engine.temporal

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

```typescript
temporal?: boolean;
```


<a id="engine.intl"></a>

### engine.intl


<details><summary>Full TypeScript declaration</summary>


```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`](/api/build#MaligatorIntlFeature)


</details>


<a id="engine.intl.enabled"></a>

### engine.intl.enabled

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

```typescript
enabled?: boolean;
```


<a id="engine.intl.features"></a>

### engine.intl.features

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

```typescript
features?: Array<MaligatorIntlFeature>;
```

Types: [`MaligatorIntlFeature`](/api/build#MaligatorIntlFeature)



<a id="engine.intl.languages"></a>

### engine.intl.languages

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

```typescript
languages?: Array<string>;
```


<a id="surface"></a>

### surface


<details><summary>Full TypeScript declaration</summary>


```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;
	};
```

</details>


<a id="surface.webPlatform"></a>

### surface.webPlatform

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

```typescript
webPlatform?: boolean;
```


<a id="surface.node"></a>

### surface.node

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

```typescript
node?: boolean;
```


<a id="surface.maligator"></a>

### surface.maligator

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

```typescript
maligator?: boolean;
```


<a id="defineBuild"></a>

## defineBuild

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

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

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

Types: [`MaligatorBuildConfig`](/api/build#MaligatorBuildConfig)