feat: add legacy.collectionsBackwardsCompat flag for v6 content colle… #14927

matthewp · 2025-11-28T21:11:53Z

Changes

Add legacy.collectionsBackwardsCompat?: boolean (defaults to false)
- When false (default): strict v6 behavior (no old-style collections)
- When true: allows old-style collections to be defined and processed
Allows collections without loaders.
Collections without loaders get type: 'content' by default (was throwing error)
Gets glob loader if using type: 'content' or type: 'data'

Testing

Tests added for the new flag.

Docs

TODO - what should be document outside of the flag?

…ctions migration PROBLEM ------- In v5, content collections could be defined without a loader and would work via automatic backwards compatibility mode (supporting v4-style collections). This allowed old code to continue working without explicit migration. In v6 (current next branch), we completely removed this backwards compat layer. Collections without loaders now throw an error in defineCollection(), and old-style collections (type: 'content' or type: 'data') are silently skipped during sync. This creates a harsh upgrade path: users upgrading to v6 get hard errors if they have legacy collections. They don't realize they're using deprecated patterns because their code 'just worked' in v5. SOLUTION -------- Add a legacy.collectionsBackwardsCompat flag that provides an escape hatch for v6. This allows projects to opt-in to backwards compatibility while they migrate, and signals explicitly that they're using deprecated patterns. IMPLEMENTATION DETAILS ---------------------- 1. Config Schema Changes File: packages/astro/src/types/public/config.ts File: packages/astro/src/core/config/schemas/base.ts - Add legacy.collectionsBackwardsCompat?: boolean (defaults to false) - When false (default): strict v6 behavior (no old-style collections) - When true: allows old-style collections to be defined and processed 2. defineCollection() Logic Restoration File: packages/astro/src/content/config.ts - Restore v5 logic that allows collections without loaders - Collections without loaders get type: 'content' by default (was throwing error) - Only validate loader presence IF a loader is defined in config - Changed from: 'must have loader' → to 'if loader exists, validate it' This means: - Old code like: defineCollection({ schema: z.object(...) }) now works instead of throwing ContentCollectionMissingLoader error - Collections get default type: 'content' if not specified 3. Content Layer Processing File: packages/astro/src/content/content-layer.ts - Check this.#settings.config.legacy?.collectionsBackwardsCompat before syncing - If flag is FALSE (default): * Skip collections with type: 'content' or type: 'data' * Skip collections without loaders * Only process loader-based collections (v6 strict mode) - If flag is TRUE (backwards compat enabled): * Process both loader-based AND old-style collections * Old-style collections still need their files to exist in the right location * But they work without explicit loader definitions - Made all loader access safe with 'loader' in collection guards MIGRATION PATH --------------- For projects upgrading to v6 with legacy collections: 1. Add to astro.config.mjs: legacy: { collectionsBackwardsCompat: true } 2. Content will continue working (same as v5) 3. At leisure, migrate collections one-by-one: - Add glob() or file() loader - Change type: 'content' to type: 'content_layer' (or omit type) - Verify it works 4. Remove the legacy flag once all collections are migrated NOTES ----- - This is v6-specific. v5 users don't see this flag (it exists but defaults to false) - The flag name signals intent: 'backwards compat' is deprecated, not a permanent feature - In Astro 7, we can remove this flag entirely - This enables a smoother upgrade experience without encouraging long-term reliance on legacy patterns

changeset-bot · 2025-11-28T21:11:58Z

⚠️ No Changeset found

Latest commit: 27570e0

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

ascorbic · 2025-12-01T17:20:50Z

To be clear, this just add a flag for the checks, but it doesn't actually reimplement any backwards-compat that was removed in #14407

matthewp · 2025-12-03T21:11:29Z

@ascorbic Correct, what I read from the thread was that there was concern that people wouldn't know what they needed to upgrade, so I created #14928 to give them errors when they don't use loaders (in v5) and this was to allow them get the simpleLoader if they don't provide a loader themselves.

I didn't add back any more of the compat because it wasn't clear to me from the thread what backwards compat was desired.

