Skip to content

feat: build hooks (preBuild, postBuild, per-file transform) #273

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
robertsLando wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat: build hooks (preBuild, postBuild, per-file transform) #273

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f133dd4
feat: build hooks (preBuild, postBuild, transform)
robertsLando Apr 27, 2026
8dc7ac2
refactor(types): extract PkgBaseOptions shared by config + API shapes
robertsLando Apr 27, 2026
f52b1a9
fix: address review feedback on build hooks
robertsLando Apr 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 111 additions & 19 deletions docs-site/guide/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,25 +58,28 @@ The strings are exactly what you'd pass on the command line — see [Getting sta

### `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). |
| 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](#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` | _(none — API only)_ | Per-file content transform (minify, obfuscate, etc.). |
Comment thread
robertsLando marked this conversation as resolved.
Outdated

## Build a full release pipeline

Expand Down Expand Up @@ -126,6 +129,95 @@ try {
}
```

## 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.

::: code-group

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

```json [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.

::: code-group

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

```json [package.json#pkg]
{
"pkg": {
"postBuild": "\"$PKG_OUTPUT\" --version"
}
}
Comment on lines +182 to +187
```

:::

### `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:

```js
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.
- 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.

## See also

- [CLI options](/guide/options)
Expand Down
45 changes: 24 additions & 21 deletions docs-site/guide/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,27 +89,30 @@ When both a pkgrc and a `pkg` field in `package.json` are present, the pkgrc win

## Full schema

| Key | Type | Description |
| ------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scripts` | glob \| string[] | JS files compiled to V8 bytecode and embedded without source — see [Scripts](#scripts) |
| `assets` | glob \| string[] | Files embedded as raw content, accessible under `/snapshot/` — see [Assets](#assets) |
| `ignore` | string[] | Globs excluded from the final executable — see [Ignore files](#ignore-files) |
| `targets` | string \| string[] | Target triples, e.g. `node22-linux-x64`; accepts a single target, an array, or a comma-separated string — see [Targets](/guide/targets) |
| `outputPath` | string | Directory for output binaries (equivalent to CLI `--out-path`) |
| `patches` | object | Patch modules that can't be packaged as-is — see [pkg source](https://github.com/yao-pkg/pkg/blob/main/dictionary/) for examples |
| `sea` | boolean | Opt into [SEA mode](/guide/sea-mode) without passing `--sea` |
| `seaConfig` | object | Forwarded to Node.js SEA config (`useCodeCache`, `disableExperimentalSEAWarning`, etc.) |
| `deployFiles` | tuple[] | Files that cannot be bundled; each entry is `[from, to]` or `[from, to, "directory"]`. pkg logs a reminder to ship each one next to the output at runtime |
| `compress` | string | VFS compression algorithm — `None` (default), `Brotli`, `GZip`, or `Zstd`. Equivalent to CLI `--compress` |
| `fallbackToSource` | boolean | Ship source when bytecode generation fails for a file. Equivalent to CLI `--fallback-to-source` |
| `public` | boolean | Speed up packaging and disclose top-level project sources. Equivalent to CLI `--public` |
| `publicPackages` | string \| string[] | Package names treated as public. Use `"*"` for all. Equivalent to CLI `--public-packages` |
| `options` | string \| string[] | V8 / Node options baked into the executable, e.g. `["expose-gc"]`. Equivalent to CLI `--options` |
| `bytecode` | boolean | Compile bytecode (default `true`). Set to `false` for source-only builds. Equivalent to CLI `--no-bytecode` |
| `nativeBuild` | boolean | Build native addons (default `true`). Equivalent to CLI `--no-native-build` (set `false`) |
| `noDictionary` | string \| string[] | Package names whose dictionary handling is skipped. Use `"*"` for all. Equivalent to CLI `--no-dict` |
| `debug` | boolean | Verbose packaging logs. Equivalent to CLI `--debug` |
| `signature` | boolean | Sign macOS binaries when applicable (default `true`). Equivalent to CLI `--signature` / `--no-signature` |
| Key | Type | Description |
| ------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scripts` | glob \| string[] | JS files compiled to V8 bytecode and embedded without source — see [Scripts](#scripts) |
| `assets` | glob \| string[] | Files embedded as raw content, accessible under `/snapshot/` — see [Assets](#assets) |
| `ignore` | string[] | Globs excluded from the final executable — see [Ignore files](#ignore-files) |
| `targets` | string \| string[] | Target triples, e.g. `node22-linux-x64`; accepts a single target, an array, or a comma-separated string — see [Targets](/guide/targets) |
| `outputPath` | string | Directory for output binaries (equivalent to CLI `--out-path`) |
| `patches` | object | Patch modules that can't be packaged as-is — see [pkg source](https://github.com/yao-pkg/pkg/blob/main/dictionary/) for examples |
| `sea` | boolean | Opt into [SEA mode](/guide/sea-mode) without passing `--sea` |
| `seaConfig` | object | Forwarded to Node.js SEA config (`useCodeCache`, `disableExperimentalSEAWarning`, etc.) |
| `deployFiles` | tuple[] | Files that cannot be bundled; each entry is `[from, to]` or `[from, to, "directory"]`. pkg logs a reminder to ship each one next to the output at runtime |
| `compress` | string | VFS compression algorithm — `None` (default), `Brotli`, `GZip`, or `Zstd`. Equivalent to CLI `--compress` |
| `fallbackToSource` | boolean | Ship source when bytecode generation fails for a file. Equivalent to CLI `--fallback-to-source` |
| `public` | boolean | Speed up packaging and disclose top-level project sources. Equivalent to CLI `--public` |
| `publicPackages` | string \| string[] | Package names treated as public. Use `"*"` for all. Equivalent to CLI `--public-packages` |
| `options` | string \| string[] | V8 / Node options baked into the executable, e.g. `["expose-gc"]`. Equivalent to CLI `--options` |
| `bytecode` | boolean | Compile bytecode (default `true`). Set to `false` for source-only builds. Equivalent to CLI `--no-bytecode` |
| `nativeBuild` | boolean | Build native addons (default `true`). Equivalent to CLI `--no-native-build` (set `false`) |
| `noDictionary` | string \| string[] | Package names whose dictionary handling is skipped. Use `"*"` for all. Equivalent to CLI `--no-dict` |
| `debug` | boolean | Verbose packaging logs. Equivalent to CLI `--debug` |
| `signature` | boolean | Sign macOS binaries when applicable (default `true`). Equivalent to CLI `--signature` / `--no-signature` |
| `preBuild` | string \| function | Shell command or JS function run once before the walker — see [Build hooks](/guide/api#build-hooks) |
| `postBuild` | string \| function | Shell command or JS function run once per produced binary; shell form receives the path via `PKG_OUTPUT` |
| `transform` | function | Per-file content transform applied between the walker and bytecode/compression — function-only, reachable from the Node.js API or `pkg.config.{js,cjs,mjs}` |

CLI flags always override config values. Unknown keys under `pkg` produce a warning.

Expand Down
Loading
Loading