Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[upgrade guide] remove mentions of beta #10121

Merged
merged 2 commits into from
Dec 3, 2024
Merged

[upgrade guide] remove mentions of beta #10121

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
006f5dc
remove mentions of beta
sarah11918 Nov 30, 2024
4e83982
update for unmaintained v4 link
sarah11918 Dec 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 17 additions & 96 deletions src/content/docs/en/guides/upgrade-to/v5.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Astro v5.0-beta
description: Upgrade your project to Astro v5.0-beta.
title: Upgrade to Astro v5
description: How to upgrade your project to Astro v5.0.
sidebar:
label: v5.0
i18nReady: true
Expand All @@ -10,80 +10,22 @@ 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 v4 to Astro v5-beta.
This guide will help you migrate from Astro v4 to Astro v5.

Need to upgrade an older project to v4 first? See our [older migration guide](/en/guides/upgrade-to/v4/).

:::note[5.0-beta docs in progress]
There are several new features and breaking changes that may not yet be entirely reflected throughout the rest of this site. Thank you for your patience while we prepare for Astro v5 stable!

For v4 docs, please visit the [main Astro Docs website](https://astro.build/docs).
:::

## Quick Links

The following features are **new/stable in Astro v5.0-beta**:
The following features are **new/stable in Astro v5.0**:

- The [new content collections](/en/guides/content-collections/) using the [Content Layer API](/en/reference/modules/astro-content/) and [Content Loader API](/en/reference/content-loader-reference/)
- [Server Islands](/en/guides/server-islands/)
- [Type Safe environment variables](/en/guides/environment-variables/#type-safe-environment-variables)
- [On-demand rendering available in `static` mode](/en/guides/on-demand-rendering/) (like the previous `hybrid` mode)

{/* Need to see the v4 docs? Visit this [older version of the docs site (unmaintained v3.6 snapshot)](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/). */}

## Start a new v5-beta project

Try the Astro v5-beta in a new project:

<PackageManagerTabs>
<Fragment slot="npm">
```shell
npm create astro@latest -- --ref next
```
</Fragment>
<Fragment slot="pnpm">
```shell
pnpm create astro --ref next
```
</Fragment>
<Fragment slot="yarn">
```shell
yarn create astro --ref next
```
</Fragment>
</PackageManagerTabs>


## Upgrade Astro

Update your existing project's version of Astro and all official integrations to the latest versions using your package manager.

<PackageManagerTabs>
<Fragment slot="npm">
```shell
# Upgrade Astro and official integrations together
npx @astrojs/upgrade beta
```
</Fragment>
<Fragment slot="pnpm">
```shell
# Upgrade Astro and official integrations together
pnpm dlx @astrojs/upgrade beta
```
</Fragment>
<Fragment slot="yarn">
```shell
# Upgrade Astro and official integrations together
yarn dlx @astrojs/upgrade beta
```
</Fragment>
</PackageManagerTabs>

Need to see the v4 docs? Visit this [older version of the docs site (unmaintained v4.16 snapshot)](https://docs-git-v4-docs-unmaintained-astrodotbuild.netlify.app/). **THIS LINK DOES NOT EXIST YET MAKE THIS LINK EXIST CHRIS**
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

{/* For beta version, only show upgrade command!
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.

Update your project's version of Astro to the latest beta version using your package manager:
Update your project's version of Astro to the latest version using your package manager:

<PackageManagerTabs>
<Fragment slot="npm">
Expand All @@ -107,7 +49,6 @@ Update your project's version of Astro to the latest beta version using your pac
</PackageManagerTabs>

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!
Expand All @@ -123,9 +64,11 @@ See [the Astro changelog](https://github.com/withastro/astro/blob/main/packages/

## Dependency Upgrades

Any major upgrades to Astro's dependencies may cause breaking changes in your project.

### Vite 6.0

Astro v5.0 updates to Vite v6.0 as the development server and production bundler.
Astro v5.0 upgrades to Vite v6.0 as the development server and production bundler.

#### What should I do?

Expand All @@ -152,24 +95,9 @@ import mdxRenderer from "@astrojs/mdx/server.js";

<ReadMore>Learn more about [using MDX in your project](/en/guides/integrations-guide/mdx/).</ReadMore>

{/*
// THESE ARE FOR DEPENDENCY UPGRADES

Any major upgrades to Astro's dependencies may cause breaking changes in your project.

### Upgraded: Vite 6.0

Placeholder

#### 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. There are no breaking changes to Astro itself.

*/}

## Legacy

The following features are 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.
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.

### Legacy: v2.0 Content Collections API

Expand All @@ -189,7 +117,7 @@ If you are unable to make any changes to your collections at this time, you can

##### Updating existing collections

See the instructions below for converting an existing content collection with Markdown, MDX, Markdoc, or JSON entries to use the Content Layer API.
See the instructions below for updating an existing content collection (`type: 'content'` or `type: 'data'`) to use the Content Layer API.

<details>
<summary>Step-by-step instructions to update a collection</summary>
Expand Down Expand Up @@ -218,7 +146,7 @@ See the instructions below for converting an existing content collection with Ma
});
```

3. **Change references from `slug` to `id`**. Content layer collections do not have a `slug` field. Instead, all updated collections will have an `id`. You may also need to update your file name to match an updated getStaticPaths() parameter:
3. **Change references from `slug` to `id`**. Content layer collections do not have a reserved `slug` field. Instead, all updated collections will have an `id`. You may also need to update dynamic routing file names to match a changed getStaticPaths() parameter:

```astro ins={7} del={6}
// src/pages/[id].astro
Expand All @@ -227,7 +155,7 @@ See the instructions below for converting an existing content collection with Ma
const posts = await getCollection('blog');
return posts.map((post) => ({
params: { slug: post.slug },
params: { slug: post.id },
params: { id: post.id },
props: post,
}));
}
Expand Down Expand Up @@ -255,15 +183,15 @@ See the instructions below for converting an existing content collection with Ma

