Upgrade to Astro v3

本頁內容尚未翻譯。

This guide will help you migrate from Astro v2 to Astro v3.

Need to upgrade an older project to v2? See our older migration guide.

Upgrade Astro

Update your project’s version of Astro to the latest version using your package manager. If you’re using Astro integrations, please also update those to the latest version.

# Upgrade to Astro v3.x
npm install astro@latest

# Example: upgrade React and Tailwind integrations
npm install @astrojs/react@latest @astrojs/tailwind@latest

# Upgrade to Astro v3.x
pnpm add astro@latest

# Example: upgrade React and Tailwind integrations
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

# Upgrade to Astro v3.x
yarn add astro@latest

# Example: upgrade React and Tailwind integrations
yarn add @astrojs/react@latest @astrojs/tailwind@latest

Astro v3.0 Experimental Flags Removed

Remove the following experimental flags from astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true,
    viewTransitions: true,
  },
})

These features are now available by default:

View Transitions for animated page transitions and persistent islands. See view transitions API breaking changes and upgrading advice if you were using this experimental flag.
A new image services API astro:assets for using images in Astro, including a new <Image /> component and getImage() function. Please read the detailed image upgrade advice whether or not you were using this experimental flag to see how this might affect your project.

Read more about these two exciting features and more in the 3.0 Blog post!

Astro v3.0 Breaking Changes

Astro v3.0 includes some breaking changes, as well as the removal of some previously deprecated features. If your project doesn’t work as expected after upgrading to v3.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase.

See the changelog for full release notes.

Removed: Support for Node 16

Node 16 is scheduled to reach its End of Life in September 2023.

Astro v3.0 drops Node 16 support entirely so that all Astro users can take advantage of Node’s more modern features.

What should I do?

Check that both your development environment and your deployment environment are using Node 18.14.1 or higher.

Check your local version of Node using:
Terminal window
```
node -v
```
Check your deployment environment’s own documentation to verify that they support Node 18.

You can specify Node 18.14.1 for your Astro project either in a dashboard configuration setting or a .nvmrc file.
.nvmrc
```
18.14.1
```

Removed: Support for TypeScript 4

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. Astro now assumes that you use TypeScript 5.0 (March 2023), or that your editor includes it (e.g. VS Code 1.77).

What should I do?

If you have installed TypeScript locally, update to at least v5.0.

npm install typescript@latest --save-dev

Removed: `@astrojs/image`

In Astro v2.x, Astro offered an official image integration that included Astro <Image /> and <Picture /> components.

Astro v3.0 removes this integration from the codebase entirely. Astro’s new solution for images is a built-in image services API: astro:assets.

What should I do?

Remove the @astrojs/image integration from your project. You will need to not only uninstall the integration but also update or remove any import statements and existing <Image /> and <Picture /> components. You might also need to configure a preferred default image processing service.

You will find complete, step-by-step instructions for removing the old image integration in our Images guide.

Migrating to astro:assets will also bring some new image options and features that you may now wish to use. Please see the full v3.0 Image Upgrade Advice for full details!

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

export default defineConfig({
  integrations: [
    image(),
  ]
})

Removed: `<Markdown />` component

In Astro v1.x, Astro deprecated the <Markdown /> component and moved it to an external package.

Astro v3.0 completely removes the package @astrojs/markdown-component. Astro’s <Markdown /> component will no longer work in your project.

What should I do?

Remove all instances of the @astrojs/markdown-component.

---
import Markdown from '@astrojs/markdown-component';
---

To continue using a similar <Markdown /> component in your code, consider using community integrations such as astro-remote. Be sure to update your <Markdown /> component imports and attributes as necessary, according to the integration’s own documentation.

Otherwise, delete all references to importing Astro’s <Markdown /> component and the component itself in your .astro files. You will need to rewrite your content as HTML directly or import Markdown from a .md file.

Removed: deprecated 1.x APIs

In Astro v1.x, Astro deprecated our original configuration settings as well as <style global> and <script hoist> support. However, these were still supported for backwards compatibility.

