Assets & Scripts

Hakobu can include non-code files -- templates, configuration, data files, and other static assets -- inside the packaged binary. These files are embedded in the snapshot filesystem and readable at runtime.

Declaring Assets

Use the "assets" field in your package.json to declare which files to include:

{
  "hakobu": {
    "assets": [
      "templates/**",
      "config.yaml",
      "locales/*.json"
    ]
  }
}

Asset paths support glob patterns. All matched files are included in the snapshot alongside your code.

Declaring Scripts

The "scripts" field lets you include additional JavaScript files that are not reachable through the normal require() / import dependency graph:

{
  "hakobu": {
    "scripts": [
      "workers/*.js",
      "plugins/**/*.js"
    ]
  }
}

This is useful for files that are loaded dynamically at runtime (e.g., worker scripts, plugin systems) where the analyzer cannot trace the dependency statically.

Accessing Assets at Runtime

Assets are embedded in the snapshot and accessible using standard fs APIs with __dirname-relative paths (CJS) or import.meta.url-derived paths (ESM).

CJS Example

const fs = require('fs');
const path = require('path');

const template = fs.readFileSync(
  path.join(__dirname, 'templates', 'email.html'),
  'utf-8'
);

ESM Example

import { readFileSync } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';

const __dirname = dirname(fileURLToPath(import.meta.url));

const config = JSON.parse(
  readFileSync(join(__dirname, 'config.yaml'), 'utf-8')
);

External Artifacts

For large files that should not be embedded in the binary (browsers, helper tools, large data files), use the "externals" config instead:

{
  "hakobu": {
    "externals": ["camoufox-browser"]
  }
}

External artifacts are resolved at runtime in the following order:

1. HAKOBU_EXTERNAL_{NAME} environment variable
2. {execDir}/externals/{name}/
3. Pattern path (absolute or relative to cwd)

This keeps the binary size manageable while still allowing your application to locate companion files at runtime.