#Build and packaging

build.zig exposes the consumer build API. Its public surface includes Platform, Import, Dts, NpmConfig, LibOptions, and addLib.

#Build behavior

• addLib builds a host .node addon.
• -Dnpm=true enables release package generation and cross-compilation.
• -Dnpm-host=true restricts native compilation to the host platform.
• -Dnpm-only=name-a,name-b filters addons in multi-addon projects.
• Dts.none, Dts.file, and Dts.auto control declaration output.
• Dts.none omits both types and index.d.ts from the generated main manifest. When a release package switches to .none, reconciliation removes the build-owned index.d.ts and its managed files entry while preserving unrelated user files and manifest fields.

#Boundaries

• Keep generated package names, binary suffixes, binding paths, optional dependencies, and npm manifest fields compatible.
• Keep npmjs as the public registry and preserve public access.
• Treat linker flags, Windows import libraries, target lists, and generated manifests as release-critical.
• Test build graph changes with the fixture projects and CLI release tests, not only the repository's own build.

Relevant tests live in tests/cli/build-dev.test.ts, tests/cli/build-release.test.ts, tests/fixture-cli/, and tests/fixture-lib/.

#Internal structure

• Keep build.zig as the public facade for addLib, Platform, Import, Dts, NpmConfig, and LibOptions.
• Keep target definitions and npm suffix mapping in build/targets.zig.
• Keep OS-specific link configuration in build/linker.zig.
• Keep escaped npm manifest and loader rendering in build/npm_manifest.zig.
• Keep declaration and local entry generation in the existing build/*_emit.zig modules.

These modules are implementation details. Moving work between them must not change the public build.zig API, generated package names, or output layout.

Use the detailed build API, TypeScript declaration, cross-compiling, and publishing pages when changing their user-visible behavior.