Astro 3.0 breaking changes tracker

[matthewp]

📋 Explain your issue

This issue is to track 3.0 breaking changes to be part of the guide. Will add things to this through comments, using this template:

### [changed/removed/added/deprecated] feature/name/title/description
In Astro v2.x, [ a statement in the past tense about what Astro did/used to do. e.g. Astro bundled all assets into several different folders....]

Astro v3.0 [ a statement in the present tense about how Astro works now. e.g. now bundles all assets into one single folder located in... ]

#### What should I do?

[Active sentences in the imperative (command) tense, with code examples showing diffs as appropriate]

e.g. Update... / Remove... / Replace... / Create...

Example upgrade guide: https://docs.astro.build/en/guides/upgrade-to/v2/

[Princesseuh]

Removed support for Node 16

In Astro v2.x, Node 16 was supported.

Astro v3.0 it's not the case anymore, the lowest supported version is now v18.14.1

What should I do?

https://docs.astro.build/en/guides/upgrade-to/v2/ has a section for when we dropped Node 14, so it'll be pretty much the same thing. This page also has a mention of the supported version: https://docs.astro.build/en/install/auto/

If a technical reason is wanted, Node 16 is getting deprecated in September, so not too long after Astro 3.0 releases. Additionally v18.14.1 was chosen specifically because of bugs in previous versions of Node 18

[ematipico]

Deprecated lowercase function endpoints

In Astro v2.x, endpoints are defined using lowercase function names: get, post, put, all, and del.

Astro v3.0 deprecates them in favour of uppercase function names.

What should I do?

Update the names as follow:

• get to GET
• post to POST
• put to PUT
• all to ALL
• del to DELETE

[Princesseuh]

Removed automatic flattening of getStaticPaths's return value

In Astro v2.x, we would magically flatten the result of getStaticPaths automatically for the user, so if you returned an array of array, it would still work

Astro v3.0 we removed this in favour of the user doing it themselves when they need to, in line with how we typically prefer for users to do explicit things.

What should I do?

If you're returning an array of arrays instead of an array of object (as you should), please flatten it using .flat(), or if you're using a .map(), use .flatMap() instead

(we also added an error message for this)

[bluwy]

Changed internal MDX and JSX plugins sorting responsibility

In Astro v2.x, Astro core would sort the MDX plugin before the JSX plugin to transform code correctly.

Astro v3.0 now lets the MDX integration (@astrojs/mdx) be responsible for the plugin sorting. Astro core does not have hardcoded MDX plugin sorting handling.

What should I do?

Update @astrojs/mdx to latest.