<SourcePR number="11976" title="Implement legacy collections using glob" />

By default, collections that use the old types (`content` or `data`) and do not define a `loader` are now implemented under the hood using the Content Layer API's built-in `glob()` loader, with extra backward-compatibility handling.
By default, collections that use the old `type` property (`content` or `data`) and do not define a `loader` are now implemented under the hood using the Content Layer API's built-in `glob()` loader, with extra backward-compatibility handling.

Additionally, temporary backwards compatibility exists for keeping the content config file in its original location of `src/content/config.ts`.

While this backwards compatibility implementation is able to emulate most of the features of legacy collections, allowing many legacy collections to continue to work even without updating your code, **there are some differences and limitations that may cause breaking changes to existing collections**:
This backwards compatibility implementation is able to emulate most of the features of legacy collections and will allow many legacy collections to continue to work even without updating your code. However, **there are some differences and limitations that may cause breaking changes to existing collections**:

- In previous versions of Astro, collections would be generated for all folders in `src/content/`, even if they were not defined in `src/content/config.ts`. This behavior is now deprecated, and collections should always be defined in `src/content.config.ts`. For existing collections, these can just be empty declarations (e.g. `const blog = defineCollection({})`) and Astro will implicitly define your legacy collection for you in a way that is compatible with the new loading behavior.
- The special `layout` field is not supported in Markdown collection entries. This property is intended only for standalone page files located in `src/pages/` and not likely to be in your collection entries. However, if you were using this property, you must now create dynamic routes that include your page styling.
- Sort order of generated collections is non-deterministic and platform-dependent. This means that if you are calling `getCollection()`, the order in which entries are returned may be different than before. If you need a specific order, you should sort the collection entries yourself.
- Sort order of generated collections is non-deterministic and platform-dependent. This means that if you are calling `getCollection()`, the order in which entries are returned may be different than before. If you need a specific order, you must sort the collection entries yourself.
- `image().refine()` is not supported. If you need to validate the properties of an image you will need to do this at runtime in your page or component.
- the `key` argument of `getEntry(collection, key)` is typed as `string`, rather than having types for every entry.

Expand Down Expand Up @@ -538,9 +466,7 @@ export default defineConfig({

These features are all available by default in Astro v5.0.

{/* Read about these exciting features and more in [the v5.0-beta Blog post](https://astro.build/blog/astro-4/). */}

<ReadMore>See Astro's current [experimental features](/en/reference/experimental-flags/).</ReadMore>
<ReadMore>Read about these exciting features and more in [the v5.0 Blog post](https://astro.build/blog/astro-5/).</ReadMore>

## Changed Defaults

Expand Down Expand Up @@ -1247,8 +1173,3 @@ Know a good resource for Astro v5.0? [Edit this page](https://github.com/withast
## 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.


#### What should I do?

In most cases, ensuring that your locally-linked dependencies are built to JS before running the Astro project, the config loading should work as before.
Loading