Package.json Config

Overview

The primary way to configure Hakobu is through the "hakobu" field in your project's package.json. CLI flags override these values when both are provided.

package.json

{
  "name": "my-app",
  "version": "1.0.0",
  "main": "src/index.js",
  "hakobu": {
    "entry": "src/index.js",
    "target": "node24-linux-x64",
    "output": "./dist/my-app",
    "assets": ["templates/**", "public/**"],
    "compress": "brotli"
  }
}

Config Fields

Core Options

Field	Type	Default	Description
`entry`	`string`	`"main"` field in package.json	Entry file relative to the project root.
`target`	`string`	Host platform	Target specification (e.g., `"node24-linux-x64"`).
`targets`	`string[]`	—	Multiple targets (e.g., `["node24-linux-x64", "node24-win-x64"]`).
`output`	`string`	—	Output executable path (single target) or directory (multi-target).
`assets`	`string[]`	`[]`	Glob patterns for extra files to include in the snapshot filesystem.
`externals`	`string[]`	`[]`	Artifact names to keep outside the executable (e.g., native binaries that cannot be embedded).

Bundle Mode

Field	Type	Default	Description
`bundle`	`boolean \| string`	`false`	Enable bundle mode. Set to `true` or `"rolldown"` to pre-bundle with Rolldown before packaging. Useful for TypeScript and monorepo projects.
`bundleExternal`	`string[]`	`[]`	Modules to keep external when bundling (not resolved into the bundle).

Compilation and Compression

Field	Type	Default	Description
`bytecode`	`boolean`	`false`	Compile JS to V8 bytecode before packaging. Source maps are not available in bytecode mode.
`compress`	`"brotli" \| "gzip"`	None (uncompressed)	Compression algorithm for the snapshot payload.
`options`	`string[]`	—	V8 flags to bake into the executable. Each flag should be prefixed with `--` (e.g., `["--expose-gc", "--max-heap-size=34"]`).

Windows PE Metadata

The metadata object sets Windows VERSIONINFO fields and the application icon.

Field	Type	Description
`metadata.productName`	`string`	Product name shown in file properties.
`metadata.fileDescription`	`string`	Description shown in Task Manager.
`metadata.companyName`	`string`	Company or publisher name.
`metadata.legalCopyright`	`string`	Copyright notice.
`metadata.fileVersion`	`string`	File version (e.g., `"1.2.3"`).
`metadata.productVersion`	`string`	Product version (defaults to file version).
`metadata.icon`	`string`	Path to a `.ico` file to embed as the application icon.

macOS App Bundle

Field	Type	Default	Description
`appBundle`	`boolean`	`false`	Wrap macOS output in a `.app` bundle. Only valid for macOS targets.

The macos object provides metadata for Info.plist generation when appBundle is true.

Field	Type	Description
`macos.bundleId`	`string`	`CFBundleIdentifier` (e.g., `"com.example.my-app"`).
`macos.displayName`	`string`	`CFBundleDisplayName`.
`macos.bundleVersion`	`string`	`CFBundleVersion` (e.g., `"1.2.3"`).
`macos.shortVersion`	`string`	`CFBundleShortVersionString` (defaults to `bundleVersion`).
`macos.copyright`	`string`	`NSHumanReadableCopyright`.
`macos.icon`	`string`	Path to a `.icns` file for the app icon.

Linux AppDir / AppImage

Field	Type	Default	Description
`appDir`	`boolean`	`false`	Wrap Linux output in an AppDir. Only valid for Linux targets.
`appImage`	`boolean`	`false`	Build an AppImage from the AppDir. Implies `appDir`. Requires `appimagetool` in PATH.

The linux object provides metadata for .desktop file and AppStream metainfo generation.

Field	Type	Description
`linux.name`	`string`	Application name in the `.desktop` file.
`linux.comment`	`string`	Short description / tooltip.
`linux.categories`	`string`	Semicolon-separated categories (e.g., `"Utility;Development;"`).
`linux.terminal`	`boolean`	Whether the app needs a terminal (default: `true`).
`linux.icon`	`string`	Icon name for the `.desktop` file.
`linux.iconPath`	`string`	Path to a `.png` file for the application icon.
`linux.summary`	`string`	One-line summary for AppStream metainfo.
`linux.description`	`string`	Longer description for AppStream metainfo.
`linux.url`	`string`	Homepage URL for AppStream metainfo.
`linux.license`	`string`	SPDX license identifier (e.g., `"MIT"`, `"Apache-2.0"`).
`linux.version`	`string`	Application version for AppStream metainfo.

Complete Example

package.json

{
  "name": "my-app",
  "version": "2.0.0",
  "type": "module",
  "main": "src/index.js",
  "hakobu": {
    "entry": "src/cli.js",
    "target": "node24-linux-x64",
    "output": "./dist/my-app",
    "assets": [
      "templates/**",
      "public/**/*.html",
      "locales/*.json"
    ],
    "externals": ["better-sqlite3"],
    "compress": "brotli",
    "options": ["--expose-gc", "--max-heap-size=512"],
    "metadata": {
      "productName": "My App",
      "fileDescription": "My App CLI Tool",
      "companyName": "My Company",
      "fileVersion": "2.0.0",
      "icon": "assets/icon.ico"
    },
    "macos": {
      "bundleId": "com.mycompany.my-app",
      "displayName": "My App",
      "bundleVersion": "2.0.0",
      "copyright": "Copyright 2026 My Company",
      "icon": "assets/icon.icns"
    },
    "linux": {
      "name": "My App",
      "comment": "A CLI tool for doing things",
      "categories": "Utility;Development;",
      "terminal": true,
      "iconPath": "assets/icon.png",
      "license": "MIT"
    }
  }
}

The "pkg" field from @yao-pkg/pkg is still accepted, but it is deprecated. Hakobu reads it and emits migration warnings explaining how to update each option. Migrate to the "hakobu" field for long-term compatibility.

When Hakobu encounters a "pkg" field, it maps supported options automatically:

`pkg` field	Maps to	Notes
`pkg.scripts`	`hakobu.assets`	Merged into the assets list. In pkg, "scripts" were extra JS files to compile; Hakobu includes all reachable files automatically.
`pkg.assets`	`hakobu.assets`	Direct mapping.
`pkg.targets`	`hakobu.target`	Hakobu builds one target at a time. The first target is used.
`pkg.outputPath`	`hakobu.output`	Direct mapping.
`pkg.patches`	Not supported	Hakobu does not support source patching.
`pkg.dictionary`	Not supported	Hakobu resolves dependencies directly.
`pkg.deployFiles`	`hakobu.assets` or `hakobu.externals`	Use assets for files to embed, externals for files kept outside.
`pkg.ignore`	Not needed	Hakobu only includes files reachable from the entry point.

If both "hakobu" and "pkg" fields exist in the same package.json, the "hakobu" field takes priority and "pkg" is ignored entirely.

Example migration warnings you will see:

[config] Reading config from "pkg" field. Migrate to "hakobu" field for future compatibility.
[config] "pkg.scripts" mapped to "hakobu.assets". In Hakobu, use "assets" for extra files to include.

Config Priority

Hakobu resolves configuration in the following order (highest priority first):

CLI flags -- Always override everything else.
"hakobu" field -- The modern configuration source.
"pkg" field -- Legacy fallback, used only when "hakobu" is absent.