From 266da4d785f3fe3c527c712c7b88ea82df67ec0d Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Wed, 2 Oct 2024 14:46:04 +0100 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Sarah Rainsberger --- .changeset/quick-onions-leave.md | 6 ++-- packages/astro/src/types/public/config.ts | 36 +++++++++++++++++++---- 2 files changed, 33 insertions(+), 9 deletions(-) diff --git a/.changeset/quick-onions-leave.md b/.changeset/quick-onions-leave.md index 083de13ef939..a47e1317eea3 100644 --- a/.changeset/quick-onions-leave.md +++ b/.changeset/quick-onions-leave.md @@ -22,11 +22,11 @@ In order to achieve backwards compatibility with existing `data` collections, th - Entries have an ID that is not slugified - `getDataEntryById` is supported -While this backwards compatibility implementation is able to emulate most of the features of legacy collections, there are some differences and limitations that may cause breaking changes to existing collections: +While this backwards compatibility implementation is able to emulate most of the features of legacy collections, **there are some differences and limitations that may cause breaking changes to existing collections**: -- In previous versions of Astro, collexctions 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({})`. To make it easier to migrate, for now Astro will still generate collections for folders without config, but *only* if no other collections use the new `loader()` syntax. A warning will be logged if this fallback behavior is used, and it will be removed in a future version. +- 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 they are returned may be different than before. If you need a specific order, you should sort the collection entries yourself. +- 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 should 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. diff --git a/packages/astro/src/types/public/config.ts b/packages/astro/src/types/public/config.ts index 287e40aa6aa7..fa82c2004566 100644 --- a/packages/astro/src/types/public/config.ts +++ b/packages/astro/src/types/public/config.ts @@ -1550,13 +1550,37 @@ export interface AstroUserConfig { * @version 5.0.0 * @description * Enable legacy behavior for content collections. - * If enabled, data and content collections are handled using the legacy code instead of Content Layer API. - * Any collections with a loader defined will still use the Content Layer API. When enabled, you cannot use - * the glob loader for any collections in the `src/content` directory, and they will instead be handled by - * the legacy code. + * + * ```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: * - * To migrate to the new Content Layer API, you should remove this flag and define a collection for any - * directories in `src/content` that you want to use as a collection. + * - 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 }; + * ``` + * + */ collections?: boolean; };