Move content collection config outside src/content/

[bholmesdev]

Body

Summary

Introduce a way to configure content collections from your project root, instead of a file within src/content/.

Background & Motivation

Today, content collections are configured from a config.ts file nested in src/content/. This is intuitive, though it has some flaws from tech debt and user perspectives:

• The config must be processed by Vite. By nesting in src, developers (understandably) expect Vite aliases and exotic file imports (ex. importing a const from a .jsx file) to work. This config is loaded at build time rather than runtime to ensure collection schema errors are resolved before you deploy your site. To support all of Vite's features while also loading separately from the rest of your build, we've needed a complex flow to spin up and spin down a separate Vite server. This has caused multiple p4-important bug fixes ([Content collections] Load content config with full Vite setup astro#6092, [Content collections] Surface content config errors in overlay astro#6170, Fix: stop executing astro:server:setup twice astro#6693) to handle properly.
• This locks your config to the src/content/ directory. This closes the door to moving content/ outside of src, which theme explorations like Astro Starbook (a documentation starter) could benefit from. It also makes introducing new concepts like a src/data/ directory feel unnatural.

Each of these concerns could be addressed by moving the config outside of the src/content/ directory.

Goals

• Remove the need for a separate Vite server when processing your content config. This means removing support for Vite plugin processing in your content config (ex. aliases).
• [Needs consensus] Unblock the src/data/ directory for data content collections

[bholmesdev]

Here are a few initial ideas for where collection config could live:

1. In a new config file at the project root. File formatting would remain the same. Potential naming conventions: astro.content.mjs, astro.collections.mjs
2. Move collection config into the astro.config file. This could mean a new collections key on the base config like so:

// astro.config.mjs
import { defineConfig, defineCollection, z /** could come from astro:content too? */ } from 'astro/config';

export default defineConfig({
  collections: { blog }
});

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
  }),
});

With this second option, users could also continue storing collections in a separate file to ease migration. They would just need to import this file into the astro.config to wire it up:

// my-collections.mjs
import { defineCollection, z } from 'astro/config';

export default defineConfig({
  collections: { blog }
});

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
  }),
});

export const collections = { blog };


// astro.config.mjs
import { defineConfig } from 'astro/config';
import { collections } from 'my-collections.mjs';

export default defineConfig({
  collections,
});

Open questions:

• Would we continue to import defineCollection from astro:content? Since the config is no longer loaded by Vite, we would need a special case to support this module from the astro.config file. A second option would be to expose defineCollection and z from astro/config instead.
• Would we continue to recommend .ts as the config file extension? We can change to .mjs to fall inline with our astro.config recommendation. By using defineCollection, the same autocomplete from .ts is possible in .mjs.

[FredKSchott]

I like astro.config.js a lot but I think your .ts comment is essential here. We'd almost certainly be pushing for astro.config.ts then, or no? Does that impact our ability to do things like statically analyze that file or run astro add?

[bholmesdev]

@FredKSchott astro.config.ts wouldn't be required! Since we're using Zod and define utility functions, .mjs should have the same autocomplete experience. Only tweak would be adding allowJs: true to your tsconfig.json.

That said, there should be an impact static analyzability or astro add. Both should be features users are happily using today.

[matthewp]

Thanks for kicking this off Ben. One of the goals here is a little unclear to me:

Allow content configuration outside of src/content/.

Why is this a goal? In the motivation section you talk about data collections and I think that's part of the reason for this goal. Is the reason that we should be able to define schemas for content and data in the same place?

If so could you make that a goal as well?

[FredKSchott]

+1! I think there are a few additional goals kind of hinted at in the background/motivation that I don't see listed, so it's hard to understand how important they are to the solution:

• Supporting a src/data folder (probably need consensus on this if it's to be an important goal here)
• Supporting moving content/ out of the src/ folder (feature request from Starbook)

I love the goal around this making more sense conceptually though.

[bholmesdev]

Thanks all! I agree the goal of "moving out of src" is an outcome instead of a root goal. I'll admit the primary motivator is the tech debt supporting config within src has caused, which I'd like to unravel. The secondary goals are each in support of future ideas (Starbook and src/data/) that have not been accepted.

[bholmesdev]

Update: the fact that my "run pnpm astro sync" comment has received 17 reactions is a sign of something. Using astro:content for the config module leads to a lot of confusion, since running the sync server before configuring isn't intuitive. withastro/astro#5711 (comment)

[florian-lefebvre]

In v5, the new default location for the content layer config is src/content.config.ts