hexo-esbuild

2.0.0 verified Fri May 01 auth: no javascript

Hexo plugin to transform JavaScript, CSS, TypeScript, and JSX files using esbuild's transform API. Current stable version is 2.0.0, with major version bumps aligning with esbuild updates (e.g., esbuild 0.25.0). Key differentiators: integrates esbuild into Hexo's filter system, supports per-type configuration (JS, CSS, TS, JSX), micromatch-based exclusion, and configurable priority. Actively maintained by uiolee with regular releases via changesets. Compared to alternatives (hexo-optimize, hexo-babel), hexo-esbuild leverages esbuild for fast, minimal transforms.

Common errors

error Error: Cannot find module 'hexo-esbuild' ↓

cause Package not installed or wrong import path.

fix

Run: npm install hexo-esbuild, then import using 'hexo-esbuild' (not './hexo-esbuild').

error TypeError: hexoEsbuild is not a function ↓

cause Using require() with ESM-only package (v2.0.0+).

fix

Use import syntax: import hexoEsbuild from 'hexo-esbuild'; Or downgrade to v1.x.

error Invalid configuration key: hexo_esbuild ↓

cause Misplaced config in _config.yml (e.g., nested under another key).

fix

Ensure 'hexo_esbuild' is a top-level key in _config.yml.

error esbuild: unexpected argument '0.25.0' ↓

cause Incompatible esbuild version installed (requires ^0.25.0).

fix

Install esbuild version matching peer dependency: npm install esbuild@^0.25.0

Warnings

breaking v2.0.0 requires esbuild >=0.25.0 (was ^0.25.0). Projects with older esbuild versions will break. ↓

fix Update esbuild to ^0.25.0: npm install esbuild@latest

gotcha Package is ESM-only since v2.0.0. require() will fail if not using ESM. ↓

fix Use import syntax and ensure your project is ESM-compatible (module in package.json, .mjs extension).

gotcha Configuration must be placed under 'hexo_esbuild' key in _config.yml – common mistake to put it at root. ↓

fix Ensure config namespace matches: hexo_esbuild: ...

gotcha Exclude patterns are passed to micromatch – glob patterns are not always compatible with minimatch. Wrong patterns may silently ignore files. ↓

fix Use micromatch-compatible glob patterns (e.g., '**.min.js' not '**/*.min.js').

deprecated The 'minify' option inside esbuildTransformOptions may be overridden by esbuild's own minification settings in future versions. ↓

fix Set minify explicitly: true or false as needed.

Install

npm install hexo-esbuild

yarn add hexo-esbuild

pnpm add hexo-esbuild

Imports

hexo-esbuild
wrong
```
const hexoEsbuild = require('hexo-esbuild');
```
correct
```
import hexoEsbuild from 'hexo-esbuild';
```
Package is ESM-only as of v2.0.0. Use import syntax in ES modules context.
HexoEsbuildConfig
```
import type { HexoEsbuildConfig } from 'hexo-esbuild';
```
TypeScript users can import the config type for type-safe configuration.
defaultConfig
```
import { defaultConfig } from 'hexo-esbuild';
```
Named export of the default configuration object. Available since v1.0.0.

Quickstart

Basic configuration to enable JavaScript and CSS minification via esbuild in Hexo.

// hexo/_config.yml
hexo_esbuild:
  enable: true
  js:
    esbuildTransformOptions:
      loader: 'js'
      minify: true
  css:
    esbuildTransformOptions:
      loader: 'css'
      minify: true