Collections API seems to be broken in Eleventy 3.1.0 or later

[sentience]

Operating system

macOS Tahoe 26.1

Eleventy

3.1.2

Describe the bug

Custom collections defined in the Eleventy config file will often pull documents from a built-in (tag-based) collection, such as filtering and/or sorting the templates with a specific tag. For example, I use the Collections API in my Eleventy config to create a "primaryNav" collection that contains a sorted list of all pages of my site with the "primary" tag set:

  // Sort primary nav bar items
  eleventyConfig.addCollection("primaryNav", (collectionsApi) =>
    collectionsApi
      .getFilteredByTag("primary")
      .sort((pageA, pageB) => pageA.data.order - pageB.data.order);
  );

This works fine up to Eleventy 3.0.0, but in 3.1.x collectionsApi.getFilteredByTag("primary") always returns an empty array.

The issue appears to be that Eleventy 3.1.0's newly-optimized build process is building the "primaryNav" (custom) collection before it builds the "primary" (tag-based) collection, because it knows all my site's pages depend on "primaryNav" (as declared in their layout's frontmatter with eleventyImport.collections) to render their primary nav bar.

In short, this is a circular dependency: my page templates depend on my layout, my layout depends on a custom collection, that custom collection depends on a tag collection, and that tag collection depends on my page templates.

A fix for this, I guess, would require Eleventy to build all of its tag collections before building the custom collections defined in the config file, before finally rendering the pages. I have taken a stab at this in #4264.

Reproduction Source Code URL

https://github.com/sentience/eleventy-collections-api-issue

Contains this version of the code with debug output (see below):

  // Sort nav bar collections
  console.log("Adding collection 'primaryNav' for tag 'primary'");
  eleventyConfig.addCollection("primaryNav", (collectionsApi) => {
    console.log(
      "DEBUG collectionsApi.getAll().length: ",
      collectionsApi.getAll().length,
    );
    return collectionsApi
      .getFilteredByTag("primary")
      .sort((pageA, pageB) => pageA.data.order - pageB.data.order);
  });

Screenshots

Build output with Eleventy 3.0.0:

Adding collection 'primaryNav' for tag 'primary'
DEBUG collectionsApi.getAll().length:  0
DEBUG collectionsApi.getAll().length:  2
[11ty] Writing ./_site/index.html from ./index.liquid
[11ty] Writing ./_site/about/index.html from ./about.liquid
[11ty] Copied 11 Wrote 2 files in 0.10 seconds (v3.0.0)

Build output with Eleventy 3.1.2:

Adding collection 'primaryNav' for tag 'primary'
DEBUG collectionsApi.getAll().length:  0
[11ty] Writing ./_site/about/index.html from ./about.liquid
[11ty] Writing ./_site/index.html from ./index.liquid
[11ty] Copied 11 Wrote 2 files in 0.11 seconds (v3.1.2)

[sentience]

For those watching this issue, I've found the root cause and have opened a PR with a fix.