esbuild-yaml

library3.2.1jsnpmunverified

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).

serialization web-framework

npm install esbuild-yaml

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-YAML

esbuild-yaml

serializationjavascriptv3.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

YAMLPlugin

✓ import { YAMLPlugin } from 'esbuild-yaml'

✗ const YAMLPlugin = require('esbuild-yaml')

ESM-only package; CommonJS require not supported.

YAMLPlugin

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

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

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

type YAMLPluginOptions

✓ import type { YAMLPluginOptions } from 'esbuild-yaml'

✗ import { YAMLPluginOptions } from 'esbuild-yaml'

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

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" }

Debug

Known issues

breakingv3.0.0 drops support for Node 18. Requires Node >=20.

fix

Upgrade Node.js to version 20 or higher.

affects: >=3.0.0

breakingv2.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/

affects: >=2.0.0 <3.0.0

deprecatedv1.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.

affects: >=1.3.0 <2.0.0

gotchaThe 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.

affects: >0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'esbuild-yaml'

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.

TypeError: YAMLPlugin is not a constructor

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.

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

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.

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

The 'yaml' peer dependency is missing.

fix

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

Upgrade

Version history

3.2.1latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency required to use esbuild plugins

yamlrequiredRuntime dependency for parsing YAML files

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/luxass/esbuild-yaml ↗

packagehttps://www.npmjs.com/package/esbuild-yaml ↗