(PR: withastro/astro#7872)

[matthewp]

[changed/removed/added/deprecated] feature/name/title/description

In Astro v2.x, Astro.cookies.get(key) would always return a AstroCookie object, even if the cookie did not exist. To check for the existence you needed to use Astro.cookies.has(key).

Astro v3.0 Astro.cookies.get(key) will return undefined if the cookie does not exist.

What should I do?

With TypeScript you will need to use the ! assertion when getting a cookie that you know exists:

---
if(Astro.cookies.has(id)) {
  const id = Astro.cookies.get(id)!;
}
---

If you could also skip has() and just check if the value is undefined like so:

---
const id = Astro.cookies.get(id)!;
if(id) {
  // TypeScript knows id is an AstroCookie
}
---

[Princesseuh]

Changed astro check command to use an external package @astrojs/check

In Astro v2.x, astro check's dependencies were bundled in Astro. This was problematic because it meant a larger package even if you don't use astro check and also prevented users from having control over the version of TypeScript and the Astro Language Server to use

Astro v3.0, astro check now requires @astrojs/check and typescript to be installed into the user's project. When starting astro check without those dependencies being present, Astro will prompt the user to install them, like so:

What should I do?

Either run astro check and press Yes at the "Astro will install the deps for you" question, or manually install @astrojs/check and typescript into your project

[Princesseuh]

Changed default image service to Sharp instead of Squoosh

In Astro v2.x, Squoosh was the default image service

Astro v3.0, Sharp is now the default image service

What should I do?

For 99.999% of people, nothing! This change is invisible. However, if you still need the Squoosh service for some reason, you can use it like this:

import { defineConfig, squooshImageService } from "astro/config";

// https://astro.build/config
export default defineConfig({
  image: {
    service: squooshImageService(),
  }
})

But be warned that it will highly probably be removed in the future.

[bluwy]

Changed internal MDX custom components export handling responsibility

In Astro v2.x, the export const components feature in MDX is handled through Astro core, causing MDX integration logic tied to core.

Astro v3.0 moves this responsibility back to the MDX integration to handle it itself.

What should I do?

Update @astrojs/mdx to latest.

(PR: withastro/astro#7904)

[Princesseuh]

Removed @astrojs/image

In Astro v2.x, this package existed

Astro v3.0, it does not anymore, replaced by astro:assets

What should I do?

Migrate to astro:assets. In .astro files this is really just a replace @astrojs/image by astro:assets in most cases, however if you used the Picture component, you'll need at this time to recreate it using the getImage APIs.

[ematipico]

changed the default value of compressHTML

In Astro v2.x, Astro compressed the emitted HTML by explicitly setting the configuration to true

defineConfig({
	compressHTML: true
})

Astro v3.0 now compress the HTML by default.

What should I do?

Remove compressHTML: true from your configuration.

Update to the configuration with compressHTML: false if you DON'T want to compress the HTML.

[sarah11918]

changed - default port used

In Astro v2.x, Astro ran on port 3000 by default

Astro v3.0 changes the default port to 4321 🚀

What should I do?

Update any references to localhost:3000 for example in tests or in your README

(Discord user reported this as a breaking change: https://discord.com/channels/830184174198718474/830184175176122389/1136797603393183775 )

[bluwy]

Removed @astrojs/markdown-component support

In Astro v2.x, it included internal code to keep @astrojs/markdown-component working, which had been deprecated since Astro v1. This increases the SSR bundle size for projects not using the <Markdown /> component.

Astro v3.0 removes the internal code, so <Markdown /> will no longer work.

What should I do?

Remove usages of <Markdown /> and the @astrojs/markdown-component package, or use community packages that provide a similar component like https://github.com/natemoo-re/astro-remote instead.

(PR: withastro/astro#7931)

[bluwy]

Changed import.meta.env.BASE_URL default trailingSlash behaviour

In Astro v2.x, import.meta.env.BASE_URL, which derives from base config, is always appended a trailingSlash by default or when trailingSlash: "ignore" is set.

Astro v3.0 import.meta.env.BASE_URL is not appended with a trailingSlash by default or when trailingSlash: "ignore" is set. The existing behavior of base in combination with trailingSlash: "always" or trailingSlash: "never" is unchanged.

What should I do?

If your base already has a trailing slash, no change is needed.

If your base does not have a trailing slash, add one to preserve the previous behaviour:

// astro.config.mjs
- base: 'my-base',
+ base: 'my-base/',

(PR: withastro/astro#7878)

[ematipico]

deprecated build.excludeMiddleware and build.split

In Astro v2.x, build.excludeMiddleware and build.split could be used to change how specific files were emitted.

Astro v3.0, these options have been deprecated.

What should I do?

Update the config file to use the option in the adapter.

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/serverless";

export default defineConfig({
     build: {
-        excludeMiddleware: true
     },
     adapter: vercel({
+        edgeMiddleware: true
     }),
});

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/serverless";

export default defineConfig({
     build: {
-        split: true
     },
     adapter: vercel({
+        functionPerRoute: true
     }),
});

import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify/functions";

export default defineConfig({
     build: {
-        excludeMiddleware: true
     },
     adapter: netlify({
+        edgeMiddleware: true
     }),
});

import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify/functions";

export default defineConfig({
     build: {
-        split: true
     },
     adapter: netlify({
+        functionPerRoute: true
     }),
});

[bluwy]

Changed tsconfig.json presets

In Astro v2.x, the tsconfig.json presets include support for both TypeScript 4.x and 5.x.

Astro v3.0 updates the tsconfig.json presets to only support TypeScript 5.x.

What should I do?

Update your TypeScript version to at least v5.0.

npm install typescript@latest --save-dev

(PR: withastro/astro#7785)

[bluwy]

Added simple asset support for Cloudflare, Deno, Vercel Edge and Netlify Edge

In Astro v2.x, using the assets feature in Cloudflare, Deno, Vercel Edge and Netlify Edge errors in runtime as the environments do not support Astro's builtin Squoosh and Sharp image optimization.

Astro v3.0 allows these environments to work without errors, but does not perform any image transformation and processing. However, you would still get benefits, e.g. no Cumulative Layout Shift (CLS), enforced alt attribute, etc.

What should I do?

If you previously avoided the assets feature due these constraints, you can now use them without issues. You can also use the no-op image service to explicitly opt-in to this behaviour:

// astro.config.mjs
export default {
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
}

(PR: withastro/astro#7903)

[ematipico]

Changed the default value of scopedStyleStrategy

In Astro v2.x, the default value of scopedStyleStrategy was "where".

Astro v3.0, the default value is "attribute"

What should I do?

You need to update the configuration file if you want to retain the old behaviour

export default defineConfig({
+	scopedStyleStrategy: "where"
})

[matthewp]

Changed Multiple JSX framework configuration

In Astro v2.x, you could use multiple JSX framework integrations (React, Solid, Preact) in the same project and Astro without having to identify which files belonged to which framework.

Astro v3.0, in order to better support single-framework usage, now requires that you specify which files are included in each integrations config. This change is only needed if using more than one of these frameworks; otherwise no configuration is needed.

What should I do?

When using multiple JSX frameworks in the same project, use the include and/or exclude configuration options to specify which files belong to which framework. We recommend having common framework components in the same folder; for ex. components/react/ and components/solid/. This is not required but makes configuration easier:

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';

export default defineConfig({
  // Enable many frameworks to support all different kinds of components.
  integrations: [
    preact({ include: ['**/preact/*'] }),
    solid({ include: ['**/solid/*'] }),
    react({ include: ['**/react/*'] }),
  ],
});

[bluwy]

Removed kebab-case transform for camelCase CSS variables

In Astro v2.x, camelCase CSS variables passed to the style attribute were rendered as camelCase (original) and kebab-case (incorrect by kept for backwards compatibility).

Astro v3.0 removes the kebab-case transform, and only the original camelCase CSS variable is rendered.

---
const myValue = "red"
---
<!-- input -->
<div style={{ "--myValue": myValue }}></div>
<!-- output (before) -->
<div style="--my-value:var(--myValue);--myValue:red"></div>
<!-- output (after) -->
<div style="--myValue:red"></div>

What should I do?

If you were relying on the kebab-case transform in your styles, make sure to use the camelCase version to prevent missing styles. For example:

<style>
  div {
-   color: var(--my-value);
+   color: var(--myValue);
  }
</style>

(PR: withastro/astro#8019)

[bluwy]

Changed entrypoint export paths

In Astro v2.x, you can import internal Astro APIs from astro/internal/* and astro/runtime/server/*.

Astro v3.0 removes the two entrypoints in favour of the existing astro/runtime/* entrypoint.

What should I do?

These are entrypoints for Astro's internal API and should not affect your project, but if you do use these entrypoints, you can migrate like below:

- import 'astro/internal/index.js';
+ import 'astro/runtime/server/index.js';

- import 'astro/server/index.js';
+ import 'astro/runtime/server/index.js';

(PR: withastro/astro#8085)

[natemoo-re]

Changed Astro Island serialization approach

This PR did not make the cut, we'll be revisiting it after launch!

(PR: withastro/astro#8004)

Original Changelog

Changed Astro Island serialization approach

In Astro v2.x, Astro serialized props passed to Astro Islands as JSON embedded in an HTML attribute.
Astro v3.0 now uses a more efficient serialization library to embed serialized props as a script.

What should I do?

This update should not change any user-facing behavior, but developer-facing tools that inspect Astro Islands may need to be updated to support this new output format.

- <astro-island props="{\"value\":\"Hello world!\"}">
+ <astro-island>
+   <script async>Astro.assign(document.currentScript,{props:{value:"Hello world!"}})</script>
    <h1>Hello world!</h1>
  </astro-island>

[lilnasy]

Small stylesheets now get inlined by default

In Astro v2.x, all project stylesheets were sent as tags by default, and you could opt-in to inlining them by using the build.inlineStylesheets configuration.
Astro v3.0 defaults inlineStylesheets to "auto", which means stylesheets smaller than 4kB get included in the initial response.

What should I do?

Nothing, this change does not require any migration. To go back to the old behavior, configure inlineStylesheets to "never"

export default defineConfig({
    build: {
+       inlineStylesheets: "never"
    }
})

(PR: withastro/astro#8118)

[natemoo-re]

Changed implementation of class:list directive

In Astro v2.x, class:list used a custom implementation inspired by clsx with a few extra features like deduplication and Set support.

In Astro v3.0, class:list uses clsx directly, which does not support deduplication or Set values.

What should I do?

Replace any Set elements passed to the class:list directive with a plain Array.

 <Component class:list={[
    'a',
    'b',
-   new Set(['c', 'd'])
+   ['c', 'd'] 
  ]} />

(PR: withastro/astro#8142)

[natemoo-re]

Changed behavior of class:list directive for components

In Astro v2.x, class:list values were sent to components via Astro.props['class:list'].

In Astro v3.0, class:list values are normalized into a string before being sent to components via Astro.props['class']

What should I do?

Remove any code that expects to receive the class:list prop.

---
- import { clsx } from 'clsx';
- const { class: className, 'class:list': classList } = Astro.props;
+ const { class: className } = Astro.props;
---
<div
-  class:list={[className, classList]}
+  class={className}
/>

(PR: withastro/astro#8142)

[sarah11918]

(Sarah's placeholder entry)

Unexperimenalized: astro:assets

In Astro v2.x, astro:assets and the Image Services API was behind an experimental flag.

Astro v3.0 unflags these image services and replaces the former @astrojs/image integration, which has been completely removed and is no longer supported.

What should I do?

Read Sarah's amazing image upgrade guide cover to cover!

[bluwy]

Changed astro package entrypoint exports

In Astro v2.x, the "astro" package entrypoint exported and ran the Astro CLI directly. It is not recommended to run Astro this way in practice.

Astro v3.0 removes the CLI from the entrypoint, and exports a new set of experimental JavaScript APIs, including dev(), build(), preview(), and sync().

What should I do?

If wanted to run the Astro CLI programatically, you can use the new experimental JavaScript APIs:

import { dev, build } from "astro";

// Start the Astro dev server
const devServer = await dev();
await devServer.stop();

// Build your Astro project
await build();

(PR: withastro/astro#7979)

[bluwy]

Deprecated the markdown.drafts configuration option

In Astro v2.x, markdown.drafts is used to create draft pages that are viewable in dev, but not in prod.

Astro v3.0 deprecates this feature in favour of Content Collections and handling drafts filtering manually instead, which gives more control of the feature.

What should I do?

You should migrate to content collections and manually filter out pages with the draft: true frontmatter property instead.

(PR: withastro/astro#8099)

[bluwy]

Removed deprecated APIs

In Astro v2.x, deprecated config options, script/style attributes types, and image export from astro:content were kept for backwards compatibility.

Astro v3.0 these APIs are removed.

What should I do?

Use the new APIs for each feature instead:

• Deprecated config options: See the 0.26 migration guide
• Deprecated script/style attribute types: See the 0.26 migration guide
• Deprecated image export from astro:content - Use the image helper from schema

(PR: withastro/astro#8170)

[bluwy]

Removed pre-shiki 0.14 theme names

In Astro v2.x, a few Shiki theme names had been renamed, but the original names were kept for backwards compatibility.

Astro v3.0 removes the original names in favour of the renamed theme names.

What should I do?

If you used the affected theme names below, rename them to the newer ones:

• material-darker -> material-theme-darker
• material-default -> material-theme
• material-lighter -> material-theme-lighter
• material-ocean -> material-theme-ocean
• material-palenight -> material-theme-palenight

(PR: withastro/astro#8169)

[ematipico]

Changed how scoped style hashes

In Astro v2.x, scoped style hashes were uppercase.

Astro v3.0 generates hashes in lowercase.

Before:

- <div  class="astro-KOI4QYR5"></div>
+ <div  class="astro-koi4qyr5"></div>

What should I do?

Nothing

[sarah11918]

I am closing this (final v3.0) issue! 🥳

This is now our source of truth for breaking changes. Any corrections/updates before Wednesday can go directly to PR #4166

Deploy preview of the upgrade guide

Thanks, everyone! I loved this process and it was exceptionally helpful. Let's do this again... BUT NOT SOON. 🙌