diff --git a/astro.sidebar.ts b/astro.sidebar.ts index d687faf69ba66..5037ada5ba839 100644 --- a/astro.sidebar.ts +++ b/astro.sidebar.ts @@ -147,9 +147,7 @@ export const sidebar = [ 'reference/experimental-flags/live-content-collections', 'reference/experimental-flags/client-prerender', 'reference/experimental-flags/content-intellisense', - 'reference/experimental-flags/preserve-scripts-order', 'reference/experimental-flags/heading-id-compat', - 'reference/experimental-flags/static-import-meta-env', 'reference/experimental-flags/chrome-devtools-workspace', ], }), diff --git a/src/content/docs/en/getting-started.mdx b/src/content/docs/en/getting-started.mdx index fce0eb7214e70..9b70bb453fd03 100644 --- a/src/content/docs/en/getting-started.mdx +++ b/src/content/docs/en/getting-started.mdx @@ -7,7 +7,7 @@ editUrl: false next: false banner: content: | - Astro v5 is here! Learn how to upgrade your site + Astro v6 is here! Learn how to upgrade your site hero: title: Astro Docs tagline: Guides, resources, and API references to help you build with Astro. diff --git a/src/content/docs/en/guides/actions.mdx b/src/content/docs/en/guides/actions.mdx index eb96b3c67a769..0503669555788 100644 --- a/src/content/docs/en/guides/actions.mdx +++ b/src/content/docs/en/guides/actions.mdx @@ -656,7 +656,7 @@ Actions are accessible as public endpoints based on the name of the action. For To authorize action requests, add an authentication check to your action handler. You may want to use [an authentication library](/en/guides/authentication/) to handle session management and user information. -Actions expose the full `APIContext` object to access properties passed from middleware using `context.locals`. When a user is not authorized, you can raise an `ActionError` with the `UNAUTHORIZED` code: +Actions expose the `ActionAPIContext` object, a subset of `APIContext`, to access properties passed from middleware using `context.locals`. When a user is not authorized, you can raise an `ActionError` with the `UNAUTHORIZED` code: ```ts title="src/actions/index.ts" {6-8} import { defineAction, ActionError } from 'astro:actions'; diff --git a/src/content/docs/en/guides/deploy/microsoft-azure.mdx b/src/content/docs/en/guides/deploy/microsoft-azure.mdx index 57ffa6ddf0360..dfb03cdcd3785 100644 --- a/src/content/docs/en/guides/deploy/microsoft-azure.mdx +++ b/src/content/docs/en/guides/deploy/microsoft-azure.mdx @@ -38,7 +38,7 @@ The GitHub action yaml that is created for you assumes the use of node 14. This ``` "engines": { - "node": ">=18.0.0" + "node": ">=22.12.0" }, ``` diff --git a/src/content/docs/en/guides/deploy/netlify.mdx b/src/content/docs/en/guides/deploy/netlify.mdx index 449e8fd034873..795ab2bdb7d5c 100644 --- a/src/content/docs/en/guides/deploy/netlify.mdx +++ b/src/content/docs/en/guides/deploy/netlify.mdx @@ -99,7 +99,7 @@ You can also create a new site on Netlify and link up your Git repository by ins ### Set a Node.js version -If you are using a legacy [build image](https://docs.netlify.com/configure-builds/get-started/#build-image-selection) (Xenial) on Netlify, make sure that your Node.js version is set. Astro requires `v18.20.8` or `v20.3.0` or higher. +If you are using a legacy [build image](https://docs.netlify.com/configure-builds/get-started/#build-image-selection) (Xenial) on Netlify, make sure that your Node.js version is set. Astro requires `v22.12.0` or higher. You can [specify your Node.js version in Netlify](https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-and-javascript) using: - a [`.nvmrc`](https://github.com/nvm-sh/nvm#nvmrc) file in your base directory. diff --git a/src/content/docs/en/guides/endpoints.mdx b/src/content/docs/en/guides/endpoints.mdx index 3329a1bd64dad..51f9c9c65904b 100644 --- a/src/content/docs/en/guides/endpoints.mdx +++ b/src/content/docs/en/guides/endpoints.mdx @@ -47,6 +47,8 @@ import type { APIRoute } from "astro"; export const GET: APIRoute = async ({ params, request }) => {...} ``` +Note that endpoints whose URLs include a file extension (e.g. `src/pages/sitemap.xml.ts`) can only be accessed without a trailing slash (e.g. `/sitemap.xml`), regardless of your [`build.trailingSlash`](/en/reference/configuration-reference/#trailingslash) configuration. + ### `params` and Dynamic routing Endpoints support the same [dynamic routing](/en/guides/routing/#dynamic-routes) features that pages do. Name your file with a bracketed parameter name and export a [`getStaticPaths()` function](/en/reference/routing-reference/#getstaticpaths). Then, you can access the parameter using the `params` property passed to the endpoint function: diff --git a/src/content/docs/en/guides/environment-variables.mdx b/src/content/docs/en/guides/environment-variables.mdx index c5184a78b58e4..bf227065c1a31 100644 --- a/src/content/docs/en/guides/environment-variables.mdx +++ b/src/content/docs/en/guides/environment-variables.mdx @@ -58,7 +58,6 @@ Astro includes a few environment variables out of the box: - `import.meta.env.DEV`: `true` if your site is running in development; `false` otherwise. Always the opposite of `import.meta.env.PROD`. - `import.meta.env.BASE_URL`: The base URL your site is being served from. This is determined by the [`base` config option](/en/reference/configuration-reference/#base). - `import.meta.env.SITE`: This is set to [the `site` option](/en/reference/configuration-reference/#site) specified in your project's `astro.config`. -- `import.meta.env.ASSETS_PREFIX`: The prefix for Astro-generated asset links if the [`build.assetsPrefix` config option](/en/reference/configuration-reference/#buildassetsprefix) is set. This can be used to create asset links not handled by Astro. Use them like any other environment variable. diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index e210b84c37816..70b4bbdea9db8 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -170,15 +170,11 @@ Set this option when all routes will have their `/locale/` prefix in their URL a - URLs without a locale prefix, (e.g. `example.com/about/`) will return a 404 (not found) status code unless you specify a [fallback strategy](#fallback). -### `redirectToDefaultLocale` +#### Opting out of redirects for the home URL -

+Even with your default locale routes prefixed, this behaviour does not apply by default to your site's index page. This allows you to have a home page that exists outside of your configured locale structure, where all of your localized routes are prefixed except the home URL of your site. -Configures whether or not the home URL (`/`) generated by `src/pages/index.astro` will redirect to `/`. - -Setting `prefixDefaultLocale: true` will also automatically set `redirectToDefaultLocale: true` in your `routing` config object. By default, the required `src/pages/index.astro` file will automatically redirect to the index page of your default locale. - -You can opt out of this behavior by [setting `redirectToDefaultLocale: false`](/en/reference/configuration-reference/#i18nroutingredirecttodefaultlocale). This allows you to have a site home page that exists outside of your configured locale folder structure. +You can opt out of this behavior so that your main site URL will also redirect to a prefixed, localized route for your default locale. When `prefixDefaultLocale: true` is set, you can additionally configure `redirectToDefaultLocale: true`. This will ensure that the home URL (`/`) generated by `src/pages/index.astro` will redirect to `/[defaultLocale]/`. ### `manual` diff --git a/src/content/docs/en/guides/upgrade-to/v5.mdx b/src/content/docs/en/guides/upgrade-to/v5.mdx index e807eaf133de5..f66c46dba673d 100644 --- a/src/content/docs/en/guides/upgrade-to/v5.mdx +++ b/src/content/docs/en/guides/upgrade-to/v5.mdx @@ -1112,7 +1112,7 @@ function useRoute(route: IntegrationRouteData) { } ``` -See the [API reference for `IntegrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference). +See the API reference for `IntegrationRouteData`. ### Changed: `distURL` is now an array (Integrations API) @@ -1139,7 +1139,7 @@ if (route.distURL) { } ``` -See the [API reference for `IntegrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference). +See the [API reference for `IntegrationRouteData`. ### Changed: Arguments passed to `app.render()` (Adapter API) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx new file mode 100644 index 0000000000000..a4bef60b8c2d7 --- /dev/null +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -0,0 +1,594 @@ +--- +title: Upgrade to Astro v6 +description: How to upgrade your project to Astro v6.0. +sidebar: + label: v6.0 +i18nReady: true +--- +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import ReadMore from '~/components/ReadMore.astro' +import SourcePR from '~/components/SourcePR.astro' + +This guide will help you migrate from Astro v5 to Astro v6. + +Need to upgrade an older project to v5 first? See our [older migration guide](/en/guides/upgrade-to/v5/). + +Need to see the v5 docs? Visit this [older version of the docs site (unmaintained v5.xx snapshot)](https://v5.docs.astro.build/). + +## Upgrade Astro + +Update your project's version of Astro to the latest version using your package manager: + + + + ```shell + # Upgrade Astro and official integrations together + npx @astrojs/upgrade + ``` + + + ```shell + # Upgrade Astro and official integrations together + pnpm dlx @astrojs/upgrade + ``` + + + ```shell + # Upgrade Astro and official integrations together + yarn dlx @astrojs/upgrade + ``` + + + +You can also [upgrade your Astro integrations manually](/en/guides/integrations-guide/#manual-upgrading) if needed, and you may also need to upgrade other dependencies in your project. + +:::note[Need to continue?] +After upgrading Astro, you may not need to make any changes to your project at all! + +But, if you notice errors or unexpected behavior, please check below for what has changed that might need updating in your project. +::: + +Astro v6.0 includes [potentially breaking changes](#breaking-changes), as well as the removal and deprecation of some features. + +If your project doesn't work as expected after upgrading to v6.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase. + +See [the Astro changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) for full release notes. + +## Dependency Upgrades + +Any major upgrades to Astro's dependencies may cause breaking changes in your project. + +### Node 22 + + + +Node 18 reached its End of Life in March 2025 and Node 20 is scheduled to reach its End of Life in April 2026. + +Astro v6.0 drops Node 18 and Node 20 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 `22.12.0` or higher**. + + +1. Check your local version of Node using: + + ```sh + node -v + ``` + +2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 22. + + You can specify Node `22.12.0` for your Astro project either in a dashboard configuration setting or a `.nvmrc` file. + + ```bash title=".nvmrc" + 22.12.0 + ``` + + +### Vite 7.0 + + + +Astro v6.0 upgrades to Vite v7.0 as the development server and production bundler. + +#### What should I do? + +If you are using Vite-specific plugins, configuration, or APIs, check the [Vite migration guide](https://vite.dev/guide/migration) for their breaking changes and upgrade your project as needed. + +## Legacy + +The following features are now considered legacy features. They should function normally but are no longer recommended and are in maintenance mode. They will see no future improvements and documentation will not be updated. These features will eventually be deprecated, and then removed entirely. + +## Deprecated + +The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly. + +Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code. + +### Deprecated: `Astro` in `getStaticPaths()` + + + +In Astro 5.x, it was possible to access an `Astro` object inside `getStaticPaths()`. However, despite being typed the same as the `Astro` object accessible in the frontmatter, this object only had `site` and `generator` properties. This could lead to confusion about which `Astro` object properties were available inside `getStaticPaths()`. + +Astro 6.0 deprecates this object for `getStaticPaths()` to avoid confusion and improves error handling when attempting to access `Astro` values that are unavailable. Using `Astro.site` or `Astro.generator` within `getStaticPaths()` will now log a deprecation warning, and accessing any other property will throw a specific error with a helpful message. In a future major version, this object will be removed entirely, and accessing `Astro.site` or `Astro.generator` will also throw an error. + +#### What should I do? + +Update your `getStaticPaths()` function if you were attempting to access any `Astro` properties inside its scope. Remove `Astro.generator` entirely, and replace all occurrences of `Astro.site()` with `import.meta.env.SITE`: + +```astro title="src/pages/blog/[slug].astro" del={5,6} ins={7} +--- +import { getPages } from "../../../utils/data"; + +export async function getStaticPaths() { + console.log(Astro.generator); + return getPages(Astro.site); + return getPages(import.meta.env.SITE); +} +--- +``` + +Read more about [built-in environment variables such as `import.meta.env.SITE`](/en/guides/environment-variables/#default-environment-variables) that are accessible when [using `getStaticPaths()` to dynamically generate static routes](/en/guides/routing/#static-ssg-mode). + +### Deprecated: `import.meta.env.ASSETS_PREFIX` + + + +In Astro 5.x, it was possible to access `build.assetsPrefix` in your Astro config via the built-in environment variable `import.meta.env.ASSETS_PREFIX`. However, Astro v5.7.0 introduced the `astro:config` virtual model to expose a non-exhaustive, serializable, type-safe version of the Astro configuration which included access to `build.assetsPrefix` directly. This became the preferred way to access the prefix for Astro-generated asset links when set, although the environment variable still existed. + +Astro 6.0 deprecates this variable in favor of `build.assetsPrefix` from the `astro:config/server` module. + +#### What should I do? + +Replace any occurances of `import.meta.env.ASSETS_PREFIX` with the `build.assetsPrefix` import from `astro:config/server`. This is a drop-in replacement to provide the existing value, and no other changes to your code should be necessary: + +```ts del={4} ins={2,5} +import { someLogic } from "./utils" +import { build } from "astro:config/server" + +someLogic(import.meta.env.ASSETS_PREFIX) +someLogic(build.assetsPrefix) +``` + +Read more about the [`astro:config` virtual modules](/en/reference/modules/astro-config/). + +## Removed + +The following features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect. + +Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features. + +### Removed: `` component + + + +In Astro 5.0, the `` component was renamed to `` to clarify the role of the component. The new name makes it more clear that the features you get from Astro's `` routing component are slightly different from the native CSS-based MPA router. However, a deprecated version of the `` component still existed and may have functioned in Astro 5.x. + +Astro 6.0 removes the `` component entirely and it can no longer be used in your project. Update to the `` component to continue to use these features. + +#### What should I do? + +Replace all occurrences of the `ViewTransitions` import and component with `ClientRouter`: + +```astro title="src/layouts/MyLayout.astro" del={1,7} ins={2,8} +import { ViewTransitions } from 'astro:transitions'; +import { ClientRouter } from 'astro:transitions'; + + + + ... + + + + +``` + +Read more about [view transitions and client-side routing in Astro](/en/guides/view-transitions/). + +### Removed: `emitESMImage()` + + + +In Astro 5.6.2, the `emitESMImage()` function was deprecated in favor of `emitImageMetadata()`, which removes two deprecated arguments that were not meant to be exposed for public use: `_watchMode` and `experimentalSvgEnabled`. + +Astro 6.0 removes `emitESMImage()` entirely. Update to `emitImageMetadata()` to keep your current behavior. + +#### What should I do? + +Replace all occurrences of the `emitESMImage()` with `emitImageMetadata()` and remove unused arguments: + +```ts del={1,5} ins={2,6} +import { emitESMImage } from 'astro/assets/utils'; +import { emitImageMetadata } from 'astro/assets/utils'; + +const imageId = '/images/photo.jpg'; +const result = await emitESMImage(imageId, false, false); +const result = await emitImageMetadata(imageId); +``` + +Read more about [`emitImageMetadata()`](/en/reference/image-service-reference/#emitimagemetadata). + +### Removed: `Astro.glob()` + + + +In Astro 5.0, `Astro.glob()` was deprecated in favor of using `getCollection()` to query your collections, and `import.meta.glob()` to query other source files in your project. + +Astro 6.0 removes `Astro.glob()` entirely. Update to `import.meta.glob()` to keep your current behavior. + +#### What should I do? + +Replace all use of `Astro.glob()` with `import.meta.glob()`. Note that `import.meta.glob()` no longer returns a `Promise`, so you may have to update your code accordingly. You should not require any updates to your [glob patterns](/en/guides/imports/#glob-patterns). + +```astro title="src/pages/blog.astro" del={2} ins={3} +--- +const posts = await Astro.glob('./posts/*.md'); +const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true })); +--- + +{posts.map((post) =>
  • {post.frontmatter.title}
    • )} +``` + +Where appropriate, consider using [content collections](/en/guides/content-collections/) to organize your content, which has its own newer, more performant querying functions. + +You may also wish to consider using glob packages from NPM, such as [`fast-glob`](https://www.npmjs.com/package/fast-glob). + +Learn more about [importing files with `import.meta.glob`](/en/guides/imports/#importmetaglob). + +### Removed: `routes` on `astro:build:done` hook (Integration API) + + + +In Astro 5.0, accessing `routes` on the `astro:build:done` hook was deprecated. + +Astro 6.0 removes the `routes` array passed to this hook entirely. Instead, the `astro:routes:resolved` hook should be used. + +#### What should I do? + +Remove any instance of `routes` passed to `astro:build:done` and replace it with the new `astro:routes:resolved` hook. Access `distURL` on the newly exposed `assets` map: + +```js title="my-integration.mjs" ins={2,6-8,11,13-18} del={10} +const integration = () => { + let routes + return { + name: 'my-integration', + hooks: { + 'astro:routes:resolved': (params) => { + routes = params.routes + }, + 'astro:build:done': ({ + routes + assets + }) => { + for (const route of routes) { + const distURL = assets.get(route.pattern) + if (distURL) { + Object.assign(route, { distURL }) + } + } + console.log(routes) + } + } + } +} +``` + +Learn more about [the Integration API `astro:routes:resolved` hook](/en/reference/integrations-reference/#astroroutesresolved) for building integrations. + +### Removed: `entryPoints` on `astro:build:ssr` hook (Integration API) + + + +In Astro 5.0, [`functionPerRoute` was deprecated](/en/guides/upgrade-to/v5/#deprecated-functionperroute-adapter-api). That meant that `entryPoints` on the `astro:build:ssr` hook was always empty. + +Astro 6.0 removes the `entryPoints` map passed to this hook entirely. + +#### What should I do? + +Remove any instance of `entryPoints` passed to `astro:build:ssr`: + +```js title="my-integration.mjs" del={6} +const integration = () => { + return { + name: 'my-integration', + hooks: { + 'astro:build:ssr': (params) => { + someLogic(params.entryPoints) + }, + } + } +} +``` + +### Removed: old `app.render()` signature (Adapter API) + + + +In Astro 4.0, the `app.render()` signature that allowed passing `routeData` and `locals` as optional arguments was deprecated in favor of a single optional `renderOptions` argument. + +Astro 6.0 removes this signature entirely. Attempting to pass these separate arguments will now cause an error in your project. + +#### What should I do? + +Review your `app.render` calls and pass `routeData` and `locals` as properties of an object instead of as multiple independent arguments: + +```ts title="my-adapter/entrypoint.ts" del={1} ins={2} +app.render(request, routeData, locals) +app.render(request, { routeData, locals }) +``` + +Learn more about the [Adapter API](/en/reference/adapter-reference/). + +### Removed: `handleForms` prop for the `` component + + + +In Astro 4.0, the `handleForms` prop of the `` component was deprecated, as it was no longer necessary to opt in to handling `submit` events for `form` elements. This functionality has been built in by default and the property, if still included in your project, silently had no impact on form submission. + +Astro 6.0 removes this prop entirely and it now must be removed to avoid errors in your project. + +#### What should I do? + +Remove the `handleForms` property from your `` component if it exists. It has provided no additional functionality, and so removing it should not change any behavior in your project: + +```astro title="src/pages/index.astro" del="handleForms" +--- +import { ClientRouter } from "astro:transitions"; +--- + + + + + + + + +``` + +Learn more about [transitions with forms](/en/guides/view-transitions/#transitions-with-forms). + +### Removed: `prefetch()` `with` option + + + +In Astro 4.8.4, the `with` option of the programmatic `prefetch()` function was deprecated in favor of a more sensible default behavior that no longer required specifying the priority of prefetching for each page. + +Astro 6.0 removes this option entirely and it is no longer possible to configure the priority of prefetching by passing the `with` option. Attempting to do so will now cause errors. + +By default, Astro's prefetching now uses an automatic approach that will always try to use ` + +In Astro 5.5.6, the `ActionAPIContext.rewrite` method was deprecated because custom endpoints should be used instead of rewrites. + +Astro 6.0 removes the `rewrite()` method from `ActionAPIContext` entirely and it may no longer be used. + +#### What should I do? + +Review your Actions handlers and remove any call to `rewrite()`: + + +```ts title="src/actions/index.ts" del={10} +import { defineAction } from 'astro:actions'; +import { z } from 'astro:schema'; + +export const server = { + getGreeting: defineAction({ + input: z.object({ + // ... + }), + handler: async (input, context) => { + context.rewrite('/') + // ... + } + }) +} +``` + +Learn more about [rewrites](/en/guides/routing/#rewrites). + +### Experimental Flags + +The following experimental flags have been removed in Astro v6.0 and these features are available for use: + +- `thing 1` + +Additionally, the following experimental flags have been removed and **are now the default or recommended behavior in Astro v6.0**. + +- `experimental.preserveScriptOrder` (See below for breaking changes to [default ` + +``` + +Read more about [using `script`](/en/guides/client-side-scripts/) and [`style`](/en/guides/styling/) tags. + +## Breaking Changes + +The following changes are considered breaking changes in Astro v5.0. Breaking changes may or may not provide temporary backwards compatibility. If you were using these features, you may have to update your code as recommended in each entry. + +### Changed: endpoints with a file extension cannot be accessed with a trailing slash + + + +In Astro v5.0, custom endpoints whose URL ended in a file extension (e.g. `/src/pages/sitemap.xml.ts` ) could be accessed with a trailing slash (`/sitemap.xml/`) or without (`/sitemap.xml`), regardless of the value configured for `build.trailingSlash`. + +In Astro v6.0, these endpoints can only be accessed without a trailing slash. This is true regardless of your `build.trailingSlash` configuration. + +#### What should I do? + +Review your links to your custom endpoints that include a file extension in the URL and remove any trailing slashes: + +```html del={1} ins={2} title="src/pages/index.astro" +Sitemap +Sitemap +``` + +Learn more about [custom endpoints](/en/guides/endpoints/). + +### Changed: `import.meta.env` values are always inlined + + + +In Astro 5.13, the `experimental.staticImportMetaEnv` was introduced to update the behavior when accessing `import.meta.env` directly to align with [Vite's handling of environment variables](https://vite.dev/guide/env-and-mode.html#env-variables) and ensures that `import.meta.env` values are always inlined. + +In Astro 5.x, non-public environment variables were replaced by a reference to `process.env`. Additionally, Astro could also convert the value type of your environment variables used through `import.meta.env`, which could prevent access to some values such as the strings `"true"` (which was converted to a boolean value), and `"1"` (which was converted to a number). + +Astro 6 removes this experimental flag and makes this the new default behavior in Astro: `import.meta.env` values are always inlined and never coerced. + +#### What should I do? + +If you were previously using this experimental feature, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists. + +If you were relying on coercion, you may need to update your project code to apply it manually: + +```ts title="src/components/MyComponent.astro" del={1} ins={2} +const enabled: boolean = import.meta.env.ENABLED; +const enabled: boolean = import.meta.env.ENABLED === "true"; +``` + +If you were relying on the transformation into `process.env`, you may need to update your project code to apply it manually: + +```ts title="src/components/MyComponent.astro" del={1} ins={2} +const enabled: boolean = import.meta.env.DB_PASSWORD; +const enabled: boolean = process.env.DB_PASSWORD; +``` + +You may also need to update types: + +```ts title="src/env.d.ts" del={3-4} ins={5,12-16} +interface ImportMetaEnv { + readonly PUBLIC_POKEAPI: string; + readonly DB_PASSWORD: string; + readonly ENABLED: boolean; + readonly ENABLED: string; +} + +interface ImportMeta { + readonly env: ImportMetaEnv; +} + +namespace NodeJS { + interface ProcessEnv { + DB_PASSWORD: string; + } +} +``` + +If you need more control over environment variables in Astro, we recommend you use `astro:env`. + +Learn more about [environment variables](/en/guides/environment-variables/) in Astro, including `astro:env`. + +## Community Resources + +Know a good resource for Astro v5.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v6.mdx) and add a link below! + +## Known Issues + +Please check [Astro's issues on GitHub](https://github.com/withastro/astro/issues/) for any reported issues, or to file an issue yourself. diff --git a/src/content/docs/en/install-and-setup.mdx b/src/content/docs/en/install-and-setup.mdx index 9a2e4d50fbcd6..65f77ac9b9458 100644 --- a/src/content/docs/en/install-and-setup.mdx +++ b/src/content/docs/en/install-and-setup.mdx @@ -24,7 +24,7 @@ Prefer to try Astro in your browser? Visit [astro.new](https://astro.new/) to br ## Prerequisites -- **Node.js** - `v18.20.8` or `v20.3.0`, `v22.0.0` or higher. ( `v19` and `v21` are not supported.) +- **Node.js** - `v22.12.0` or higher. Odd-numbered versions like `v23` are not supported. - **Text editor** - We recommend [VS Code](https://code.visualstudio.com/) with our [Official Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). - **Terminal** - Astro is accessed through its command-line interface (CLI). diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index de3542df0e71f..6e8d70220ecb6 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -322,7 +322,7 @@ If not provided, Astro will fallback to its default behavior for fetching error **Default:** `app.match(request)`

    -Provide a value for [`integrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference) if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatch) to determine the route to render. +Provide a value for `integrationRouteData` if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatch) to determine the route to render. ```js "routeData" const routeData = app.match(request); diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 8bcdbedcee4bb..bd6c7f2b044e5 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1048,118 +1048,3 @@ Loads a session by ID. In normal use, a session is loaded automatically from the - - -### Deprecated object properties - -#### `Astro.glob()` - -:::caution[Deprecated in v5.0] -Use [Vite's `import.meta.glob`](https://vite.dev/guide/features.html#glob-import) to query project files. - -`Astro.glob('../pages/post/*.md')` can be replaced with: - -`Object.values(import.meta.glob('../pages/post/*.md', { eager: true }));` - -See the [imports guide](/en/guides/imports/#importmetaglob) for more information and usage. -::: - -`Astro.glob()` is a way to load many local files into your static site setup. - -```astro ---- -// src/components/my-component.astro -const posts = await Astro.glob('../pages/post/*.md'); // returns an array of posts that live at ./src/pages/post/*.md ---- - -
    -{posts.slice(0, 3).map((post) => ( -
    -

    {post.frontmatter.title}

    -

    {post.frontmatter.description}

    - Read more -
    -))} -
    -``` - -`.glob()` only takes one parameter: a relative URL glob of which local files you'd like to import. It’s asynchronous and returns an array of the exports from matching files. - -`.glob()` can't take variables or strings that interpolate them, as they aren't statically analyzable. (See [the imports guide](/en/guides/imports/#supported-values) for a workaround.) This is because `Astro.glob()` is a wrapper of Vite's [`import.meta.glob()`](https://vite.dev/guide/features.html#glob-import). - -:::note -You can also use `import.meta.glob()` itself in your Astro project. You may want to do this when: -- You need this feature in a file that isn't `.astro`, like an API route. `Astro.glob()` is only available in `.astro` files, while `import.meta.glob()` is available anywhere in the project. -- You don't want to load each file immediately. `import.meta.glob()` can return functions that import the file content, rather than returning the content itself. Note that this import includes all styles and scripts for any imported files. These will be bundled and added to the page whether or not a file is actually used, as this is decided by static analysis, not at runtime. -- You want access to each file's path. `import.meta.glob()` returns a map of a file's path to its content, while `Astro.glob()` returns a list of content. -- You want to pass multiple patterns; for example, you want to add a "negative pattern" that filters out certain files. `import.meta.glob()` can optionally take an array of glob strings, rather than a single string. - -Read more in the [Vite documentation](https://vite.dev/guide/features.html#glob-import). -::: - -##### Markdown Files - -Markdown files loaded with `Astro.glob()` return the following `MarkdownInstance` interface: - -```ts -export interface MarkdownInstance> { - /* Any data specified in this file's YAML/TOML frontmatter */ - frontmatter: T; - /* The absolute file path of this file */ - file: string; - /* The rendered path of this file */ - url: string | undefined; - /* Astro Component that renders the contents of this file */ - Content: AstroComponentFactory; - /** (Markdown only) Raw Markdown file content, excluding layout HTML and YAML/TOML frontmatter */ - rawContent(): string; - /** (Markdown only) Markdown file compiled to HTML, excluding layout HTML */ - compiledContent(): string; - /* Function that returns an array of the h1...h6 elements in this file */ - getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>; - default: AstroComponentFactory; -} -``` - -You can optionally provide a type for the `frontmatter` variable using a TypeScript generic. - -```astro ---- -interface Frontmatter { - title: string; - description?: string; -} -const posts = await Astro.glob('../pages/post/*.md'); ---- - -
      - {posts.map(post =>
    • {post.frontmatter.title}
      • )} -
    -``` - -##### Astro Files - -Astro files have the following interface: - -```ts -export interface AstroInstance { - /* The file path of this file */ - file: string; - /* The URL for this file (if it is in the pages directory) */ - url: string | undefined; - default: AstroComponentFactory; -} -``` - -##### Other Files - -Other files may have various different interfaces, but `Astro.glob()` accepts a TypeScript generic if you know exactly what an unrecognized file type contains. - -```ts ---- -interface CustomDataFile { - default: Record; -} -const data = await Astro.glob('../data/**/*.js'); ---- -``` diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx index a907cadcc1a6f..c220bafec5b62 100644 --- a/src/content/docs/en/reference/configuration-reference.mdx +++ b/src/content/docs/en/reference/configuration-reference.mdx @@ -1549,14 +1549,14 @@ export default defineConfig({

    **Type:** `boolean`
    -**Default:** `true`
    +**Default:** `false`

    Configures whether or not the home URL (`/`) generated by `src/pages/index.astro` will redirect to `/[defaultLocale]` when `prefixDefaultLocale: true` is set. -Set `redirectToDefaultLocale: false` to disable this automatic redirection at the root of your site: +Set `redirectToDefaultLocale: true` to enable this automatic redirection at the root of your site: ```js // astro.config.mjs export default defineConfig({ @@ -1565,7 +1565,7 @@ export default defineConfig({ locales: ["en", "fr"], routing: { prefixDefaultLocale: true, - redirectToDefaultLocale: false + redirectToDefaultLocale: true } } }) diff --git a/src/content/docs/en/reference/errors/astro-glob-no-match.mdx b/src/content/docs/en/reference/errors/astro-glob-no-match.mdx index 0e440b87c3717..e0f6b9d83d6b6 100644 --- a/src/content/docs/en/reference/errors/astro-glob-no-match.mdx +++ b/src/content/docs/en/reference/errors/astro-glob-no-match.mdx @@ -17,8 +17,3 @@ import DontEditWarning from '~/components/DontEditWarning.astro' ## What went wrong? `Astro.glob()` did not return any matching files. There might be a typo in the glob pattern. - -**See Also:** -- [Astro.glob](/en/reference/api-reference/#astroglob) - - diff --git a/src/content/docs/en/reference/errors/astro-glob-used-outside.mdx b/src/content/docs/en/reference/errors/astro-glob-used-outside.mdx index 0046b3892b504..f3473054c151f 100644 --- a/src/content/docs/en/reference/errors/astro-glob-used-outside.mdx +++ b/src/content/docs/en/reference/errors/astro-glob-used-outside.mdx @@ -17,8 +17,3 @@ import DontEditWarning from '~/components/DontEditWarning.astro' ## What went wrong? `Astro.glob()` can only be used in `.astro` files. You can use [`import.meta.glob()`](https://vite.dev/guide/features.html#glob-import) instead to achieve the same result. - -**See Also:** -- [Astro.glob](/en/reference/api-reference/#astroglob) - - diff --git a/src/content/docs/en/reference/experimental-flags/preserve-scripts-order.mdx b/src/content/docs/en/reference/experimental-flags/preserve-scripts-order.mdx deleted file mode 100644 index 429fb416c60d5..0000000000000 --- a/src/content/docs/en/reference/experimental-flags/preserve-scripts-order.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Experimental preserve scripts order -sidebar: - label: Preserve scripts order -i18nReady: true ---- - -import Since from '~/components/Since.astro' - -

    - - **Type:** `boolean`
    - **Default:** `false`
    - -

    - -Renders multiple ` - - - -``` - -After compiling, Astro's default behavior will create an inline style where `yellow` appears first, and then `red`. This means the `red` background is applied. Similarly with the two scripts, the word `world!` is logged first, and then `hello` second: - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -When `experimental.preserveScriptOrder` is set to `true`, the rendering order of ` - - - -``` - -Después de la compilación, el comportamiento predeterminado de Astro creará un estilo en línea donde `yellow` aparece primero, y luego `red`. Esto significa que se aplica el fondo `red`. De manera similar con los dos scripts, la palabra `world!` se registra primero, y luego `hello` en segundo lugar: - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -Cuando `experimental.preserveScriptOrder` se establece en `true`, el orden de renderizado de las etiquetas ` - - - -``` - -Après la compilation, le comportement par défaut d'Astro crée un style en ligne où `yellow` apparaît en premier, puis `red`. Cela signifie que l'arrière-plan `red` est appliqué. De même, avec les deux scripts, le mot `world!` est affiché en premier, suivi de `hello` : - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -Lorsque `experimental.preserveScriptOrder` est définie sur `true`, l'ordre de restitution des balises ` - - - -``` - -컴파일 후 Astro의 기본 동작은 `yellow`가 먼저 나타나고 `red`가 다음에 나타나는 인라인 스타일을 생성합니다. 이는 `red` 배경이 적용됨을 의미합니다. 두 스크립트의 경우 `world!`가 먼저 기록되고 `hello`가 다음에 기록됩니다. - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -`experimental.preserveScriptOrder`가 `true`로 설정되면 ` - - - -``` - -在编译后，Astro 的默认行为会创建一个内联样式，其中 `yellow` 首先出现，然后是 `red`。这意味着最终应用的是 `red` 背景。类似地，对于两个脚本，会先打印 `world!`，然后是 `hello`： - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -当 `experimental.preserveScriptOrder` 设置为 `true` 时，`