Skip to content
Effect Days 2026 Get your ticket

Build

Builds self-installing modules from ahead-of-time compiled Schema decoders.

6 exports Added in v4.0.0 Source

Compilation

build

Added in v4.0.0 Source

Writes a self-installing AOT module for Schema values exported by a set of modules.

When to use

Use when a build script should let an application install generated decoders by importing one generated module at startup.

Details

Module keys are import specifiers relative to baseUrl. Their loaders run sequentially during the build. The builder sorts module specifiers and export names, compiles direct Schema exports, and writes deterministic source using FileSystem. The generated module imports those exports and installs their decoders in the shared Schema parser registry as a module side effect. A lazy record returned by import.meta.glob can be passed as modules directly.

Decoding is prepared by default. is and make prepare the type-side AST; encode prepares the flipped AST. Nested dependencies are discovered by the AOT compiler and do not need separate exports.

Gotchas

Loaders execute application modules during the build. Each loader must return the same module named by its key. The generated file must be rebuilt after a schema definition or Effect version changes. Unsupported operations retain the interpreter fallback. Build configurations that mark modules as side-effect free must retain the generated import.

Signature

declare const build: (options: BuildOptions) => Effect.Effect<BuildResult, BuildError | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path>

Errors

BuildError

Added in v4.0.0 Source

An error raised while loading modules or generating an AOT module.

Signature

declare class BuildError extends YieldableError<this> & {
  readonly _tag: "BuildError";
} & Readonly<{
  readonly _tag: "BuildError";
  readonly cause: unknown;
  readonly kind: "Generate" | "InvalidModule" | "LoadModule" | "ResolveModule";
  readonly message: string;
  readonly module?: string;
}> {
  constructor(args: {
    readonly cause: unknown;
    readonly kind: "Generate" | "InvalidModule" | "LoadModule" | "ResolveModule";
    readonly message: string;
    readonly module?: string;
  });
}

Models

BuildOptions interface

Added in v4.0.0 Source

Options for build.

Signature

interface BuildOptions {
  readonly baseUrl: string | URL;
  readonly modules: Readonly<Record<string, ModuleLoader>>;
  readonly operations?: readonly Array<Operation>;
  readonly outFile: string;
}

BuildResult interface

Added in v4.0.0 Source

A summary of a completed build.

Signature

interface BuildResult {
  readonly modules: number;
  readonly outFile: string;
  readonly schemas: number;
}

ModuleLoader interface

Added in v4.0.0 Source

Loads the exports of a schema module during a build.

Signature

interface ModuleLoader {
  (): PromiseLike<unknown>;
}

Operation type

Added in v4.0.0 Source

An operation whose root AST should be prepared by build.

Signature

type Operation = "decode" | "encode" | "is" | "make"