Astro v3.0 removes these deprecated APIs entirely. The officially supported configuration settings and modern <style is:global> and <script> syntax should be used instead.

What should I do?

If you are continuing to use v1.x APIs, 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

Removed: Partial shims for Web APIs in server code

In Astro v2.x, Astro provided partial shims for Web APIs such as document or localStorage in server-rendered code. These shims were often incomplete and unreliable.

Astro v3.0 removes these partial shims entirely. Web APIs are no longer available in server-rendered code.

What should I do?

If you are using Web APIs in server-rendered components, you will need to either make the usage of those APIs conditional or use the client:only client directive.

Removed: `image` from `astro:content` in content collections schema

In Astro v2.x, the content collections API deprecated an image export from astro:content for use in your content collections schemas.

Astro v3.0 removes this export entirely.

What should I do?

If you are using the deprecated image() from astro:content, remove it as this no longer exists. Validate images through the image helper from schema instead:

import { defineCollection, z, image } from "astro:content";
import { defineCollection, z } from "astro:content";

defineCollection({
  schema: ({ image }) =>
    z.object({
      image: image(),
   }),
});

Removed: pre-0.14 Shiki theme names

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

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

What should I do?

If your project uses any of the themes below, rename them to their updated name:

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

Removed: `class:list` features

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

Astro v3.0 now uses clsx directly for class:list, 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']
]} />

Removed: passing `class:list` as a prop

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

Astro v3.0 normalizes class:list values 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:list={[className]}
/>

Removed: kebab-case transform for camelCase CSS variables

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

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

---
const myValue = "red"
---
<!-- input -->
<div style={{ "--myValue": myValue }}></div>

<!-- output (Astro 2.x) -->
<div style="--my-value:var(--myValue);--myValue:red"></div>
<!-- output (Astro 3.0) -->
<div style="--myValue:red"></div>

What should I do?

If you were relying on Astro to transform kebab-case in your styles, update your existing styles to camelCase to prevent missing styles. For example:

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

Removed: automatic flattening of `getStaticPaths()`’s return value

In Astro v2.x, the return value of getStaticPaths() was automatically flattened to allow you to return an array of arrays without errors.

Astro v3.0 removes automatic flattening of getStaticPaths()’s result.

What should I do?

If you’re returning an array of arrays instead of an array of objects (as is expected), .flatMap and .flat should now be used to ensure that you are returning a flat array.

An error message indicating that getStaticPath()’s return value must be an array of objects will be provided if you need to update your code.

Moved: `astro check` now requires an external package

In Astro v2.x, astro check was included in Astro by default, and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used astro check. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use.

Astro v3.0 moves the astro check command out of Astro core and now requires an external package @astrojs/check. Additionally, you must install typescript in your project to use the astro check command.

What should I do?

Run the astro check command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install @astrojs/check and typescript into your project.

Deprecated: `build.excludeMiddleware` and `build.split`

In Astro v2.x, build.excludeMiddleware and build.split were used to change how specific files were emitted when using an adapter in SSR mode.

Astro v3.0 replaces these build config options with new SSR adapter configuration options to perform the same tasks: edgeMiddleware and functionPerRoute.

What should I do?

Update the Astro config file to now use the new options in the adapter configuration directly.

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 netlify from "@astrojs/netlify/functions";

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

Deprecated: `markdown.drafts`

In Astro v2.x, the markdown.drafts configuration allowed you to have draft pages that were available in when running the dev server, but not built in production.

Astro v3.0 deprecates this feature in favor of the content collections method of handling draft pages by filtering manually instead, which gives more control over the feature.

What should I do?

To continue to mark some pages in your project as drafts, migrate to content collections and manually filter out pages with the draft: true frontmatter property instead.

Deprecated: returning simple object in endpoints

In Astro v2.x, endpoints could return a simple object, which would be converted to a JSON response.

Astro v3.0 deprecates this behavior in favor of returning a Response object directly.

What should I do?

Update your endpoints to return a Response object directly.

