From 3d722b842ec13e9f0e8be4750198b4944f68af74 Mon Sep 17 00:00:00 2001 From: sarahrainsberger Date: Mon, 22 Sep 2025 12:00:52 +0000 Subject: [PATCH 01/12] removed content collections --- src/content/docs/en/guides/upgrade-to/v6.mdx | 104 +++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 41552d4979312..a58758a55cba5 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -75,6 +75,110 @@ The following features have now been entirely removed from the code base and can Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features. + +### Removed: legacy content collections + +In Astro 5.x, it was still possible to use [the Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), either through a `legacy` configuration flag or via built-in backwards compatibility. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your content collections to the new Content Layer API. + +Astro v6.0 removes the Content Collections API entirely. All content collections must now use the Content Layer API introduced in Astro v5.0. No backwards compatibility support is available. + +#### What should I do? + +Ensure that your content collections are **fully updated** for the Content Layer API. Astro v5.x included some backwards compatibility that may have allowed your existing collections to continue to work even if only some features of the Content Layer API were upgraded. + +You will need to upgrade your collections to be fully compatible with the Content Layer API if you currently have any of the following legacy features: + +- no content collections configuration file +- a configuration file located at `src/content/config.ts` +- a legacy collection definition that does not define a `loader` +- a legacy collection definition that includes a collection type ((`type: 'content'` or `type: 'data'`)) +- legacy collection querying methods `getDataEntryById()` and `getEntryBySlug()` +- legacy collection querying and rendering methods that depend on a special, reserved `slug` property +- legacy collection rendering methods that do not import and use the Content Layer API `render()` function + +See the detailed instructions below for updating any legacy content collection to use the Content Layer API. + +BELOW IS STILL THE V5 stuff, NOT UPDATED YET + +
+Step-by-step instructions to update a collection from the Content Collecctions API to the new Content Layer API + + + +1. **Move the content config file**. This file no longer lives within the `src/content/` folder. This file should now exist at `src/content.config.ts`. + +2. **Edit the collection definition**. Your updated collection requires a `loader` which indicates both a folder for the location of your collection (`base`) and a `pattern` defining the collection entry filenames and extensions to match. (You may need to update the example below accordingly. You can use [globster.xyz](https://globster.xyz/) to check your glob pattern.) The option to select a collection `type` is no longer available. + + ```ts ins={3,8} del={7} + // src/content.config.ts + import { defineCollection, z } from 'astro:content'; + import { glob } from 'astro/loaders'; + + const blog = defineCollection({ + // For content layer you no longer define a `type` + type: 'content', + loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }), + schema: z.object({ + title: z.string(), + description: z.string(), + pubDate: z.coerce.date(), + updatedDate: z.coerce.date().optional(), + }), + }); + ``` + +3. **Change references from `slug` to `id`**. Content layer collections do not have a reserved `slug` field. Instead, all updated collections will have an `id`: + + ```astro ins={7} del={6} + // src/pages/[slug].astro + --- + export async function getStaticPaths() { + const posts = await getCollection('blog'); + return posts.map((post) => ({ + params: { slug: post.slug }, + params: { slug: post.id }, + props: post, + })); + } + --- + ``` + You can also update the dynamic routing file names to match the value of the changed `getStaticPaths()` parameter. + +4. **Switch to the new `render()` function**. Entries no longer have a `render()` method, as they are now serializable plain objects. Instead, import the `render()` function from `astro:content`. + + ```astro title="src/pages/index.astro" ins=", render" del={6} ins={7} + --- + import { getEntry, render } from 'astro:content'; + + const post = await getEntry('blog', params.slug); + + const { Content, headings } = await post.render(); + const { Content, headings } = await render(post); + --- + + ``` + + +
+ +##### Breaking changes to legacy `content` and `data` collections + + + +By default, collections that use the old `type` property (`content` or `data`) and do not define a `loader` are now implemented under the hood using the Content Layer API's built-in `glob()` loader, with extra backward-compatibility handling. + +Additionally, temporary backwards compatibility exists for keeping the content config file in its original location of `src/content/config.ts`. + +This backwards compatibility implementation is able to emulate most of the features of legacy collections and will allow many legacy collections to continue to work even without updating your code. However, **there are some differences and limitations that may cause breaking changes to existing collections**: + + - In previous versions of Astro, collections would be generated for all folders in `src/content/`, even if they were not defined in `src/content/config.ts`. This behavior is now deprecated, and collections should always be defined in `src/content.config.ts`. For existing collections, these can just be empty declarations (e.g. `const blog = defineCollection({})`) and Astro will implicitly define your legacy collection for you in a way that is compatible with the new loading behavior. + - The special `layout` field is not supported in Markdown collection entries. This property is intended only for standalone page files located in `src/pages/` and not likely to be in your collection entries. However, if you were using this property, you must now create dynamic routes that include your page styling. + - Sort order of generated collections is non-deterministic and platform-dependent. This means that if you are calling `getCollection()`, the order in which entries are returned may be different than before. If you need a specific order, you must sort the collection entries yourself. + - `image().refine()` is not supported. If you need to validate the properties of an image you will need to do this at runtime in your page or component. + - The `key` argument of `getEntry(collection, key)` is typed as `string`, rather than having types for every entry. + - Previously when calling `getEntry(collection, key)` with a static string as the key, the return type was not nullable. The type now includes `undefined` so you must check if the entry is defined before using the result or you will have type errors. + + ### Removed: `` component From ea94f560ccbfd87cc466d9239fed54c9c46b39fd Mon Sep 17 00:00:00 2001 From: sarahrainsberger Date: Mon, 22 Sep 2025 12:25:57 +0000 Subject: [PATCH 02/12] links back to v5 content --- src/content/docs/en/guides/upgrade-to/v6.mdx | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index a58758a55cba5..ffb2eb2372008 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -91,7 +91,7 @@ You will need to upgrade your collections to be fully compatible with the Conten - no content collections configuration file - a configuration file located at `src/content/config.ts` - a legacy collection definition that does not define a `loader` -- a legacy collection definition that includes a collection type ((`type: 'content'` or `type: 'data'`)) +- a legacy collection definition that includes a collection type (`type: 'content'` or `type: 'data'`) - legacy collection querying methods `getDataEntryById()` and `getEntryBySlug()` - legacy collection querying and rendering methods that depend on a special, reserved `slug` property - legacy collection rendering methods that do not import and use the Content Layer API `render()` function @@ -161,22 +161,7 @@ BELOW IS STILL THE V5 stuff, NOT UPDATED YET -##### Breaking changes to legacy `content` and `data` collections - - - -By default, collections that use the old `type` property (`content` or `data`) and do not define a `loader` are now implemented under the hood using the Content Layer API's built-in `glob()` loader, with extra backward-compatibility handling. - -Additionally, temporary backwards compatibility exists for keeping the content config file in its original location of `src/content/config.ts`. - -This backwards compatibility implementation is able to emulate most of the features of legacy collections and will allow many legacy collections to continue to work even without updating your code. However, **there are some differences and limitations that may cause breaking changes to existing collections**: - - - In previous versions of Astro, collections would be generated for all folders in `src/content/`, even if they were not defined in `src/content/config.ts`. This behavior is now deprecated, and collections should always be defined in `src/content.config.ts`. For existing collections, these can just be empty declarations (e.g. `const blog = defineCollection({})`) and Astro will implicitly define your legacy collection for you in a way that is compatible with the new loading behavior. - - The special `layout` field is not supported in Markdown collection entries. This property is intended only for standalone page files located in `src/pages/` and not likely to be in your collection entries. However, if you were using this property, you must now create dynamic routes that include your page styling. - - Sort order of generated collections is non-deterministic and platform-dependent. This means that if you are calling `getCollection()`, the order in which entries are returned may be different than before. If you need a specific order, you must sort the collection entries yourself. - - `image().refine()` is not supported. If you need to validate the properties of an image you will need to do this at runtime in your page or component. - - The `key` argument of `getEntry(collection, key)` is typed as `string`, rather than having types for every entry. - - Previously when calling `getEntry(collection, key)` with a static string as the key, the return type was not nullable. The type now includes `undefined` so you must check if the entry is defined before using the result or you will have type errors. + See [the Astro v5 upgrade guide](https://docs.astro.build/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about maintaining backwards compatibility of legacy collections in Astro v5. ### Removed: `` component From 2471a2bb88adba97d8bb68f43a2452f8e477a19a Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Mon, 22 Sep 2025 10:30:45 -0300 Subject: [PATCH 03/12] proper link syntax --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index ffb2eb2372008..106ba9b58c9c0 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -161,7 +161,7 @@ BELOW IS STILL THE V5 stuff, NOT UPDATED YET - See [the Astro v5 upgrade guide](https://docs.astro.build/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about maintaining backwards compatibility of legacy collections in Astro v5. + See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about maintaining backwards compatibility of legacy collections in Astro v5. ### Removed: `` component From fddbb86b4602956b8ddcdc1dad7f0094700f4089 Mon Sep 17 00:00:00 2001 From: sarahrainsberger Date: Wed, 24 Sep 2025 14:41:39 +0000 Subject: [PATCH 04/12] remove legacy flag documentation --- .../docs/en/reference/legacy-flags.mdx | 44 ++----------------- 1 file changed, 3 insertions(+), 41 deletions(-) diff --git a/src/content/docs/en/reference/legacy-flags.mdx b/src/content/docs/en/reference/legacy-flags.mdx index de5a97d93637f..fcb4df3fd2e89 100644 --- a/src/content/docs/en/reference/legacy-flags.mdx +++ b/src/content/docs/en/reference/legacy-flags.mdx @@ -3,49 +3,11 @@ title: Legacy flags i18nReady: true --- +import Since from '~/components/Since.astro' + To help some users migrate between versions of Astro, we occasionally introduce `legacy` flags. These flags allow you to opt in to some deprecated or otherwise outdated behavior of Astro in the latest version, so that you can continue to upgrade and take advantage of new Astro releases until you are able to fully update your project code. -import Since from '~/components/Since.astro' - -## Collections - -

- -**Type:** `boolean`
-**Default:** `false`
- -

- -Enable legacy behavior for content collections (as used in Astro v2 through v4) - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -export default defineConfig({ - legacy: { - collections: true - } -}); -``` - -If enabled, `data` and `content` collections (only) are handled using the legacy content collections implementation. Collections with a `loader` (only) will continue to use the Content Layer API instead. Both kinds of collections may exist in the same project, each using their respective implementations. - - The following limitations continue to exist: - -- Any legacy (`type: 'content'` or `type: 'data'`) collections must continue to be located in the `src/content/` directory. -- These legacy collections will not be transformed to implicitly use the `glob()` loader, and will instead be handled by legacy code. -- Collections using the Content Layer API (with a `loader` defined) are forbidden in `src/content/`, but may exist anywhere else in your project. - -When you are ready to remove this flag and migrate to the new Content Layer API for your legacy collections, you must define a collection for any directories in `src/content/` that you want to continue to use as a collection. It is sufficient to declare an empty collection, and Astro will implicitly generate an appropriate definition for your legacy collections: - -```js -// src/content/config.ts -import { defineCollection, z } from 'astro:content'; - -const blog = defineCollection({ }) - -export const collections = { blog }; -``` +Any currently available legacy flags, including instructions for removing them and upgrading to the latest features of Astro, are listed below. \ No newline at end of file From fb4c1219c982bf337aaa99f0193d3b1c12419fb1 Mon Sep 17 00:00:00 2001 From: sarahrainsberger Date: Wed, 24 Sep 2025 17:04:34 +0000 Subject: [PATCH 05/12] =?UTF-8?q?=F0=9F=8C=AD=20details=3F=20do=20we=20lik?= =?UTF-8?q?e=20this=3F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/content/docs/en/guides/upgrade-to/v6.mdx | 168 +++++++++++-------- 1 file changed, 98 insertions(+), 70 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 3d77aa5272658..a6657833badcf 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -80,88 +80,116 @@ Projects now containing these removed features will be unable to build, and ther In Astro 5.x, it was still possible to use [the Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), either through a `legacy` configuration flag or via built-in backwards compatibility. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your content collections to the new Content Layer API. -Astro v6.0 removes the Content Collections API entirely. All content collections must now use the Content Layer API introduced in Astro v5.0. No backwards compatibility support is available. +Astro v6.0 removes this previously deprecated Content Collections API support entirely. All content collections must now use the Content Layer API introduced in Astro v5.0 that powers all content collections. No backwards compatibility support is available. #### What should I do? -Ensure that your content collections are **fully updated** for the Content Layer API. Astro v5.x included some backwards compatibility that may have allowed your existing collections to continue to work even if only some features of the Content Layer API were upgraded. +Especially if you did not upgrade your collections for Astro v5.0, ensure that your content collections are **fully updated** for the Content Layer API. -You will need to upgrade your collections to be fully compatible with the Content Layer API if you currently have any of the following legacy features: +Astro v5.x included some automatic backwards compatibility under the hood relying on the older Content Collections API. This may have allowed your existing collections to continue to work even when only some features of Content Layer API collections were successfully updated. -- no content collections configuration file -- a configuration file located at `src/content/config.ts` -- a legacy collection definition that does not define a `loader` -- a legacy collection definition that includes a collection type (`type: 'content'` or `type: 'data'`) -- legacy collection querying methods `getDataEntryById()` and `getEntryBySlug()` -- legacy collection querying and rendering methods that depend on a special, reserved `slug` property -- legacy collection rendering methods that do not import and use the Content Layer API `render()` function +Check for any of the following legacy features in your project and take the appropriate action described as necessary. -See the detailed instructions below for updating any legacy content collection to use the Content Layer API. +##### If you have... -BELOW IS STILL THE V5 stuff, NOT UPDATED YET +
+no content collections configuration file +Create `src/content.config.ts` and [define your collections](/en/guides/content-collections/#defining-collections) in it. +
+ +
+a configuration file located at `src/content/config.ts` +Rename and move this file to `src/content.config.ts` +
+ +
+a collection that does not define a `loader` + +Import [Astro's built-in `glob()` loader](/en/guides/content-collections/#built-in-loaders) and define the `pattern` and `base` for your collection entries: + +```ts ins={3,6} +// src/content.config.ts +import { defineCollection, z } from 'astro:content'; +import { glob } from 'astro/loaders'; + +const blog = defineCollection({ + loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }), + schema: z.object({ + title: z.string(), + description: z.string(), + pubDate: z.coerce.date(), + updatedDate: z.coerce.date().optional(), + }), +}); +``` +
+ +
+a collection that defines a collection type (`type: 'content'` or `type: 'data'`) +There are no longer different types of collections. This must be deleted from your collection definition. + +```ts del={7} +// src/content.config.ts +import { defineCollection, z } from 'astro:content'; +import { glob } from 'astro/loaders'; + +const blog = defineCollection({ + // For content layer you no longer define a `type` + type: 'content', + loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }), + schema: z.object({ + title: z.string(), + description: z.string(), + pubDate: z.coerce.date(), + updatedDate: z.coerce.date().optional(), + }), +}); +``` +
+ +
+legacy collection querying methods `getDataEntryById()` and `getEntryBySlug()` +Replace both methods with [`getEntry()`](/en/reference/modules/astro-content/#getentry). + +
-Step-by-step instructions to update a collection from the Content Collecctions API to the new Content Layer API - - - -1. **Move the content config file**. This file no longer lives within the `src/content/` folder. This file should now exist at `src/content.config.ts`. - -2. **Edit the collection definition**. Your updated collection requires a `loader` which indicates both a folder for the location of your collection (`base`) and a `pattern` defining the collection entry filenames and extensions to match. (You may need to update the example below accordingly. You can use [globster.xyz](https://globster.xyz/) to check your glob pattern.) The option to select a collection `type` is no longer available. - - ```ts ins={3,8} del={7} - // src/content.config.ts - import { defineCollection, z } from 'astro:content'; - import { glob } from 'astro/loaders'; - - const blog = defineCollection({ - // For content layer you no longer define a `type` - type: 'content', - loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }), - schema: z.object({ - title: z.string(), - description: z.string(), - pubDate: z.coerce.date(), - updatedDate: z.coerce.date().optional(), - }), - }); - ``` - -3. **Change references from `slug` to `id`**. Content layer collections do not have a reserved `slug` field. Instead, all updated collections will have an `id`: - - ```astro ins={7} del={6} - // src/pages/[slug].astro - --- - export async function getStaticPaths() { - const posts = await getCollection('blog'); - return posts.map((post) => ({ - params: { slug: post.slug }, - params: { slug: post.id }, - props: post, - })); - } - --- - ``` - You can also update the dynamic routing file names to match the value of the changed `getStaticPaths()` parameter. - -4. **Switch to the new `render()` function**. Entries no longer have a `render()` method, as they are now serializable plain objects. Instead, import the `render()` function from `astro:content`. - - ```astro title="src/pages/index.astro" ins=", render" del={6} ins={7} - --- - import { getEntry, render } from 'astro:content'; - - const post = await getEntry('blog', params.slug); - - const { Content, headings } = await post.render(); - const { Content, headings } = await render(post); - --- - - ``` - +legacy collection querying and rendering methods that depend on a special, reserved `slug` property +The [CollectionEntry type](/en/reference/modules/astro-content/#collectionentry) now returns a unique `id`. Replace instances of `slug` with `id`: + +```astro ins={6} del={5} title="src/pages/[slug].astro" +--- +export async function getStaticPaths() { + const posts = await getCollection('blog'); + return posts.map((post) => ({ + params: { slug: post.slug }, + params: { slug: post.id }, + props: post, + })); +} +--- +``` +
+ +
+content rendered using `entry.render()` +Collection entries no longer have a render() method. Instead, import the `render()` function from `astro:content` and use `render(entry)`: + +```astro title="src/pages/index.astro" ins=", render" del={6} ins={7} +--- +import { getEntry, render } from 'astro:content'; + +const post = await getEntry('blog', params.slug); + +const { Content, headings } = await post.render(); +const { Content, headings } = await render(post); +--- + +```
- See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about maintaining backwards compatibility of legacy collections in Astro v5. + See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about backwards compatibility of legacy collections in Astro v5 and upgrading to the new Content Layer API. ### Removed: `` component From 29fb6aa55833336a448f2cea08169d365ea54754 Mon Sep 17 00:00:00 2001 From: sarahrainsberger Date: Wed, 24 Sep 2025 17:46:53 +0000 Subject: [PATCH 06/12] add the implementation PR and some stronger wording --- src/content/docs/en/guides/upgrade-to/v6.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index a6657833badcf..a856d342e8dec 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -78,17 +78,19 @@ Projects now containing these removed features will be unable to build, and ther ### Removed: legacy content collections + + In Astro 5.x, it was still possible to use [the Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), either through a `legacy` configuration flag or via built-in backwards compatibility. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your content collections to the new Content Layer API. -Astro v6.0 removes this previously deprecated Content Collections API support entirely. All content collections must now use the Content Layer API introduced in Astro v5.0 that powers all content collections. No backwards compatibility support is available. +**Astro v6.0 removes this previously deprecated Content Collections API support entirely.** All content collections must now use the Content Layer API introduced in Astro v5.0 that powers all content collections. No backwards compatibility support is available. #### What should I do? Especially if you did not upgrade your collections for Astro v5.0, ensure that your content collections are **fully updated** for the Content Layer API. -Astro v5.x included some automatic backwards compatibility under the hood relying on the older Content Collections API. This may have allowed your existing collections to continue to work even when only some features of Content Layer API collections were successfully updated. +Astro v5.x included some automatic backwards compatibility under the hood relying on the older Content Collections API. This may have allowed your existing collections to continue to work even when only some features of Content Layer API collections were successfully updated. Therefore, your v5 collections may contain one or more legacy features that need updating to the newer API for v6, even if your project was previously error-free. -Check for any of the following legacy features in your project and take the appropriate action described as necessary. +If you have content collections errors after upgrading to v6, use the following list to help you identify and upgrade any legacy features that may exist in your code. ##### If you have... From 41f864b022f99210b46c1800c33a3ef12b9a24f9 Mon Sep 17 00:00:00 2001 From: sarahrainsberger Date: Wed, 24 Sep 2025 17:58:22 +0000 Subject: [PATCH 07/12] add removing legacy flag --- src/content/docs/en/guides/upgrade-to/v6.mdx | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index a856d342e8dec..f1cfc4fd51abe 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -82,11 +82,23 @@ Projects now containing these removed features will be unable to build, and ther In Astro 5.x, it was still possible to use [the Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), either through a `legacy` configuration flag or via built-in backwards compatibility. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your content collections to the new Content Layer API. -**Astro v6.0 removes this previously deprecated Content Collections API support entirely.** All content collections must now use the Content Layer API introduced in Astro v5.0 that powers all content collections. No backwards compatibility support is available. +**Astro v6.0 removes this previously deprecated Content Collections API support entirely, including the `legacy.collections` flag.** All content collections must now use the Content Layer API introduced in Astro v5.0 that powers all content collections. No backwards compatibility support is available. #### What should I do? -Especially if you did not upgrade your collections for Astro v5.0, ensure that your content collections are **fully updated** for the Content Layer API. +If you had previously enabled the legacy flag, you must remove it. + +```ts title="astro.config.mjs" del={5} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + legacy: { + collections: true, + } +}) +``` + +Additionally, if you did not upgrade your collections for Astro v5.0, ensure that your content collections are **fully updated** for the Content Layer API. Astro v5.x included some automatic backwards compatibility under the hood relying on the older Content Collections API. This may have allowed your existing collections to continue to work even when only some features of Content Layer API collections were successfully updated. Therefore, your v5 collections may contain one or more legacy features that need updating to the newer API for v6, even if your project was previously error-free. From 1a71b64e791e132a428704aea43171f952dcd453 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Thu, 25 Sep 2025 13:10:41 -0300 Subject: [PATCH 08/12] don't focus on collection API names, just legacy/new Co-authored-by: Matt Kane --- src/content/docs/en/guides/upgrade-to/v6.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index f1cfc4fd51abe..db25087120cc7 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -98,9 +98,9 @@ export default defineConfig({ }) ``` -Additionally, if you did not upgrade your collections for Astro v5.0, ensure that your content collections are **fully updated** for the Content Layer API. +Additionally, if you did not upgrade your collections for Astro v5.0, ensure that your content collections are **fully updated** for the updated API. -Astro v5.x included some automatic backwards compatibility under the hood relying on the older Content Collections API. This may have allowed your existing collections to continue to work even when only some features of Content Layer API collections were successfully updated. Therefore, your v5 collections may contain one or more legacy features that need updating to the newer API for v6, even if your project was previously error-free. +Astro v5.x included some automatic backwards compatibility to allow content collections to continue to work even if they had not been updated to use the new API. Therefore, your v5 collections may contain one or more legacy features that need updating to the newer API for v6, even if your project was previously error-free. If you have content collections errors after upgrading to v6, use the following list to help you identify and upgrade any legacy features that may exist in your code. @@ -168,8 +168,8 @@ Replace both methods with [`getEntry()`](/en/reference/modules/astro-content/#ge
-legacy collection querying and rendering methods that depend on a special, reserved `slug` property -The [CollectionEntry type](/en/reference/modules/astro-content/#collectionentry) now returns a unique `id`. Replace instances of `slug` with `id`: +legacy collection querying and rendering methods that depend on a `slug` property +Previously the `id` was based on the filename, and there was a `slug` property that could be used in a URL. Now the [CollectionEntry type](/en/reference/modules/astro-content/#collectionentry) `id` is a slug. If you need access to the filename (previously available as the `id`) use the `filePath` property. Replace instances of `slug` with `id`.: ```astro ins={6} del={5} title="src/pages/[slug].astro" --- From e849055320a5f8011d72cd80c46212cf47e2bc0a Mon Sep 17 00:00:00 2001 From: sarahrainsberger Date: Thu, 25 Sep 2025 17:35:35 +0000 Subject: [PATCH 09/12] add placeholder error messages --- .../content-collection-invalid-type.mdx | 23 ++++++++++++++++ .../content-collection-missing-loader.mdx | 25 ++++++++++++++++++ .../errors/legacy-content-config-error.mdx | 26 +++++++++++++++++++ 3 files changed, 74 insertions(+) create mode 100644 src/content/docs/en/reference/errors/content-collection-invalid-type.mdx create mode 100644 src/content/docs/en/reference/errors/content-collection-missing-loader.mdx create mode 100644 src/content/docs/en/reference/errors/legacy-content-config-error.mdx diff --git a/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx b/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx new file mode 100644 index 0000000000000..e2c3860eec7c8 --- /dev/null +++ b/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx @@ -0,0 +1,23 @@ +--- +# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs' +# Do not make edits to it directly, they will be overwritten. +# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +# Translators, please remove this note and the component. + +title: Content collection invalid type. +i18nReady: true +githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +--- + +import DontEditWarning from '~/components/DontEditWarning.astro' + + + + +> Invalid collection type "data". Remove the type from your collection definition in your content config file. + +### What went wrong? + +Content collections should no longer have a type field. Remove this field from your content config file. + +See the [Astro 6 migration guide](https://docs.astro.build/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information. \ No newline at end of file diff --git a/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx b/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx new file mode 100644 index 0000000000000..e0fcb015a5d0d --- /dev/null +++ b/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx @@ -0,0 +1,25 @@ +--- +# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs' +# Do not make edits to it directly, they will be overwritten. +# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +# Translators, please remove this note and the component. + +title: Content collection missing loader. +i18nReady: true +githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +--- + +import DontEditWarning from '~/components/DontEditWarning.astro' + + + + +> Collections must have a loader defined. Check your collection definitions in your content config file. + +### What went wrong? + +A legacy content config file was found. Move the file to `src/content.config.ts` and update any collection definitions if needed. +A content collection is missing a loader definition. Make sure that each collection in your content config file has a loader. + +**See Also:** +- [Content collections configuration](https://docs.astro.build/en/guides/content-collections/#defining-the-collection-loader) diff --git a/src/content/docs/en/reference/errors/legacy-content-config-error.mdx b/src/content/docs/en/reference/errors/legacy-content-config-error.mdx new file mode 100644 index 0000000000000..f91bd35d62425 --- /dev/null +++ b/src/content/docs/en/reference/errors/legacy-content-config-error.mdx @@ -0,0 +1,26 @@ +--- +# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs' +# Do not make edits to it directly, they will be overwritten. +# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +# Translators, please remove this note and the component. + +title: Legacy content config error. +i18nReady: true +githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +--- + +import DontEditWarning from '~/components/DontEditWarning.astro' + + + + +> Legacy content config file found. + +### What went wrong? + +A legacy content config file was found. Move the file to `src/content.config.ts` and update any collection definitions if needed. + +See the [Astro 6 migration guide](https://docs.astro.build/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information. + +**See Also:** +- [Content collections configuration](https://docs.astro.build/en/guides/content-collections/#the-collection-config-file) From 171c4162d3621a35097f5b3604b0f498cef7f4e6 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Thu, 25 Sep 2025 14:44:43 -0300 Subject: [PATCH 10/12] relative links --- .../en/reference/errors/content-collection-invalid-type.mdx | 2 +- .../en/reference/errors/content-collection-missing-loader.mdx | 2 +- .../docs/en/reference/errors/legacy-content-config-error.mdx | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx b/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx index e2c3860eec7c8..79332174c63d2 100644 --- a/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx +++ b/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx @@ -20,4 +20,4 @@ import DontEditWarning from '~/components/DontEditWarning.astro' Content collections should no longer have a type field. Remove this field from your content config file. -See the [Astro 6 migration guide](https://docs.astro.build/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information. \ No newline at end of file +See the [Astro 6 migration guide](/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information. \ No newline at end of file diff --git a/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx b/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx index e0fcb015a5d0d..31b755e695cff 100644 --- a/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx +++ b/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx @@ -22,4 +22,4 @@ A legacy content config file was found. Move the file to `src/content.config.ts` A content collection is missing a loader definition. Make sure that each collection in your content config file has a loader. **See Also:** -- [Content collections configuration](https://docs.astro.build/en/guides/content-collections/#defining-the-collection-loader) +- [Content collections configuration](/en/guides/content-collections/#defining-the-collection-loader) diff --git a/src/content/docs/en/reference/errors/legacy-content-config-error.mdx b/src/content/docs/en/reference/errors/legacy-content-config-error.mdx index f91bd35d62425..8dcd318ea0da5 100644 --- a/src/content/docs/en/reference/errors/legacy-content-config-error.mdx +++ b/src/content/docs/en/reference/errors/legacy-content-config-error.mdx @@ -20,7 +20,7 @@ import DontEditWarning from '~/components/DontEditWarning.astro' A legacy content config file was found. Move the file to `src/content.config.ts` and update any collection definitions if needed. -See the [Astro 6 migration guide](https://docs.astro.build/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information. +See the [Astro 6 migration guide](/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information. **See Also:** -- [Content collections configuration](https://docs.astro.build/en/guides/content-collections/#the-collection-config-file) +- [Content collections configuration](/en/guides/content-collections/#the-collection-config-file) From 5adf67eddfc05ebfb6cbd36c916adf46c969e83e Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Fri, 26 Sep 2025 08:59:57 -0300 Subject: [PATCH 11/12] links to Content Layer API deep dive blog post and content collection error messages --- src/content/docs/en/guides/upgrade-to/v6.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index db25087120cc7..0bd1dbdf8f801 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -82,7 +82,7 @@ Projects now containing these removed features will be unable to build, and ther In Astro 5.x, it was still possible to use [the Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), either through a `legacy` configuration flag or via built-in backwards compatibility. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your content collections to the new Content Layer API. -**Astro v6.0 removes this previously deprecated Content Collections API support entirely, including the `legacy.collections` flag.** All content collections must now use the Content Layer API introduced in Astro v5.0 that powers all content collections. No backwards compatibility support is available. +**Astro v6.0 removes this previously deprecated Content Collections API support entirely, including the `legacy.collections` flag.** All content collections must now use [the Content Layer API introduced in Astro v5.0](https://astro.build/blog/content-layer-deep-dive/) that powers all content collections. No backwards compatibility support is available. #### What should I do? @@ -102,7 +102,7 @@ Additionally, if you did not upgrade your collections for Astro v5.0, ensure tha Astro v5.x included some automatic backwards compatibility to allow content collections to continue to work even if they had not been updated to use the new API. Therefore, your v5 collections may contain one or more legacy features that need updating to the newer API for v6, even if your project was previously error-free. -If you have content collections errors after upgrading to v6, use the following list to help you identify and upgrade any legacy features that may exist in your code. +If you have [content collections errors](/en/reference/error-reference/#content-collection-errors) or warnings after upgrading to v6, use the following list to help you identify and upgrade any legacy features that may exist in your code. ##### If you have... From b342d32808b9d1236d4238863f770b43e21dd397 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Fri, 17 Oct 2025 10:47:49 -0300 Subject: [PATCH 12/12] Polishing of upgrade guidance, fix an error message --- src/content/docs/en/guides/upgrade-to/v6.mdx | 4 ++-- .../en/reference/errors/content-collection-missing-loader.mdx | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index cf25e0a858047..a250d89792a77 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -166,7 +166,7 @@ Projects now containing these removed features will be unable to build, and ther -In Astro 5.x, it was still possible to use [the Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), either through a `legacy` configuration flag or via built-in backwards compatibility. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your content collections to the new Content Layer API. +In Astro 5.x, it was still possible to use [the original Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), either through a `legacy` configuration flag or via built-in backwards compatibility. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your existing content collections to those powered by the new Content Layer API. **Astro v6.0 removes this previously deprecated Content Collections API support entirely, including the `legacy.collections` flag.** All content collections must now use [the Content Layer API introduced in Astro v5.0](https://astro.build/blog/content-layer-deep-dive/) that powers all content collections. No backwards compatibility support is available. @@ -289,7 +289,7 @@ const { Content, headings } = await render(post);
- See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about backwards compatibility of legacy collections in Astro v5 and upgrading to the new Content Layer API. + See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about backwards compatibility of legacy collections in Astro v5 and full step-by-step instructions for upgrading legacy collections to the new Content Layer API. ### Removed: `` component diff --git a/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx b/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx index 31b755e695cff..224406aa602c6 100644 --- a/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx +++ b/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx @@ -18,7 +18,6 @@ import DontEditWarning from '~/components/DontEditWarning.astro' ### What went wrong? -A legacy content config file was found. Move the file to `src/content.config.ts` and update any collection definitions if needed. A content collection is missing a loader definition. Make sure that each collection in your content config file has a loader. **See Also:**