Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

Build unstable

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

6 exports Since v4.0.0 Source

Compilation

build

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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 unstable
Since v4.0.0

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 unstable
Since v4.0.0

A summary of a completed build.

Signature

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

ModuleLoader

interface unstable
Since v4.0.0

Loads the exports of a schema module during a build.

Signature

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

Operation

type unstable
Since v4.0.0

An operation whose root AST should be prepared by build.

Signature

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