ascorbic · 2025-12-08T10:21:44Z

I think the summary of backwards-compat behaviour that we should re-enable:

config file in src/content/config.ts.
collections with no loader, and/or with type: content or type: data. These would get the automatic glob loader in legacy mode, which generates entries that support the legacy API:
- entry.slug
- entry.render()

I'm not sure if we should also bring back getEntryById and getEntryBySlug

sarah11918 · 2025-12-08T12:14:15Z

I'm not sure if we should also bring back getEntryById and getEntryBySlug

These were already deprecated in Astro v4. I did a quick search on GitHub to see if I could find much use of them in Astro projects, and my advanced search probably wasn't working properly because it showed ZERO code matches, but scanning what was returned, there probably isn't much use in current projects.

So, probably safe to remove these, I think? We have also had GetEntryDeprecationError since v4, so this all seems safe. They would have been seeing errors about this for a while already.

Otherwise, Matt's suggestions LGTM!

sarah11918 · 2025-12-08T13:10:22Z

Will there be any complication with the move to Zod 4 here? Will backwards compatibility exist, but yet people will still have to upgrade their schemas to satisfy Zod 4? Or will the backwards compatibility include staying on Zod 3?

ascorbic · 2025-12-08T14:33:45Z

I don't think it would make any difference. It wouldn't touch the schema stuff – it's mostly related to loaders

sarah11918 · 2025-12-08T15:25:29Z

So then, if someone enables "backwards compatibility" they only get "backwards LOADER compatibility" but would still have to go through the Zod 4 update? That's more what I'm wondering. "Backwards compat" doesn't mean except from other Astro 6 upgrades?

ascorbic · 2025-12-08T16:12:35Z

Will there be no backwards-compat for Zod then?

sarah11918 · 2025-12-08T16:25:07Z

I don't know, but we don't mention any way to enable it in the upgrade guide entry Matthew submitted to docs, so I'm guessing no?

matthewp · 2025-12-08T16:45:37Z

No, we can't support both Zod 3 and Zod 4, it was attempted but decided to just do Zod 4.

github-actions · 2025-12-08T20:22:49Z

⚠️ Package Trust Level Decreased

Caution

Decreased trust levels may indicate a higher risk of supply chain attacks. Please review these changes carefully.

📦 Package	🔒 Before	🔓 After
@cloudflare/unenv-preset	trusted-with-provenance	none
workerd	trusted-with-provenance	none
ts-api-utils	provenance	none
undici	provenance	none
miniflare	trusted-with-provenance	none
youch	provenance	none
@cloudflare/workerd-darwin-64	trusted-with-provenance	none
@cloudflare/workerd-darwin-arm64	trusted-with-provenance	none
@cloudflare/workerd-linux-64	trusted-with-provenance	none
@cloudflare/workerd-linux-arm64	trusted-with-provenance	none
@cloudflare/workerd-windows-64	trusted-with-provenance	none
wrangler	trusted-with-provenance	none

matthewp · 2025-12-08T20:29:09Z

I've updated the PR to do these things:

Allow src/content/config.ts
Collections with no loader get the glob loader if using type: 'content' or type: 'data'.

That's all.

packages/astro/src/content/config.ts

ascorbic · 2025-12-10T09:47:31Z

Collections with no loader get the glob loader if using type: 'content' or type: 'data'.

It should also be if there is no type set, as it should default to content in that case. It looks like that is what's currently implemented, but I just wanted to flag it.

List v5 behaviors restored by flag

…m:withastro/astro into feat/restore-collections-backwards-compat

packages/astro/src/types/public/config.ts

ematipico

I am not very familiar with this part of the code, so take my review with a huge grain of salt

Co-authored-by: Matt Kane <[email protected]>

sarah11918

Just left a couple of comments with thoughts on the wording of some messages!

packages/astro/src/content/config.ts

Co-authored-by: Sarah Rainsberger <[email protected]>

github-actions bot added pkg: astro Related to the core `astro` package (scope) docs pr labels Nov 28, 2025

