import Hexo from './src/hexo-core/hexo';
const hexo = new Hexo(process.cwd(), { silent: true });

4. Required env layout: the base directory passed to Box must end with the OS path separator; this is handled automatically by Box's constructor. No additional env vars are required beyond a valid Hexo site directory.

5. Call hexo.init() before any other operation. It loads config, registers models, and initialises all built-in plugins.

Public API

Box

class Box extends EventEmitter {
  constructor(ctx: Hexo, base: string, options?: Partial<BoxOptions>);
  processors: Processor[];
  watcher: Awaited<ReturnType<typeof watch>> | null;
  process(): Promise<void>;
  watch(): Promise<void>;
  unwatch(): void;
  isWatching(): boolean;
  addProcessor(pattern: Pattern, fn: (file?: File) => any): void;
}

Box is the file-processing pipeline. Instantiate it with a Hexo context and a base directory, register processors via addProcessor, then call process() to scan and process all matching files. Used internally by Source and Theme but can be used standalone.

extend/index exports (Filter, Generator, Processor, Renderer, etc.)

import { Filter, Generator, Renderer, Tag, Console } from './src/hexo-core/extend';

// Filter
filter.register(type: string, fn: Function, options?: FilterOptions): void;

// Generator
generator.register(name: string, fn: (locals: SiteLocals) => BaseGeneratorReturn | BaseGeneratorReturn[]): void;

// Renderer
renderer.register(name: string, output: string, fn: Function, sync?: boolean): void;

These registries are accessible via hexo.extend.*. Register custom filters to transform content at named pipeline points, generators to produce output routes, and renderers to handle new file extensions.

Hexo (main class)

class Hexo extends EventEmitter {
  constructor(base: string, args?: Record<string, any>);
  version: string;
  base_dir: string;
  public_dir: string;
  source_dir: string;
  config: Record<string, any>;
  extend: { console: Console; filter: Filter; generator: Generator; /* … */ };
  route: Router;
  init(): Promise<void>;
  load(): Promise<void>;
  watch(): Promise<void>;
  unwatch(): Promise<void>;
  exit(err?: Error): Promise<void>;
  call(name: string, args?: Record<string, any>): Promise<void>;
  model(name: string, schema?: Schema): any;
}

The central orchestrator. Call init() then load() to populate the database and route map. Use call('generate') to trigger the built-in generate console command programmatically.

Working examples

Scenario - Programmatic site generation

Instantiate Hexo, load the site, and generate static output into public/ without using the CLI.

import Hexo from './src/hexo-core/hexo';
import { join } from 'path';

async function build(siteDir: string): Promise<void> {
  const hexo = new Hexo(siteDir, { silent: false });
  await hexo.init();
  await hexo.load();
  await hexo.call('generate', { force: true });
  await hexo.exit();
}

build(join(__dirname, 'my-hexo-site')).catch(err => {
  console.error(err);
  process.exit(1);
});

Scenario - Registering a custom filter

Inject a custom filter into the post-render pipeline to append a disclaimer to every post.

import Hexo from './src/hexo-core/hexo';

async function withCustomFilter(siteDir: string): Promise<void> {
  const hexo = new Hexo(siteDir, { silent: true });
  await hexo.init();

  hexo.extend.filter.register('after_post_render', function(data) {
    data.content += '\n<p class="disclaimer">Views are my own.</p>';
    return data;
  });

  await hexo.load();
  await hexo.call('generate', {});
  await hexo.exit();
}

Scenario - Registering a custom generator

Produce an extra JSON route (/api/posts.json) that lists all post titles.

import Hexo from './src/hexo-core/hexo';
import type { SiteLocals, BaseGeneratorReturn } from './src/hexo-core/types';

async function withApiRoute(siteDir: string): Promise<void> {
  const hexo = new Hexo(siteDir, { silent: true });
  await hexo.init();

  hexo.extend.generator.register('api_posts', function(locals: SiteLocals): BaseGeneratorReturn {
    const titles = locals.posts.toArray().map((p: any) => p.title);
    return {
      path: 'api/posts.json',
      data: JSON.stringify(titles)
    };
  });

  await hexo.load();
  await hexo.call('generate', {});
  await hexo.exit();
}

Scenario - Using Box directly for custom file watching

Attach a Box to an arbitrary directory and process matched files.

import Hexo from './src/hexo-core/hexo';
import Box from './src/hexo-core/box';
import { Pattern } from 'hexo-util';

async function watchData(siteDir: string): Promise<void> {
  const hexo = new Hexo(siteDir, { silent: true });
  await hexo.init();

  const dataBox = new Box(hexo, siteDir + '/data/');
  const jsonPattern = new Pattern(/\.json$/);

  dataBox.addProcessor(jsonPattern, async (file) => {
    if (!file) return;
    console.log('Processing:', file.path);
  });

  await dataBox.watch();
}

