Skip to content

Commit e7b6f56

Browse files
sarah11918sarah11918
authored
Merge branch 'v3-upgrade-guide' into feat/astro-features-plt-722
2 parents cab589c + 0f62bd2 commit e7b6f56

14 files changed

Lines changed: 451 additions & 454 deletions

File tree

‎src/content/docs/en/guides/assets.mdx‎

Lines changed: 0 additions & 404 deletions
This file was deleted.

‎src/content/docs/en/guides/middleware.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ You can import and use the utility function `defineMiddleware()` to take advanta
4545

4646
```ts
4747
// src/middleware.ts
48-
import { defineMiddleware } from "astro/middleware";
48+
import { defineMiddleware } from "astro:middleware";
4949

5050
// `context` and `next` are automatically typed
5151
export const onRequest = defineMiddleware((context, next) => {
@@ -137,7 +137,7 @@ export const onRequest = async (context, next) => {
137137
Multiple middlewares can be joined in a specified order using [`sequence()`](#sequence):
138138

139139
```js title="src/middleware.js"
140-
import { sequence } from "astro/middleware";
140+
import { sequence } from "astro:middleware";
141141

142142
async function validation(_, next) {
143143
console.log("validation request");
@@ -218,4 +218,4 @@ This function can be used by integrations/adapters to programmatically execute t
218218

219219
### `trySerializeLocals`
220220

221-
A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error.
221+
A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error.

‎src/content/docs/en/guides/styling.mdx‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -531,24 +531,36 @@ If you are using Tailwind, the [typography plugin](https://tailwindcss.com/docs/
531531

532532
### Bundle control
533533

534-
When Astro builds your site for production deployment it combines your CSS into chunks. Each page on your site is its own chunk, and additionally, CSS that is shared between multiple pages is further split off into their own chunks for reuse.
534+
When Astro builds your site for production deployment, it minifies and combines your CSS into chunks. Each page on your site gets its own chunk, and additionally, CSS that is shared between multiple pages is further split off into their own chunks for reuse.
535535

536-
In each of your HTML files there will be `<link rel="stylesheet">` tags added, one for each of the chunks that the pages needs.
536+
However, when you have several pages sharing styles, some shared chunks can become really small. If all of them were sent separately, it would lead to many stylesheets requests and affect site performance. Therefore, by default Astro will link only those in your HTML above 4kB in size as `<link rel="stylesheet">` tags, while inlining smaller ones into `<style type="text/css">`. This approach provides a balance between the number of additional requests and the volume of CSS that can be cached between pages.
537537

538-
Sites with a large number of pages and many different shared styles can lead to many stylesheet requests and affect site performance. You can configure the `inlineStylesheets` option to reduce the number of these requests by putting (minimized) stylesheets into a `<style>` tag rather than request them externally.
538+
You can configure the size at which stylesheets will be linked externally (in bytes) using the `assetsInlineLimit` vite build option. Note that this option affects script and image inlining as well.
539+
540+
```js
541+
import { defineConfig } from 'astro/config';
542+
543+
export default defineConfig({
544+
vite: {
545+
build: {
546+
assetsInlineLimit: 1024,
547+
}
548+
};
549+
});
550+
```
551+
552+
If you would rather all project styles remain external, you can configure the `inlineStylesheets` build option.
539553

540554
```js
541555
import { defineConfig } from 'astro/config';
542556

543557
export default defineConfig({
544558
build: {
545-
inlineStylesheets: 'auto'
559+
inlineStylesheets: 'never'
546560
}
547561
});
548562
```
549563

550-
The `'auto'` option will inline only the stylesheets that are below the `vite.build.assetsInlineLimit` threshold, reducing the number of requests for smaller sheets. Larger stylesheets, such as global ones used by all pages, will still be fetched externally and cached. This option provides a balance between the number of stylesheets loaded and the styles that can be cached between pages.
551-
552564
You can also set this option to `'always'` which will inline all stylesheets.
553565

554566
## Advanced

‎src/content/docs/en/guides/troubleshooting.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,7 @@ To help you debug your Astro components, Astro provides a built-in [`<Debug />`]
198198

199199
```astro {2,7}
200200
---
201-
import { Debug } from 'astro/components';
201+
import { Debug } from 'astro:components';
202202
const sum = (a, b) => a + b;
203203
---
204204
@@ -210,7 +210,7 @@ The Debug component supports a variety of syntax options for even more flexible
210210

211211
```astro {2,7-9}
212212
---
213-
import { Debug } from 'astro/components';
213+
import { Debug } from 'astro:components';
214214
const sum = (a, b) => a + b;
215215
const answer = sum(2, 4);
216216
---

‎src/content/docs/en/guides/upgrade-to/v3.mdx‎

Lines changed: 243 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,31 @@ Update your project's version of Astro to the latest version using your package
4545
</Fragment>
4646
</PackageManagerTabs>
4747

48+
## Astro v3.0 Experimental Flags Removed
49+
50+
Remove the following experimental flags from `astro.config.mjs`:
51+
52+
```js del={5-8}
53+
// astro.config.mjs
54+
import { defineConfig } from 'astro/config';
55+
56+
export default defineConfig({
57+
experimental: {
58+
assets: true,
59+
viewTransitions: true,
60+
},
61+
})
62+
```
63+
64+
These features are now available by default:
65+
66+
- [View Transitions](/en/guides/view-transitions/) for animated page transitions and persistent islands.
67+
- [A new image services API `astro:assets`](/en/guides/images/) for optimizing and transforming images through the new `<Image />` component and `getImage()` function. Also unlocks [relative images in Markdown, MDX and Markdoc](/en/guides/images/#update-your-markdown-mdx-and-markdoc-files) using standard `![]()` syntax.
68+
69+
Read more about these two exciting features and more in the 3.0 Blog post!
70+
71+
72+
4873
## Astro v3.0 Breaking Changes
4974

5075
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.
@@ -74,13 +99,27 @@ Astro v3.0 drops Node 16 support entirely, so that all Astro users can take adva
7499

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

77-
### Reserved: `src/assets/`
102+
### Removed: `@astrojs/image`
103+
In Astro v2.x, this package existed
104+
105+
Astro v3.0, it does not anymore, replaced by `astro:assets`
106+
107+
#### What should I do?
108+
109+
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.
110+
111+
Please see the full [v3 Image Upgrade Guide](/en/guides/images/#upgrade-to-v30-from-v2x) for details!
78112

79-
Astro v3.0 now includes the new image services API for optimizing your image assets. This API reserves `src/assets/` as a special folder, with a built-in import alias: `~/assets` for referencing assets located here.
113+
114+
### Removed: `<Markdown />` component
115+
116+
In Astro v2.x, Astro deprecated the `<Markdown />` component and moved it to an external package.
117+
118+
Astro v3.0 comletely removes the package `@astrojs/markdown-component`, so Astro's `<Markdown />` component will no longer work in your project.
80119

81120
#### What should I do?
82121

83-
No change is required, and there will be no conflicts with an existing `src/assets/` folder. However, you will now have access to the built-in import alias and can choose to rename your asset imports within your files. This folder is not required, and your assets may continued to be located anywhere.
122+
Uninstall the `@astrojs/markdown-component` package. To continue using a similar `<Markdown />` component in your code, consider using [community integrations](https://astro.build/integrations/) that provide a similar component like https://github.com/natemoo-re/astro-remote, and be sure to update your 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](/en/guides/markdown-content/#importing-markdown) from an `.md` file.
84123

85124
### Changed: automatic flattening of `getStaticPaths()`'s return value
86125

@@ -321,25 +360,142 @@ Astro V3 still displays the error log, but now you can build the project.
321360
When using an adapter that supports neither Squoosh or Sharp, Astro will now automatically use an image service that does not support processing, but still provides the other benefits of `astro:assets` such as enforcing `alt`, no CLS etc to users. Should be noted that it does no transformations or processing, but you still get all the other benefits (no CLS, alt enforced, etc). All of those benefits are part of the image service, if you make your own, you lose those benefits unless you make it yourself
322361
323362
324-
### Removed: `<Markdown />` component
363+
### Removed: camelCase transformations
325364
326-
In Astro v2.x, Astro deprecated the `<Markdown />` component and moved it to an external package.
365+
In Astro 2.x, Astro automatically transformed camelCase CSS variable names passed to the `style` attribute of an HTML element.
327366
328-
Astro v3.0 comletely removes the package `@astrojs/markdown-component`, so Astro's `<Markdown />` component will no longer work in your project.
367+
Astro 3.0 removes backwards-compatible kebab-case transform for these camelCase CSS variable names.
329368
330369
#### What should I do?
331370
332-
Uninstall the `@astrojs/markdown-component` package. To continue using a similar `<Markdown />` component in your code, consider using [community integrations](https://astro.build/integrations/) that provide a similar component like https://github.com/natemoo-re/astro-remote, and be sure to update your 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](/en/guides/markdown-content/#importing-markdown) from an `.md` file.
371+
If you were relying on Astro to transform kebab-case in your styles, update your existing styles to use the camelCase version to prevent missing styles. For example:
333372
334-
### Removed: camelCase transformations
373+
```astro
374+
---
375+
const myValue = "red"
376+
---
377+
<!-- input -->
378+
<div style={{ "--myValue": myValue }}></div>
379+
<!-- output (before) -->
380+
<div style="--my-value:var(--myValue);--myValue:red"></div>
381+
<!-- output (after) -->
382+
<div style="--myValue:red"></div>
383+
```
335384
336-
In Astro 2.x, Astro automatically transformed camelCase CSS variable names passed to the `style` attribute of an HTML element.
385+
```diff
386+
<style>
387+
div {
388+
- color: var(--my-value);
389+
+ color: var(--myValue);
390+
}
391+
</style>
392+
```
337393
338-
Astro 3.0 removes backwards-compatible kebab-case transform for these camelCase CSS variable names.
394+
### Changed: default `scopedStyleStrategy`
395+
396+
In Astro v2.x, the default value of `scopedStyleStrategy` was `"where"`.
397+
398+
Astro v3.0, the default value is `"attribute"`. By default, styles are now applied using `data-*` attributes.
339399
340400
#### What should I do?
341401
342-
If you were relying on Astro to transform kebab-case in your styles, update your existing styles to use the camelCase version to prevent missing styles. For example:
402+
To retain your project's current style scoping, update the configuration file to the previous default value:
403+
404+
```diff
405+
export default defineConfig({
406+
+ scopedStyleStrategy: "where"
407+
})
408+
```
409+
410+
### Changed: import.meta.env.BASE_URL default `trailingSlash` behaviour
411+
412+
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.
413+
414+
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.
415+
416+
#### What should I do?
417+
418+
If your `base` already has a trailing slash, no change is needed.
419+
420+
If your `base` does not have a trailing slash, add one to preserve the previous behaviour:
421+
422+
```diff
423+
// astro.config.mjs
424+
- base: 'my-base',
425+
+ base: 'my-base/',
426+
```
427+
428+
### Changed: Multiple JSX framework configuration
429+
430+
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 automatically scanned your components to determine which framework-specific transformations should be used, but at a performance cost.
431+
432+
Astro v3.0 determines which framework to use with `include` and `exclude` integration config options where you can specify files and folders on a per-framework basis. This allows Astro to better support single-framework usage, as well as advanced features like Fast Refresh.
433+
434+
#### What should I do?
435+
436+
If you are using multiple JSX frameworks in the same project, use the `include` and/or `exclude` configuration options to specify which files belong to which framework. Provide an array of files and/or folders. Wildcards may be used to include multiple file paths.
437+
438+
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:
439+
440+
```js
441+
import { defineConfig } from 'astro/config';
442+
import preact from '@astrojs/preact';
443+
import react from '@astrojs/react';
444+
import svelte from '@astrojs/svelte';
445+
import vue from '@astrojs/vue';
446+
import solid from '@astrojs/solid-js';
447+
448+
export default defineConfig({
449+
// Enable many frameworks to support all different kinds of components.
450+
// No `include` is needed if you are only using a single framework!
451+
integrations: [
452+
preact({
453+
include: ['**/preact/*']
454+
}),
455+
react({
456+
include: ['**/react/*']
457+
}),
458+
solid({
459+
include: ['**/solid/*'],
460+
}),
461+
]
462+
});
463+
```
464+
465+
466+
### Removed: kebab-case transform for camelCase CSS variables
467+
468+
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).
469+
470+
Astro v3.0 removes the kebab-case transform, and only the original camelCase CSS variable is rendered.
471+
472+
```astro
473+
---
474+
const myValue = "red"
475+
---
476+
<!-- input -->
477+
<div style={{ "--myValue": myValue }}></div>
478+
<!-- output (before) -->
479+
<div style="--my-value:var(--myValue);--myValue:red"></div>
480+
<!-- output (after) -->
481+
<div style="--myValue:red"></div>
482+
```
483+
484+
#### What should I do?
485+
486+
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:
487+
488+
```diff
489+
<style>
490+
div {
491+
- color: var(--my-value);
492+
+ color: var(--myValue);
493+
}
494+
</style>
495+
```
496+
DUPE TO BE COMBINED
497+
498+
Remove backwards-compatible kebab-case transform for camelCase CSS variable names passed to the `style` attribute. 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:
343499
344500
```astro
345501
---
@@ -362,6 +518,82 @@ const myValue = "red"
362518
</style>
363519
```
364520
521+
### Changed entrypoint export paths
522+
523+
In Astro v2.x, you can import internal Astro APIs from `astro/internal/star` and `astro/runtime/server/star`.
524+
525+
Astro v3.0 removes the two entrypoints in favour of the existing `astro/runtime/star` entrypoint.
526+
527+
#### What should I do?
528+
529+
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:
530+
531+
```diff
532+
- import 'astro/internal/index.js';
533+
+ import 'astro/runtime/server/index.js';
534+
535+
- import 'astro/server/index.js';
536+
+ import 'astro/runtime/server/index.js';
537+
```
538+
539+
### Small stylesheets now get inlined by default
540+
In Astro v2.x, all project stylesheets were sent lnd u could opt-in to inlining them by using the `build.inlineStylesheets` configuration.
541+
542+
were sent as link tags by default and you could opt in to inlining them
543+
544+
Astro v3.0 defaults `inlineStylesheets` to "auto", which means stylesheets smaller than 4kB get included in the initial response.
545+
546+
#### What should I do?
547+
Nothing, this change does not require any migration. To go back to the old behavior, configure `inlineStylesheets` to "never"
548+
549+
```diff
550+
export default defineConfig({
551+
build: {
552+
+ inlineStylesheets: "never"
553+
}
554+
})
555+
```
556+
557+
### Changed implementation of `class:list` directive
558+
In Astro v2.x, `class:list` used a custom implementation inspired by [`clsx`](https://github.com/lukeed/clsx) with a few extra features like deduplication and `Set` support.
559+
560+
In Astro v3.0, `class:list` uses [`clsx`](https://github.com/lukeed/clsx) directly, which does not support deduplication or `Set` values.
561+
562+
#### What should I do?
563+
564+
Replace any `Set` elements passed to the `class:list` directive with a plain `Array`.
565+
566+
```diff
567+
<Component class:list={[
568+
'a',
569+
'b',
570+
- new Set(['c', 'd'])
571+
+ ['c', 'd']
572+
]} />
573+
```
574+
575+
### Changed behavior of `class:list` directive for components
576+
577+
In Astro v2.x, `class:list` values were sent to components via `Astro.props['class:list']`.
578+
579+
In Astro v3.0, `class:list` values are normalized into a string before being sent to components via `Astro.props['class']`
580+
581+
#### What should I do?
582+
583+
Remove any code that expects to receive the `class:list` prop.
584+
585+
```diff
586+
---
587+
- import { clsx } from 'clsx';
588+
- const { class: className, 'class:list': classList } = Astro.props;
589+
+ const { class: className } = Astro.props;
590+
---
591+
<div
592+
- class:list={[className, classList]}
593+
+ class={className}
594+
/>
595+
```
596+
365597
## Known Issues
366598

367599
There are currently no known issues.

0 commit comments

Comments
 (0)