add support for automatic glob loader usage

04f4327

matthewp added 8 commits December 8, 2025 15:49

Merge branch 'next' into feat/restore-collections-backwards-compat

810d249

fix build

4fc983b

use a symbol instead

0abf4eb

small lint thing

5aacb3d

fix

8c56033

fix everything

5e3d547

remove unnecessary exports

eb14aa9

Merge branch 'next' into feat/restore-collections-backwards-compat

6f236fd

florian-lefebvre reviewed Dec 10, 2025

View reviewed changes

packages/astro/src/content/config.ts Show resolved Hide resolved

matthewp added 3 commits December 11, 2025 16:53

bring back loader constraint

6a618cb

Merge branch 'next' into feat/restore-collections-backwards-compat

fcc9eab

fix build

0b25a09

matthewp added 3 commits December 15, 2025 10:30

Merge branch 'next' into feat/restore-collections-backwards-compat

a3209f1

docs: improve collectionsBackwardsCompat documentation

8d260f3

List v5 behaviors restored by flag

Merge branch 'feat/restore-collections-backwards-compat' of github.co…

18886ea

…m:withastro/astro into feat/restore-collections-backwards-compat

matthewp marked this pull request as ready for review December 15, 2025 20:04

ascorbic reviewed Dec 15, 2025

View reviewed changes

packages/astro/src/types/public/config.ts Outdated Show resolved Hide resolved

ematipico approved these changes Dec 16, 2025

View reviewed changes

Update packages/astro/src/types/public/config.ts

7496be4

Co-authored-by: Matt Kane <[email protected]>

sarah11918 reviewed Dec 16, 2025

View reviewed changes

packages/astro/src/content/config.ts Outdated Show resolved Hide resolved

packages/astro/src/content/config.ts Outdated Show resolved Hide resolved

matthewp and others added 3 commits December 17, 2025 09:56

Update packages/astro/src/content/config.ts

7132f9f

Co-authored-by: Sarah Rainsberger <[email protected]>

Update packages/astro/src/content/config.ts

4158048

Co-authored-by: Sarah Rainsberger <[email protected]>

Merge branch 'next' into feat/restore-collections-backwards-compat

27570e0

matthewp merged commit a33e1c6 into next Jan 5, 2026
23 checks passed

matthewp deleted the feat/restore-collections-backwards-compat branch January 5, 2026 14:24

HiDeoo mentioned this pull request Jan 9, 2026

add legacy.collectionsBackwardsCompat flag docs for v6 withastro/docs#13022

Merged

Uh oh!

feat: add legacy.collectionsBackwardsCompat flag for v6 content colle… #14927

feat: add legacy.collectionsBackwardsCompat flag for v6 content colle… #14927

Uh oh!

Conversation

matthewp commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Testing

Docs

Uh oh!

changeset-bot bot commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

ascorbic commented Dec 1, 2025

Uh oh!

matthewp commented Dec 3, 2025

Uh oh!

ascorbic commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sarah11918 commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sarah11918 commented Dec 8, 2025

Uh oh!

ascorbic commented Dec 8, 2025

Uh oh!

sarah11918 commented Dec 8, 2025

Uh oh!

ascorbic commented Dec 8, 2025

Uh oh!

sarah11918 commented Dec 8, 2025

Uh oh!

matthewp commented Dec 8, 2025

Uh oh!

github-actions bot commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Package Trust Level Decreased

Uh oh!

matthewp commented Dec 8, 2025

Uh oh!

Uh oh!

ascorbic commented Dec 10, 2025

Uh oh!

Uh oh!

ematipico left a comment

Choose a reason for hiding this comment

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

matthewp commented Nov 28, 2025 •

edited

Loading

changeset-bot bot commented Nov 28, 2025 •

edited

Loading

ascorbic commented Dec 8, 2025 •

edited

Loading

sarah11918 commented Dec 8, 2025 •

edited

Loading

github-actions bot commented Dec 8, 2025 •

edited

Loading