esbuild-yaml

3.2.1 verified Mon Apr 27 auth: no javascript

An esbuild plugin for importing YAML files as JavaScript objects or raw strings. Current stable version is 3.2.1, requiring Node >=20 and esbuild >=0.19.0. Supports both YAML and YAML Multi-Document files. Differentiates itself via a simple API, TypeScript support, and the ability to import YAML files as both parsed objects and raw strings using a ?raw query suffix. It leverages the yaml library internally since version 2.0.0 (previously js-yaml).

Common errors

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

cause The package is not installed or is a dev dependency not available at runtime.

fix

Run 'npm install --save-dev esbuild-yaml esbuild' to install as dev dependency.

error TypeError: YAMLPlugin is not a constructor ↓

cause Trying to use YAMLPlugin without calling it as a function (e.g., plugins: [YAMLPlugin] instead of plugins: [YAMLPlugin()])

fix

Use YAMLPlugin() in the plugins array.

error Module not found: Error: Can't resolve './file.yaml' ↓

cause YAMLPlugin is not loaded or not properly configured in the esbuild build.

fix

Ensure the YAMLPlugin is added to the plugins array in esbuild's build options.

error node:internal/modules/cjs/loader:1078 - throw err; Error: Cannot find module 'yaml' ↓

cause The 'yaml' peer dependency is missing.

fix

Install yaml: npm install yaml (or ensure it is included via esbuild-yaml's dependencies).

Warnings

breaking v3.0.0 drops support for Node 18. Requires Node >=20. ↓

fix Upgrade Node.js to version 20 or higher.

breaking v2.0.0 migrates from js-yaml to yaml, which may change parsing behavior for some edge cases (e.g., custom tags, schema). ↓

fix Review YAML files for compatibility with the yaml library. See https://eemeli.org/yaml/

deprecated v1.3.0 requires esbuild version >=0.19.0. Older esbuild versions (e.g., 0.18.x) will not work. ↓

fix Update esbuild to at least version 0.19.0.

gotcha The YAMLPlugin must be instantiated as a function call YAMLPlugin() - passing it directly as an object will not work. ↓

fix Use YAMLPlugin() (with parentheses) in the plugins array.

Install

npm install esbuild-yaml

yarn add esbuild-yaml

pnpm add esbuild-yaml

Imports

YAMLPlugin

wrong

const YAMLPlugin = require('esbuild-yaml')

correct

import { YAMLPlugin } from 'esbuild-yaml'

ESM-only package; CommonJS require not supported.

YAMLPlugin

wrong

const { YAMLPlugin } = require('esbuild-yaml')

correct

const { YAMLPlugin } = await import('esbuild-yaml')

Dynamic import works in CommonJS modules with top-level await.

type YAMLPluginOptions

wrong

import { YAMLPluginOptions } from 'esbuild-yaml'

correct

import type { YAMLPluginOptions } from 'esbuild-yaml'

Use 'import type' for type-only imports to avoid runtime errors.

Quickstart

Shows how to use YAMLPlugin with esbuild to import YAML files as objects.

import { build } from 'esbuild';
import { YAMLPlugin } from 'esbuild-yaml';

build({
  entryPoints: ['src/index.ts'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [YAMLPlugin()],
}).catch(() => process.exit(1));

// Then in src/index.ts:
// import config from './config.yaml';
// console.log(config); // { name: "esbuild-yaml", version: "1.0.0" }