Skip to content

feat(config): accept CLI-only build flags in pkg config #263

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

Merged
robertsLando merged 11 commits into from
Apr 23, 2026
Merged

feat(config): accept CLI-only build flags in pkg config #263

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
28d6d7e
refactor(config): unify flag registry, phase-split resolveConfig
robertsLando Apr 23, 2026
697b02b
test(config): add pure-unit regression guard for parseInput/resolveFlags
robertsLando Apr 23, 2026
83d35c5
fix(config): address PR review feedback
robertsLando Apr 23, 2026
14ec429
refactor(config): enhance type safety for CLI argument parsing
robertsLando Apr 23, 2026
18d7780
refactor(config): improve type safety and clarity in CLI argument han…
robertsLando Apr 23, 2026
724ea8a
fix(config): address Copilot review feedback
robertsLando Apr 23, 2026
80f4fec
refactor(config): drop resolveTargetAlias helper
robertsLando Apr 23, 2026
16922e2
fix(config): address deep-review feedback
robertsLando Apr 23, 2026
258f090
fix(config): address Copilot review feedback
robertsLando Apr 23, 2026
d069fa2
docs(config): add JSDoc coverage across lib/config.ts
robertsLando Apr 23, 2026
144feea
fix(config): address Copilot review feedback
robertsLando Apr 23, 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
34 changes: 23 additions & 11 deletions docs-site/guide/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,17 +89,29 @@ 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[] | Target triples, e.g. `node22-linux-x64` — 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.) |
| `deployAssets` | boolean | Copy `assets` next to the executable at runtime instead of keeping them in the snapshot |
| 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` |

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

## Scripts

Expand Down
Loading
Loading