Singletons in the Content Collections API

[joshdchang]

Summary

I'm proposing adding a simple way of indicating to the Content Collections API that a collection is a singleton and should have exactly one entry. These could be used to more intuitively describe single pages, footer/header content, common settings, and more.

Background & Motivation

I love Astro, and I especially love the new Content Collections API. I think it is such a clean and easy way of separating editable content from page structure, styling, and other concerns — especially when you want your content to be editable by less technical users. I have been building a new website using the API, and I had an idea for a small improvement that could improve it.

I want to load the content of my about page from the Content Collections API so that it can have a type-safe schema and intellisense. Right now, I am doing this as follows:

// content/config.ts

const aboutCollection = defineCollection({
  schema: {
    //...
  },
});
// other collections and singletons...

export default collections = {
  'about': aboutCollection,
  // other collections and singletons...
};

content
├── about
│   ├── index.md
├── home
│   ├── index.md
├── header
│   ├── index.md
├── footer
│   ├── index.md
├── settings
│   ├── index.md
└── config.ts

// about.astro

const about = await getEntryBySlug('about', 'index');

This is not bad, but I think it could be even better if there we a more explicit way of defining singletons. This would improve code readability, simplify the directory structure, and make singletons more enforceable (instead of feeling like a workaround). It would especially improve the experience of less technical users who wish to understand and update the content directory, while also adding more context for more advanced use cases (like creating a visual CMS based on the schema that writes to the content directory).

This is a very small change (mostly just syntactic sugar). I imagine it would not be too difficult to implement and would add very little complexity.

Goals

• Make singletons more explicit and enforceable
• Simplify the structure of the content directory
• Empower new developers and less technical users to more easily understand a project's content directory
• Enable other programs (like a visual CMS that configures itself using config.ts, for example) to know which entries are singletons and which are part of a collection.

Example

One way to do this would be to create new function called defineSingleton to be used in the config.ts file:

const aboutSingleton = defineSingleton({
  schema: z.object({
    //...
  }),
});
// other collections and singletons...

Singletons could be exported along with normal collections:

export const collections = {
  'about': aboutSingleton,
  // other collections and singletons...
};

Or they could be exported separately (i.e. export const singletons = {...}), mitigating the need for a new defineSingleton function.

Then, the content directory would look something like this:

content
├── about.md
├── home.md
├── header.md
├── footer.md
├── settings.md
└── config.ts

Finally, to use the singleton, there would be a getSingleton function (similar to getEntryBySlug, but with only one parameter):

const about = await getSingleton('about');

I feel like this would be a more explicit, clean, and enforceable way of providing type-safe markdown content for special pages like an about page or a homepage.

[louisescher]

It's been quite a while now since this has proposed, and I think there is some real value in having singleton entries in Astro. As OP has described, it's quite common to use content collections with a single entry for displaying content on a singular page alone. As an example, I do this on my own page for the topmost "about" section, but something like a privacy policy page would also benefit from this.

To build on the proposed idea, I think there should be a dedicated "singletons directory" of some kind for better organization:

content
├── singletons/
    ├── home.md
    ├── footer.md
    └── about.md
└── other-collection/

The main benefit here, in my opinion, is on the sides of DX and directory structure complexity. The current setup with an "index" file works, but it leads to lots of folders with very little subcontent.

[Adammatthiesen]

Yeah @ArmandPhilippot Your right... it really wouldn't be too bad to build with Content loaders 🤔

[florian-lefebvre]

The problem is each singleton problem has a different schema, which doesn't work ootb in your example. Although a little package could abstract this logic away, that's for sure

[ArmandPhilippot]

Yeah, I wasn't sure if "singleton" meant a different schema or not. The example was written before the Content Loader API so I assumed this could be only an organizational issue because pages often use the same schema, and if some needs additional fields we can deal with that using optional fields.

So, yes, if we need to support conditional schema based on which entry is loaded, my example is not enough. I guess someone could create a different collection for each but that's not ideal...

[louisescher]

If we are using content loaders then the directory would be decided by the user's loader would it not?

Yeah, good point. It'd probably work with the file loader? We're moving away from the old content collections, so that makes sense. Having an extra directory would probably feel restricting anyway.

What confuses me is that this idea was proposed long before the Content Loader API, and so what is described here seems already achievable with the current API? Unless "singletons" are meant to have different schemas?

As Florian said, the issue is probably schemas. The above works for basic markdown files, but once you introduce frontmatter structures it gets complicated.

Although a little package could abstract this logic away, that's for sure

Might be nice to have this as a proof of concept. What would be your approach here @florian-lefebvre?

[florian-lefebvre]

Not 100% sure but something like this:

// content.config.ts
import { singletonCollection } from 'astro-singletons'
import { z } from 'astro/zod'

export const collections = {
	...singletonCollection({
		about: z.object({
			foo: z.string()
		}),
		config: z.object({
			bar: z.number()
		})
	})
}

Under the hood this uses a fork of the glob loader that turns it into a discriminated union schema, eg.

const schema = z.discriminatedUnion('__internalType', [
	z.object({
		__internalType: z.literal('about'),
		...options.about.shape
	}),
	// ...
])

And transforms the data to append the discriminator

if (entry.slug === 'about.json') {
	entry.data.__internalType = 'about'
}

Then have a custom util to retrieve the singleton:

import { getSingleton } from 'virtual:singletons'

const singleton = await getSingleton('about')

This may not even need an integration if you manage to reuse the generated types of astro:content.

This is mostly pseudo code but you get the idea!

[florian-lefebvre]

2 questions:

1. How do you think singletons integrate with the concept of collection content loaders?
2. How do you think singletons integrate with the concept of live collections?

[louisescher]

1. I think a singleton could probably use / be restricted to using the file loader.
2. I think there might be a use-case for this as well? A live collection could still face the same issue, having a single entry which could be identified via a slug, but could also be fetched on its own. I imagine it would function similarly for the end user to non-live collections.

The biggest issue for me, at least right now, is how to properly define schemas. Maybe there's some type-gen that can be done so a singleton doesn't even need to have a schema defined, but that feels like a bit too much magic? But if the user does have to define a schema, we're very close to the current workaround and would just be abstracting around 5 - 15 lines of code, which the user could probably do themselves.