export async function GET() {
  return { body: { "title": "Bob's blog" }};
  return new Response(JSON.stringify({ "title": "Bob's blog" }));
}

If you really need to keep the previous format, you can use the ResponseWithEncoding object but will be deprecated in the future.

export async function GET() {
  return { body: { "title": "Bob's blog" } };
  return new ResponseWithEncoding({ body: { "title": "Bob's blog" }});
}

Changed default: `verbatimModuleSyntax` in tsconfig.json presets

In Astro v2.x, the verbatimModuleSyntax setting was off by default, with its TypeScript 4.x equivalent importsNotUsedAsValues being enabled in the strict preset.

In Astro v3.0, verbatimModuleSyntax is enabled in every preset.

What should I do?

This option requires that types are imported using the import type syntax.

---
import { type CollectionEntry, getEntry } from "astro:content";
---

While we recommend keeping it on and properly making your type imports with type (as shown above), you can disable it by setting verbatimModuleSyntax: false in your tsconfig.json file if it causes any issues.

{
  "compilerOptions": {
    "verbatimModuleSyntax": false
  }
}

Changed default: port `3000`

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 existing references to localhost:3000, for example in tests or in your README, to reflect the new port localhost:4321.

Changed default: import.meta.env.BASE_URL `trailingSlash`

In Astro v2.x, import.meta.env.BASE_URL appended your base setting with a trailingSlash by default. trailingSlash: "ignore" also appended a trailing slash.

Astro v3.0 no longer appends import.meta.env.BASE_URL with a trailing slash by default, nor 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 if you wish to preserve the previous default (or trailingSlash: "ignore") behavior:

import { defineConfig } from "astro/config";

export default defineConfig({
  base: 'my-base',
  base: 'my-base/',
});

Changed default: `compressHTML`

In Astro v2.x, Astro only compressed your emitted HTML when compressHTML was explicitly set to true. The default value was false.

Astro v3.0 now compresses emitted HTML by default.

What should I do?

You can now remove compressHTML: true from your configuration as this is the new default behavior.

import { defineConfig } from "astro/config";

export default defineConfig({
  compressHTML: true
})

You must now set compressHTML: false to opt out of HTML compression.

Changed default: `scopedStyleStrategy`

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

Astro v3.0 introduces a new, default value: "attribute". By default, styles are now applied using data-* attributes.

What should I do?

To retain your project’s current style scoping, update the configuration file to the previous default value:

import { defineConfig } from "astro/config";

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

Changed default: `inlineStyleSheets`

In Astro v2.x, all project stylesheets were sent as link tags by default. You could opt in to inlining them into <style> tags every time with "always", or to inlining only stylesheets below a certain size with "auto" by setting the build.inlineStylesheets configuration. The default setting was "never".

Astro v3.0 changes the default value of inlineStylesheets to "auto". Stylesheets smaller than ViteConfig.build.assetsInlineLimit (default: 4kb) are inlined by default. Otherwise, project styles are sent in external stylesheets.

What should I do?

If you want to keep your project’s current behavior, set build.inlineStylesheets to the previous default, "never":

import { defineConfig } from "astro/config";

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

Changed default: image service

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

Astro v3.0 now includes Sharp as the default image processing service and instead provides a configuration option to use Squoosh.

What should I do?

If you would prefer to continue to use Squoosh to transform your images, update your config with the following:

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

export default defineConfig({
  image: {
    service: squooshImageService(),
  }
})

Changed: HTTP request methods case

In Astro v2.x, HTTP request methods were written using lowercase function names: get, post, put, all, and del.

Astro v3.0 uses uppercase function names, including DELETE instead of del.

What should I do?

Rename all functions to their uppercase equivalent:

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