File walkthrough

• box/index.ts - Box class: scans a directory, caches checksums, dispatches matched files to registered Processor handlers, supports live watching via hexo-fs.
• box/file.ts - File abstraction used inside Box; holds path, type (create/update/delete/skip), and read helpers.
• extend/console.ts - Registry for CLI command handlers registered with hexo.extend.console.register.
• extend/filter.ts - Ordered filter chain; filters run sequentially and can mutate data at named hook points.
• extend/generator.ts - Registry that maps generator functions to output route objects.
• extend/renderer.ts - Maps source extensions to output-format render functions (sync and async).
• extend/tag.ts - Nunjucks tag extension registry for custom template tags.
• extend/injector.ts - HTML injection registry for inserting <script>/<style> into rendered pages.
• extend/index.ts - Re-exports all extension registries as named exports.
• hexo/index.ts - Main Hexo class; composes all subsystems and orchestrates init/load/generate/watch lifecycle.
• hexo/default_config.ts - Default values for _config.yml fields.
• hexo/post.ts - Post creation logic (hexo new), front-matter scaffolding.
• hexo/render.ts - Render helpers that delegate to the Renderer registry.
• hexo/router.ts - In-memory route map storing generated file paths and their data streams.
• hexo/load_config.ts - Reads and merges _config.yml with CLI overrides.
• hexo/register_models.ts - Registers all Warehouse models on the database.
• models/post.ts - Warehouse schema for blog posts (title, date, tags, categories, slug, etc.).
• models/page.ts - Warehouse schema for standalone pages.
• models/category.ts / models/tag.ts - Taxonomy models with parent/child relations.
• models/asset.ts / models/post_asset.ts - File asset tracking models.
• models/cache.ts - SHA-1 based file cache to skip unchanged files.
• plugins/console/ - Built-in CLI commands: clean, config, deploy, generate, list, migrate, new, publish, render.
• plugins/filter/ - Built-in filter implementations (after_post_render, after_render, before_exit, etc.).
• plugins/generator/ - Built-in generators (posts, pages, categories, tags, assets).
• plugins/renderer/ - Built-in renderers (Nunjucks, Markdown via hexo-util).
• plugins/highlight/ - Syntax highlight integration bridging hexo-util highlight engines.
• theme/ - Theme Box subclass and config loader.
• types.ts - Shared TypeScript interfaces used across the codebase.

Common pitfalls and fixes

• hexo.init() not awaited before hexo.extend access - Always await hexo.init() before registering extensions or calling hexo.load(); the registry is not ready until init completes.
• Box base path missing trailing separator - Box appends the OS sep automatically, but if you construct paths manually ensure they are absolute; relative paths cause silent cache mismatches.
• Warehouse model schema conflicts - Calling hexo.model('Post') before register_models runs will return an unschemaed collection; let hexo.init() register models first.
• CJS/ESM interop with warehouse - warehouse ships CJS; if your project uses "type": "module", import via createRequire or set "esModuleInterop": true in tsconfig.
• bluebird Promise vs native Promise - Internal code mixes Bluebird and native Promises; do not Promise.resolve() a Bluebird chain in contexts that expect native thenables without verifying compatibility.
• hexo-fs watch on Linux requires inotify limits - For large sites increase fs.inotify.max_user_watches (sudo sysctl fs.inotify.max_user_watches=524288).

Vibe-coding prompt template

I have a copy of the Hexo core library source (hexo@8.1.2) located in `src/hexo-core/`
and a usage guide in `USAGE.md`. Please help me integrate it into my existing
Node.js/TypeScript project step by step.

Context:
- Source root: src/hexo-core/ (mirrors the upstream `lib/` folder)
- Main entry: src/hexo-core/hexo/index.ts (exports the `Hexo` class)
- Extension registries: src/hexo-core/extend/index.ts
- Types: src/hexo-core/types.ts
- Upstream package: user@example.com

Tasks:
1. Add the required npm dependencies listed in USAGE.md to my package.json.
2. Update tsconfig.json with the path aliases shown in USAGE.md.
3. Create a `buildSite.ts` script that instantiates `Hexo`, registers any
   custom filters or generators I describe, calls `generate`, and exits cleanly.
4. Show me how to add a custom Generator that produces `/api/posts.json`.
5. Explain how to watch for file changes and rebuild incrementally using
   `hexo.watch()` and `Box`.
6. Identify any import paths that need adjusting for my project structure.

Only use symbols and APIs visible in USAGE.md and the source excerpts provided.
Do not invent new APIs.

License and credit

Hexo is licensed under the MIT License. See source/LICENSE if present, or the official repository for the full license text. Upstream package: hexo on npm.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.