Linting Eleventy data

[aarongoldenthal]

I'm looking at options for how to lint data on an Eleventy page to ensure that anything required by the template is present and valid. Some data is in front matter, some in directory data files, and some in global data files, so I really need the data after the data cascade to be complete. I have a solution, shown below, but I'm wondering if there's a better way (ideally a way that could be a plugin that's passed the data configuration to validate).

Options that didn't work:

• Events: eleventy.before fires once per build, not per page, and I didn't see another event per page
• Transforms/Linters: fire for each page, but after the page is rendered, and don't appear to have access to data

The one solution that is working is using computed data.

File: _data/eleventyComputed.js

module.exports = {
    invalid: (data) => {
        // Check `data` for validity, which has data after the cascade...
        // Log errors to an `errors` array...
        console.error(`[11ty] Invalid data for ${page.inputPath}: ${errors.join(', ')}`);
        return errors.length > 0;
    }
};

Then during a build this outputs errors like:

[11ty] Invalid data for ./src/posts/post1.md: `description` is required, at least one `tag` is required for posts
[11ty] Invalid data for ./src/posts/post1.md: `description` is required, at least one `tag` is required for posts
[11ty] Invalid data for ./src/posts/post3.md: `date` is required
[11ty] Invalid data for ./src/posts/post3.md: `date` is required

One by-product of this approach is the invalid property is added to data can be used to conditionally render the page (for example put an invalid banner on applicable pages). That wasn't in my initial requirements, and in reality I'd probably want to warn on development builds and fail on production builds.

All of this raises two questions:

1. Is there a better way, and something that could be configured as a plugin, or define the computed data in config?
2. In the list above you can see that the computed data function is called twice for every page. The first time data is a Proxy with the data, and the second time data is the final data object (at least that's how it appear in the VSCode debugger). Both seem to process the data properly, and I could filter out the Proxy calls, but curious if there's a subtle difference I'm missing.

[uncenter]

I've actually given this a go over at https://github.com/uncenter/eleventy-frontmatter-with-zod using Zod for validation. It is possible with current Eleventy I think but that version showcases a potential change to Eleventy that allows for access to data from front matter specifically (which opens it up to stricter comparisons, not allowing extra keys...).

[uncenter]

@aarongoldenthal I've implemented that using the collections method and published, if you want to give it a try. Still experimental but working so far in my testing.

[uncenter]

Okay so that all works but we can't access collections added from eleventyConfig.addCollection since getFilteredByTag(s) is only tags. Any ideas there?

[aarongoldenthal]

I did not think of that. Maybe try getAll() to see. I'm wondering if they run in order they're added.

[uncenter]

I tried eleventyConfig.getCollections(), which works but returns the functions themselves and not the results which doesn't help.

[uncenter]

Alright you were exactly right with getAll(). Each entry has data about what collections it is a part of, including collections defined in the config! Got it all working now.

[pdehaan]

+1 to the .addCollection() route. Seemed to work well for me in the past.

https://github.com/pdehaan/11ty-schema-ajv

I should really add a README.md to that repo, but basically you can define collection specific schemas in ./schemas/blog.js (or whatever), like this:

// ./schemas/blog.js
module.exports = {
  "$id": "blogs",
  "type": "object",
  "properties": {
    "title": { type: "string" },
    "orderId": { type: "number" },
  },
  "required": ["title", "orderId"],
};

Then I have ./schemas/index.js which creates my Ajv instance and exports a validator which throws an Error if the required fields aren't found in data cascade:

// ./schemas/index.js
const Ajv = require("ajv");

const ajv = new Ajv({ allErrors: true });
ajv.addSchema(require("./blogs"));

function validateSchema(data, id, dataVar) {
  const validate = ajv.getSchema(id);
  if (!validate(data)) {
    throw new Error(ajv.errorsText(validate.errors, { dataVar }));
  }
}

module.exports = {
  validate: validateSchema,
};

Finally, my eleventy.config.js imports the validate() function, and I added a helper function which is poorly named addCollectionValidate() which takes a name of a collection, which is also the name of the schema to validate each page against. If the validation fails, it writes the Ajv errors to STDERR and sets a non-zero exit code.

const { validate } = require("./schemas/index");

/**
 * @param {import("@11ty/eleventy/src/UserConfig")} eleventyConfig
 * @returns {ReturnType<import("@11ty/eleventy/src/defaultConfig")>}
 */
module.exports = function (eleventyConfig) {
  addCollectionValidate("blogs");

  function addCollectionValidate(name) {
    eleventyConfig.addCollection(name, function (collectionApi) {
      const pages = [...collectionApi.getFilteredByTag(name)];
      for (const p of pages) {
        try {
          validate(p.data, name, p.inputPath);
        } catch (err) {
          console.error(err.message);
          process.exitCode = 1;
        }
      }
      return pages;
    });
  }

  return {
    dir: {
      input: "src",
      output: "www",
    }
  };
};

And my console output looks like this:

npm run build

> [email protected] build
> eleventy

./src/blogs/four.njk must have required property 'orderId'
./src/blogs/one.njk must have required property 'title', ./src/blogs/one.njk must have required property 'orderId'
./src/blogs/three.njk must have required property 'orderId'
./src/blogs/two.njk must have required property 'orderId'
./src/blogs/four.njk must have required property 'orderId'
./src/blogs/one.njk must have required property 'title', ./src/blogs/one.njk must have required property 'orderId'
./src/blogs/three.njk must have required property 'orderId'
./src/blogs/two.njk must have required property 'orderId'
[11ty] Writing www/index.html from ./src/index.njk
[11ty] Writing www/blogs/two/index.html from ./src/blogs/two.njk
[11ty] Writing www/blogs/four/index.html from ./src/blogs/four.njk
[11ty] Writing www/blogs/five/index.html from ./src/blogs/five.njk
[11ty] Writing www/blogs/three/index.html from ./src/blogs/three.njk
[11ty] Writing www/blogs/one/index.html from ./src/blogs/one.njk
[11ty] Wrote 6 files in 0.04 seconds (v2.0.1)

I image we could/should probably fail louder on schema validation errors versus just logging a message and still building.
But should be simple enough to add more schemas for different parts of the site and then just call addCollectionValidate("gallery") and addCollectionValidate("employees"), etc.

Another option would be specifying a template's or collection's schema name in front-matter or directory data files, then just using .getAll() and looping over each page and validating the data in the data cascade against each file's schema (if one exists).

[uncenter]

Yeah I've made it into a plugin, I'll try to add support for other validator libraries!

[aarongoldenthal]

One note with the collection approach is that adding the collection adds that tag in collections.all, so anywhere tags are filtered out the new collection also needs to be filtered out. For example, using a site loosely derived from eleventy-base-blog and eleventy-plugin-validate, I found a eleventy-plugin-validate page (for the __eleventy-plugin-validate collection) in the pages for each tag (and consequently the sitemap).

[11ty] Writing public/tags/eleventy-plugin-validate/index.html from ./src/tags.njk

[uncenter]

Hmm....

[aarongoldenthal]

Specifically, it was here and here that it needed to be filtered out.

[uncenter]

Yeah that makes sense, I'm just trying to brainstorm a way to remove the collection right after we "add" it.