export function get() {
export function GET() {
    return new Response(JSON.stringify({ "title": "Bob's blog" }));
}

Changed: Multiple JSX framework configuration

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

Astro v3.0 now requires you to specify which framework to use for your files with new include and exclude integration config options when you have multiple JSX framework integrations installed. This allows Astro to better support single-framework usage, as well as advanced features like React Fast Refresh.

What should I do?

If you are using multiple JSX frameworks in the same project, set include (and optionally exclude) to an array of files and/or folders. Wildcards may be used to include multiple file paths.

We recommend placing common framework components in the same folder (e.g. /components/react/ and /components/solid/) to make specifying your includes easier, but this is not required:

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.
  // No `include` is needed if you are only using a single framework!
  integrations: [
    preact({
      include: ['**/preact/*']
    }),
    react({
      include: ['**/react/*']
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ]
});

Changed: `Astro.cookies.get(key)` can return `undefined`

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

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

What should I do?

This change will not break any code that checks for the existence of the Astro.cookie object before using Astro.cookies.get(key), but is now no longer required.

You can safely remove any code that uses has() to check if the value of Astro.cookies is undefined:

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

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

Changed: running the Astro CLI programmatically

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?

To run the Astro CLI programmatically, 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();

Changed: internal Astro API entry point export paths

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

Astro v3.0 removes the two entry points in favor of the existing astro/runtime/* entrypoint. Additionally, a new astro/compiler-runtime export has been added for compiler-specific runtime code.

What should I do?

These are entry points for Astro’s internal API and should not affect your project. But if you do use these entrypoints, update as shown below:

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

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

import { transform } from '@astrojs/compiler';

const result = await transform(source, {
  internalURL: 'astro/runtime/server/index.js',
  internalURL: 'astro/compiler-runtime',
  // ...
});

Community Resources

Know a good resource for Astro v3.0? Edit this page and add a link below!

Known Issues

There are currently no known issues.

Upgrade to Astro v3

Upgrade Astro

Astro v3.0 Experimental Flags Removed

Astro v3.0 Breaking Changes

Removed: Support for Node 16

What should I do?

Removed: Support for TypeScript 4

What should I do?

Removed: @astrojs/image

What should I do?

Removed: <Markdown /> component

What should I do?

Removed: deprecated 1.x APIs

What should I do?

Removed: Partial shims for Web APIs in server code

What should I do?

Removed: image from astro:content in content collections schema

What should I do?

Removed: pre-0.14 Shiki theme names

What should I do?

Removed: class:list features

What should I do?

Removed: passing class:list as a prop

What should I do?

Removed: kebab-case transform for camelCase CSS variables

What should I do?

Removed: automatic flattening of getStaticPaths()’s return value

What should I do?

Moved: astro check now requires an external package

What should I do?

Deprecated: build.excludeMiddleware and build.split

What should I do?

Deprecated: markdown.drafts

What should I do?

Deprecated: returning simple object in endpoints

What should I do?

Changed default: verbatimModuleSyntax in tsconfig.json presets

What should I do?

Changed default: port 3000

What should I do?

Changed default: import.meta.env.BASE_URL trailingSlash

What should I do?

Changed default: compressHTML

What should I do?

Changed default: scopedStyleStrategy

What should I do?

Changed default: inlineStyleSheets

What should I do?

Changed default: image service

What should I do?

Changed: HTTP request methods case

What should I do?

Changed: Multiple JSX framework configuration

What should I do?

Changed: Astro.cookies.get(key) can return undefined

What should I do?

Changed: running the Astro CLI programmatically

What should I do?

Changed: internal Astro API entry point export paths

What should I do?

Community Resources

Known Issues

Removed: `@astrojs/image`

Removed: `<Markdown />` component

Removed: `image` from `astro:content` in content collections schema

Removed: `class:list` features

Removed: passing `class:list` as a prop

Removed: automatic flattening of `getStaticPaths()`’s return value

Moved: `astro check` now requires an external package

Deprecated: `build.excludeMiddleware` and `build.split`

Deprecated: `markdown.drafts`

Changed default: `verbatimModuleSyntax` in tsconfig.json presets

Changed default: port `3000`

Changed default: import.meta.env.BASE_URL `trailingSlash`

Changed default: `compressHTML`

Changed default: `scopedStyleStrategy`

Changed default: `inlineStyleSheets`

Changed: `Astro.cookies.get(key)` can return `undefined`