Experimental and Legacy Flags

Legacy Flags

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.

legacy.collections

Type: boolean
Default: false

Added In:

Enable legacy behavior for content collections.

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:

src/content/config.ts

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({ })

export const collections = { blog };

Experimental Flags

Astro offers experimental flags to give users early access to new features. These flags are not guaranteed to be stable.

experimental.clientPrerender

Type: boolean
Default: false

Added In:

Enables pre-rendering your prefetched pages on the client in supported browsers.

This feature uses the experimental Speculation Rules Web API and enhances the default prefetch behavior globally to prerender links on the client. You may wish to review the possible risks when prerendering on the client before enabling this feature.

Enable client side prerendering in your astro.config.mjs along with any desired prefetch configuration options:

astro.config.mjs

{
  prefetch: {
    prefetchAll: true,
    defaultStrategy: 'viewport',
  },
  experimental: {
    clientPrerender: true,
  },
}

Continue to use the data-astro-prefetch attribute on any <a /> link on your site to opt in to prefetching. Instead of appending a <link> tag to the head of the document or fetching the page with JavaScript, a <script> tag will be appended with the corresponding speculation rules.

Client side prerendering requires browser support. If the Speculation Rules API is not supported, prefetch will fallback to the supported strategy.

experimental.contentIntellisense

Type: boolean
Default: false

Added In:

Enables Intellisense features (e.g. code completion, quick hints) for your content collection entries in compatible editors.

When enabled, this feature will generate and add JSON schemas to the .astro directory in your project. These files can be used by the Astro language server to provide Intellisense inside content files (.md, .mdx, .mdoc).

{
  experimental: {
    contentIntellisense: true,
  },
}

To use this feature with the Astro VS Code extension, you must also enable the astro.content-intellisense option in your VS Code settings. For editors using the Astro language server directly, pass the contentIntellisense: true initialization parameter to enable this feature.