yaml-loader

0.9.0 verified Sat Apr 25 auth: no javascript

A Webpack loader that converts YAML files into JavaScript objects or JSON strings, using the `yaml` library for parsing. The current stable version is 0.9.0, released with support for Webpack 5+ and Node.js 20+. It offers options like `asJSON` for JSON output, `asStream` for parsing multi-document YAML streams, and `namespace` for extracting specific sub-trees. Unlike alternatives like js-yaml-loader, this loader leverages the more modern `yaml` package and is actively maintained. Release cadence is irregular, with major version bumps for breaking changes.

Common errors

error Module parse failed: Unexpected token (1:2) ↓

cause Webpack is trying to parse a YAML file without the yaml-loader configured.

fix

Add module rule in webpack.config.js: { test: /\.ya?ml$/, use: 'yaml-loader' }

error Error: Cannot find module 'yaml' ↓

cause The 'yaml' package is not installed.

fix

Run: npm install --save-dev yaml

error Critical dependency: the request of a dependency is an expression ↓

cause Using inline loader syntax like `require('yaml-loader!./file.yaml')` with dynamic path.

fix

Configure the loader in webpack.config.js and use static imports instead.

error yaml-loader: options are not allowed for this loader (use 'use' instead of 'loader' with options) ↓

cause Passing options with `loader` key directly instead of inside `use`.

fix

Use: { use: { loader: 'yaml-loader', options: { asJSON: true } } }

Warnings

breaking Drop support for Webpack v4 (#61) and unsupported Node.js versions ↓

fix Upgrade to Webpack 5 and Node.js 20 or later.

breaking Output JavaScript source by default, rather than JSON (#27) ↓

fix Set `{ asJSON: true }` option if you need JSON output.

breaking Replace `js-yaml` dependency with `yaml` ↓

fix Some YAML files parsed as valid by js-yaml may now be invalid; review your YAML files and update if needed.

breaking Drop output JSON prettification ↓

fix Output is no longer multiline or tab-indented; if you need prettified JSON, chain another loader or use `asJSON` option and format yourself.

deprecated Node.js versions below 12.13 are no longer supported ↓

fix Upgrade Node.js to at least 12.13.

gotcha Options set in webpack.config.js via `options` object are superseded by query parameters (`?namespace=...`) ↓

fix Use either `options` in config or query parameters, not both, to avoid confusion.

gotcha The `asStream` option always outputs an array and ignores `namespace` ↓

fix Do not combine `asStream` with `namespace`; they are mutually exclusive.

Install

npm install yaml-loader

yarn add yaml-loader

pnpm add yaml-loader

Imports

default loader

wrong

module.exports = { module: { rules: [ { test: /\.ya?ml$/, loader: 'yaml-loader' } ] } }

correct

module.exports = { module: { rules: [ { test: /\.ya?ml$/, use: 'yaml-loader' } ] } }

When using options, the configuration must use `use` or `loader` with `options` object.

JavaScript import from YAML
wrong
```
const config = require('./config.yaml');
```
correct
```
import config from './config.yaml';
```
ESM import works with Webpack's module bundling; require() may not work in all setups.

TypeScript import (type)

wrong

import yaml from 'yaml'; // yaml is not directly imported by the loader user

correct

import type { YAMLType } from 'yaml'; // not needed for loader

The loader itself does not re-export yaml types; use the 'yaml' package directly if type access is needed.

Options with query parameter
```
import data from './data.yaml?namespace=config';
```
Query parameters override options set in webpack.config.js.
CommonJS require
wrong
```
const data = require('yaml-loader!./data.yaml');
```
correct
```
const data = require('./data.yaml');
```
Inline loader syntax is discouraged; use Webpack configuration instead.

Quickstart

Configures Webpack to import YAML files as JavaScript objects using yaml-loader.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.ya?ml$/,
        use: 'yaml-loader',
      },
    ],
  },
};

// app.js
import config from './config.yaml';
console.log(config);

// config.yaml
server:
  port: 8080
  host: localhost