How to Build a Custom YAML Loader for Webpack: From Basics to AST Parsing

1. What Is a Loader

Loaders and plugins are the two core components of Webpack. Loaders transform source files so they can be imported as modules, allowing formats like YAML to be converted into JavaScript that Webpack can understand.

2. Writing a yaml-loader

YAML Syntax

YAML is a human‑readable configuration language similar to JSON but supports comments and indentation for hierarchy.

# object
version: 1.2.4
# array
author:
  - Mike
  - Hankle
# constant
name: "my project" # define a string
limit: 30 # define a number
es6: true # define a boolean
openkey: null # define a null
server:
  base: &base
  port: 8005
  dev:
    ip: 120.168.117.21
    <<: *base
  gamma:
    ip: 120.168.117.22
    <<: *base

The equivalent JSON representation is:

{
  "version": "1.2.4",
  "author": ["Mike", "Hankle"],
  "name": "my project",
  "limit": 30,
  "es6": true,
  "openkey": null,
  "server": {
    "base": {
      "port": 8005
    },
    "dev": {
      "ip": "120.168.117.21"
    },
    "gamma": {
      "ip": "120.168.117.22",
      "port": 8005
    }
  }
}

To use YAML data in a Webpack‑built application you need a yaml‑loader. If an existing loader is unavailable or you need custom behavior, you can write your own.

Loader Principle

A loader is a Node module that exports a function. The function receives the source as a String or Buffer and must return the transformed source.

// loaders/yaml-loader.js
module.exports = function(source) {
  return source;
};

Loaders are applied in a pipeline from right to left (or bottom to top). You can chain multiple loaders for the same file type.

Webpack Configuration Example

const path = require("path");
module.exports = {
  module: {
    rules: [
      {
        test: /\.yml$/,
        use: [
          { loader: "json-loader" },
          { loader: path.resolve(__dirname, "./loaders/yaml-loader.js") }
        ]
      }
    ]
  }
};

3. Simple yaml-loader Implementation

The loader only needs to turn YAML into a JSON string.

var yaml = require("js-yaml");
module.exports = function(source) {
  this.cacheable && this.cacheable();
  try {
    var res = yaml.safeLoad(source);
    return JSON.stringify(res, undefined, "\t");
  } catch (err) {
    this.emitError(err);
    return null;
  }
};

If the js-yaml module is unavailable, you can use an AST parser for a more robust solution.

4. Using an AST for Source Transformation

The yaml-ast-parser module parses YAML into an AST, making traversal and conversion easier than raw string manipulation.

const yaml = require("yaml-ast-parser");
class YamlParser {
  constructor(source) {
    this.data = yaml.load(source);
    this.parse();
  }
  parse() {
    // traverse AST and build JavaScript object
  }
}
module.exports = function(source) {
  this.cacheable && this.cacheable();
  try {
    const parser = new YamlParser(source);
    return JSON.stringify(parser.data, undefined, "\t");
  } catch (err) {
    this.emitError(err);
    return null;
  }
};

The traversal handles objects (MAP), scalars (SCALAR), arrays (SEQ), and anchor references (ANCHOR_REF) with appropriate switch cases, throwing errors for unsupported nodes.

5. Loader Development Tips

1. Single Responsibility

Design each loader to perform one well‑defined task, enabling composition via the pipeline.

2. Statelessness

A loader should not retain state between runs; this keeps data flow clear and improves testability. Loaders can still perform asynchronous I/O if needed.

3. Leverage Caching

Webpack enables loader caching by default. Disable caching only when the loader depends on unstable external resources.

this.cacheable && this.cacheable(false);