Astro 5.13 | Astro

🍀 Lucky Astro 5.13 brings experimental improvements to environment variable handling, support for Chrome DevTools workspaces, and more!

The starting lineup includes:

Experimental static import.meta.env
Experimental Chrome DevTools workspace support
Multiple sitemaps
Experimental hosted error pages with the Node.js adapter
Enum support in Astro DB tables
Local support for Cloudflare KV

To upgrade an existing project, use the automated @astrojs/upgrade CLI tool. Alternatively, upgrade manually by running the upgrade command for your package manager:

# Recommended:
npx @astrojs/upgrade

# Manual:
npm install astro@latest
pnpm upgrade astro --latest
yarn upgrade astro --latest

Experimental static `import.meta.env`

Environment variables can be complicated! Astro’s astro:env API allows you to configure a type-safe schema for your environment variables, and converts variables imported via astro:env into the expected type. This is the recommended way to use environment variables in Astro, as it allows you to easily see and manage whether your variables are public or secret, available on the client or only on the server at build time, and the data type of your values.

However, you can still access your environment variables through process.env as well as import.meta.env directly if needed. This was the only way to use environment variables in Astro before astro:env was added in Astro 5.0, and its handling of import.meta.env includes some logic that was intended for earlier versions of Astro that is no longer necessary.

Astro 5.13 includes a new experimental.staticImportMetaEnv flag that updates the behavior of import.meta.env to align with Vite’s handling of environment variables and for better ease of use with Astro’s current implementations and features. This flag supersedes the previous rawEnvVariables as a more complete solution for handling private meta environment variables. This will become the default behavior in Astro 6.0, and this early preview is introduced as an experimental feature.

Currently, non-public import.meta.env environment variables are replaced by a reference to process.env. Additionally, Astro may also convert the value type of your environment variables used through import.meta.env, which can prevent access to some values, such as the strings "true" (which is converted to a boolean value), and "1" (which is converted to a number).

The experimental.staticImportMetaEnv flag simplifies Astro’s default behavior, making it easier to understand and use. Astro will no longer replace any import.meta.env environment variables with a process.env call, nor will it coerce values. Instead, your private meta environment variables will always be inlined.

To enable this feature, add the experimental flag in your Astro config and remove the experimental.rawEnvValues flag if it was enabled:

import { defineConfig } from "astro/config";

export default defineConfig({
   experimental: {
     staticImportMetaEnv: true,
     rawEnvValues: true
   }
});

See the experimental static import.meta.env documentation for more information about opting in to this early feature preview and how to update your project code accordingly.

You can learn more about using environment variables in Astro, including astro:env, in the environment variables documentation.

Experimental Chrome DevTools workspace support

Chrome workspace folders allow you to save changes made in DevTools back to your project code via a connected workspace folder. This allows you to apply edits such as CSS adjustments without ever leaving your browser tab!

Astro 5.13 brings a new experimental option for the Astro dev server to automatically configure a Chrome DevTools workspace for your project. Your project folder will appear as a workspace source, no manual configuration needed, ready for you to connect. Then, any changes that you make in the “Sources” panel are automatically saved to your local source files.

To enable this feature, add the experimental flag chromeDevtoolsWorkspace to your Astro config:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    chromeDevtoolsWorkspace: true
  }
});

See the experimental Chrome DevTools workspace feature documentation for more information.

Multiple sitemaps

The @astrojs/sitemap integration has always supported the option to include externally-generated pages in the sitemap-index.xml file generated by Astro. This allows you to include pages in your sitemap that are a part of your deployed site, but not created by Astro.

The latest release of the integration adds a new customSitemaps configuration option to include externally-generated sitemaps in the sitemap-index.xml file along with the Astro-generated sitemap entries.

This is useful for multi-framework setups on the same domain as your Astro site (example.com), such as a blog at example.com/blog whose sitemap is generated by another framework.

You can specify any additional sitemaps in your sitemap configuration:

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    sitemap({
      customSitemaps: [
       'https://example.com/blog/sitemap.xml',
       'https://example.com/helpcenter/sitemap.xml'
      ]
    })
  ]
});

Learn more in the @astrojs/sitemap configuration documentation.

Thanks to Gourav Khunger who contributed this feature.

Experimental hosted error pages

The latest release of the Node.js adapter ships with experimental support for loading prerendered custom error pages from any specified host.

Astro needs to be able to load your 404 page in order to return it in a response. By default, Astro will load prerendered custom error pages from the same host as the one that the request is made to. For example, if a request is made to https://example.com/nonexistent-page, Astro will attempt to load the prerendered error page from https://example.com/404.html.

@astrojs/node@9.4.0 now handles situations where your custom error page must be loaded from a different host, such as when the server is running behind a reverse proxy or in a container that may not have access to the external host URL. You can also use this option when it is more efficient to load the prerendered error page from localhost rather than via the public internet.

To use this feature, set the experimentalErrorPageHost adapter option in your Astro configuration to the desired host URL. For example, if your server is running on localhost and served via a proxy, you can ensure the prerendered error pages are fetched via the localhost URL:

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    // If your server is running on localhost and served via a proxy,
    // set the host like this to ensure prerendered error pages are fetched via the localhost URL
    experimentalErrorPageHost: 'http://localhost:4321'
  })
});

For more information on enabling and using this experimental feature, see the @astrojs/node adapter docs.

Enum support in Astro DB tables

We are sure you’ll be ({ enum: ['happy', 'thrilled', 'over the moon'] }) about this update to Astro DB!

The latest release of @astrojs/db brings long-awaited enum support for text columns in Astro DB tables. This behavior better aligns with user expectations and with the underlying Drizzle implementation.

Note that this is used exclusively to generate types, and no runtime validation will be performed. Removing, adding, and changing values should be handled in your own project code.

import { column, defineTable } from 'astro:db';

// Table definition
const UserTable = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    name: column.text(),
        rank: column.text({ enum: ['user', 'mod', 'admin'] })
  }
});

// Resulting type definition
type UserTableInferInsert = {
    id?: string;
    name: string;
    rank: "user" | "mod" | "admin";
}

Local support for Cloudflare KV

The newest release of the Cloudflare adapter includes local support for Cloudflare Workers KV when running astro dev. This internal refactoring is a drop-in replacement for powering Astro sessions and does not require any change to your existing project code.

However, you can now choose to connect to the remote Cloudflare KV Namespace if desired and use production data during local development.