Skip to content

uncenter/eleventy-plugin-validate

Repository files navigation

eleventy-plugin-validate

Installation

npm i eleventy-plugin-validate
pnpm add eleventy-plugin-validate
yarn add eleventy-plugin-validate
bun add eleventy-plugin-validate

Usage

Setup the plugin in your Eleventy configuration file.

CJS

const pluginValidate = require('eleventy-plugin-validate');
const { z } = require('zod');

module.exports = (eleventyConfig) => {
  eleventyConfig.addPlugin(pluginValidate, {
    // Select the Zod library for schemas:
    validator: 'zod',
    schemas: [
      {
        // `collections: ['posts']` tells the plugin
        // to run this schema on the 'posts' collection.
        // If you omit this property, the schema will run against
        // collection items from the 'all' collection (a default
        // collection that Eleventy generates for you).
        collections: ['posts'],

        // `schema` should be a schema made with the validator
        // library selected in the above 'validator' property.
        schema: z
          .object({
            title: z.string(),
            description: z.string(),
            draft: z.boolean(),
          })
          // I suggest adding .strict() to your schema
          // for even more accurate validation.
          // With .strict(), extra properties
          // you have not specified in the schema object
          // will cause an error. For example, if you have an
          // optional property "edited", but you misspell it as
          // "edtied", .strict() will warn you!
          .strict(),
      },
    ],
  });
};

ESM (@11ty/eleventy@v3 or later)

import pluginValidate from 'eleventy-plugin-validate';
import { z } from 'zod';

export default (eleventyConfig) => {
  eleventyConfig.addPlugin(pluginValidate, {
    // Select the Zod library for schemas:
    validator: 'zod',
    schemas: [
      {
        // `collections: ['posts']` tells the plugin
        // to run this schema on the 'posts' collection.
        // If you omit this property, the schema will run against
        // collection items from the 'all' collection (a default
        // collection that Eleventy generates for you).
        collections: ['posts'],

        // `schema` should be a schema made with the validator
        // library selected in the above 'validator' property.
        schema: z
          .object({
            title: z.string(),
            description: z.string(),
            draft: z.boolean(),
          })
          // I suggest adding .strict() to your schema
          // for even more accurate validation.
          // With .strict(), extra properties
          // you have not specified in the schema object
          // will cause an error. For example, if you have an
          // optional property "edited", but you misspell it as
          // "edtied", .strict() will warn you!
          .strict(),
      },
    ],
  });
};

Run Eleventy, and voila! The plugin will warn you about collection items that do not pass schema validation.

For example:

> eleventy --serve

[eleventy-plugin-validate][./posts/hello-world.md] title: expected a string but received boolean
[eleventy-plugin-validate][./posts/hello-world.md] description: expected a string but received number
[eleventy-plugin-validate][./posts/hello-world.md] draft: expected a boolean but received string
[11ty] Problem writing Eleventy templates: (more in DEBUG output)
[11ty] Invalid frontmatter data provided (via Error)
...

Caveats

This plugin uses the addCollection callback to access the entire data cascade of your site, which unfortunately means it adds an extra collection with no items in it. If you have tag pages (or anything similar), you'll need to use pagination filtering to hide the eleventy-plugin-validate collection. I'm open to suggestions if you have another way of doing this!

License

MIT