Node.js API

In addition to the CLI, pkg exposes a small programmatic API so you can drive builds from a Node.js script — useful for custom release pipelines, CI integration, or wrapping pkg inside a bigger build tool.

Install

npm install --save-dev @yao-pkg/pkg

Import

CommonJS

const { exec } = require('@yao-pkg/pkg');

ESM

import { exec } from '@yao-pkg/pkg';

exec()

exec() accepts either a CLI-style argv array or a typed options object, and returns a Promise<void> that resolves when the build is complete, or rejects on failure.

Options object (recommended)

import { exec, PkgExecOptions } from '@yao-pkg/pkg';

await exec({
  input: 'index.js',
  targets: ['node22-linux-x64'],
  output: 'dist/app',
  compress: 'Brotli',
});

Only input is required. Everything else mirrors the CLI flags — see the full field list below.

Argv array

const { exec } = require('@yao-pkg/pkg');

await exec(['index.js', '--target', 'host', '--output', 'dist/app']);

The strings are exactly what you'd pass on the command line — see Getting started → CLI reference.

PkgExecOptions fields

Field	Type	CLI equivalent	Notes
input	string	positional <input>	Required. Entry file or directory.
targets	string[]	--targets	e.g. ['host'] or ['node22-linux-x64', ...].
config	string	--config	Path to package.json or standalone config JSON.
output	string	--output	Output file name or template.
outputPath	string	--out-path	Output directory (mutually exclusive with output).
compress	'None' | 'Brotli' | 'GZip' | 'Zstd'	--compress	Default 'None'.
sea	boolean	--sea	Use Single Executable Application mode.
bakeOptions	string | string[]	--options	Node/V8 flags baked into the binary (e.g. ['expose-gc']).
debug	boolean	--debug	Verbose packaging logs.
build	boolean	--build	Build base binaries from source.
bytecode	boolean	--no-bytecode	Default true. Set false to ship plain JS.
nativeBuild	boolean	--no-native-build	Default true.
fallbackToSource	boolean	--fallback-to-source	Ship source when bytecode compile fails.
public	boolean	--public	Top-level project is public.
publicPackages	string[]	--public-packages	Use ['*'] for all.
noDictionary	string[]	--no-dict	Use ['*'] to disable all dictionaries.
signature	boolean	--no-signature	Default true (macOS signing when applicable).
preBuild	string | (() => void | Promise<void>)	(none — API/config)	Shell command or function run before the walker. See Build hooks.
postBuild	string | ((output: string) => void | Promise<void>)	(none — API/config)	Run once per produced binary. Shell form receives PKG_OUTPUT env.
transform	(file: string, contents: Buffer | string) => Buffer | string | void | Promise<Buffer | string | void>	(none — API/JS config)	Per-file content transform (minify, obfuscate, etc.). Async returns are awaited. Function-only, so not available from JSON config.

Build a full release pipeline

const { exec } = require('@yao-pkg/pkg');
const { mkdir, rm } = require('node:fs/promises');
const path = require('node:path');

const DIST = 'dist';
const TARGETS = [
  'node22-linux-x64',
  'node22-linux-arm64',
  'node22-macos-arm64',
  'node22-win-x64',
];

async function build() {
  await rm(DIST, { recursive: true, force: true });
  await mkdir(DIST, { recursive: true });

  await exec({
    input: '.',
    targets: TARGETS,
    outputPath: DIST,
    compress: 'Brotli',
  });

  console.log(`built ${TARGETS.length} binaries into ${path.resolve(DIST)}`);
}

build().catch((err) => {
  console.error(err);
  process.exit(1);
});

Error handling

exec rejects with an Error whose message contains the same diagnostic you'd see on the CLI. Wrap in try/catch (or chain .catch) if you need to react to specific failures:

try {
  await exec(['bad/input.js']);
} catch (err) {
  console.error('pkg build failed:', err.message);
  process.exitCode = 1;
}

Build hooks

pkg exposes three hooks that run at well-defined points in the build pipeline. They turn shell scripts that previously had to wrap pkg (pre-bundle, smoke-test, minify, etc.) into first-class config.

Lifecycle order

preBuild → walk → transform (per file) → bytecode/compression → write → postBuild (per binary)

preBuild

Runs once before the walker collects files. Use it for setup work — pre-bundling with esbuild/webpack, codegen, fetching assets. Throw or exit non-zero to abort the build.

Function

await exec({
  input: 'src/index.js',
  preBuild: async () => {
    await build({ entryPoints: ['src/index.js'], outfile: 'dist/bundle.js' });
  },
});

package.json#pkg

{
  "pkg": {
    "preBuild": "esbuild src/index.js --bundle --outfile=dist/bundle.js"
  }
}

postBuild

Runs once per produced binary, after the file has been written and (where applicable) codesigned. Use it for smoke tests, signing, notarization, upload. The shell form receives the absolute output path via the PKG_OUTPUT environment variable; the function form receives it as the first argument.

Function

await exec({
  input: 'src/index.js',
  postBuild: async (output) => {
    await execFileAsync(output, ['--version']);
  },
});

package.json#pkg

{
  "pkg": {
    "postBuild": "\"$PKG_OUTPUT\" --version"
  }
}

transform

JS-function-only — applied to each file the walker collected, after refinement and before bytecode/compression. Receives the absolute on-disk path and current contents, returns the replacement (a Buffer or string) or undefined/void to leave the file unchanged.

transform is the hook for minification and obfuscation — pkg deliberately ships no minifier of its own so the runtime dependency footprint stays small. Drop in your tool of choice:

import { exec } from '@yao-pkg/pkg';
import { minify } from 'terser';

await exec({
  input: 'src/index.js',
  output: 'dist/app',
  transform: async (file, contents) => {
    if (!file.endsWith('.js')) return; // leave non-JS untouched
    const { code } = await minify(contents.toString());
    return code;
  },
});

The transform sees the exact set of files pkg is embedding (walker output, post-refine), never the user's source tree on disk — so the original repo is left intact.

Notes

• Shell hooks are spawned with shell: true and inherit stdio, so the user sees their tool's live output. Non-zero exit fails the build.
• Function-form hooks are reachable from the Node.js API and from pkg.config.{js,cjs,mjs} (which can export a function value); JSON-format config (package.json#pkg, .pkgrc, .pkgrc.json) can only carry the shell-string form.
• transform receives every embedded file — JS, JSON, assets, native .node addons, anything the walker collected. Filter by path.extname(file) (or your matcher of choice) before rewriting; returning a string for binary content will corrupt it.
• In simple SEA mode (--sea without a package.json), transform is a no-op — there's no walker output to apply per-file rewrites to. preBuild and postBuild still run.
• In enhanced SEA mode, all targets are baked in parallel and postBuild only fires once all binaries are baked (then runs sequentially per target). The traditional pipeline produces targets serially, so postBuild for each target fires before the next one starts. Both modes call postBuild exactly once per produced binary; only the relative timing differs.

See also

• CLI options
• Recipes: build in CI