{"id":21298,"library":"esbuild-yaml","title":"esbuild-yaml","description":"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).","status":"active","version":"3.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/luxass/esbuild-yaml","tags":["javascript","esbuild","plugin","yaml","yaml import","yaml plugin","yaml esbuild","typescript"],"install":[{"cmd":"npm install esbuild-yaml","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-yaml","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-yaml","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required to use esbuild plugins","package":"esbuild","optional":false},{"reason":"Runtime dependency for parsing YAML files","package":"yaml","optional":false}],"imports":[{"note":"ESM-only package; CommonJS require not supported.","wrong":"const YAMLPlugin = require('esbuild-yaml')","symbol":"YAMLPlugin","correct":"import { YAMLPlugin } from 'esbuild-yaml'"},{"note":"Dynamic import works in CommonJS modules with top-level await.","wrong":"const { YAMLPlugin } = require('esbuild-yaml')","symbol":"YAMLPlugin","correct":"const { YAMLPlugin } = await import('esbuild-yaml')"},{"note":"Use 'import type' for type-only imports to avoid runtime errors.","wrong":"import { YAMLPluginOptions } from 'esbuild-yaml'","symbol":"type YAMLPluginOptions","correct":"import type { YAMLPluginOptions } from 'esbuild-yaml'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { YAMLPlugin } from 'esbuild-yaml';\n\nbuild({\n  entryPoints: ['src/index.ts'],\n  outfile: 'dist/bundle.js',\n  bundle: true,\n  plugins: [YAMLPlugin()],\n}).catch(() => process.exit(1));\n\n// Then in src/index.ts:\n// import config from './config.yaml';\n// console.log(config); // { name: \"esbuild-yaml\", version: \"1.0.0\" }","lang":"typescript","description":"Shows how to use YAMLPlugin with esbuild to import YAML files as objects."},"warnings":[{"fix":"Upgrade Node.js to version 20 or higher.","message":"v3.0.0 drops support for Node 18. Requires Node >=20.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review YAML files for compatibility with the yaml library. See https://eemeli.org/yaml/","message":"v2.0.0 migrates from js-yaml to yaml, which may change parsing behavior for some edge cases (e.g., custom tags, schema).","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Update esbuild to at least version 0.19.0.","message":"v1.3.0 requires esbuild version >=0.19.0. Older esbuild versions (e.g., 0.18.x) will not work.","severity":"deprecated","affected_versions":">=1.3.0 <2.0.0"},{"fix":"Use YAMLPlugin() (with parentheses) in the plugins array.","message":"The YAMLPlugin must be instantiated as a function call YAMLPlugin() - passing it directly as an object will not work.","severity":"gotcha","affected_versions":">0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'npm install --save-dev esbuild-yaml esbuild' to install as dev dependency.","cause":"The package is not installed or is a dev dependency not available at runtime.","error":"Error: Cannot find module 'esbuild-yaml'"},{"fix":"Use YAMLPlugin() in the plugins array.","cause":"Trying to use YAMLPlugin without calling it as a function (e.g., plugins: [YAMLPlugin] instead of plugins: [YAMLPlugin()])","error":"TypeError: YAMLPlugin is not a constructor"},{"fix":"Ensure the YAMLPlugin is added to the plugins array in esbuild's build options.","cause":"YAMLPlugin is not loaded or not properly configured in the esbuild build.","error":"Module not found: Error: Can't resolve './file.yaml'"},{"fix":"Install yaml: npm install yaml (or ensure it is included via esbuild-yaml's dependencies).","cause":"The 'yaml' peer dependency is missing.","error":"node:internal/modules/cjs/loader:1078 - throw err; Error: Cannot find module 'yaml'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}