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.

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

Update CSS Bundle Control for 3.0 #4253

Merged
merged 3 commits into from
Aug 19, 2023
Merged
Changes from all commits
Commits
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
24 changes: 18 additions & 6 deletions src/content/docs/en/guides/styling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -531,24 +531,36 @@ If you are using Tailwind, the [typography plugin](https://tailwindcss.com/docs/

### Bundle control

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.
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.

In each of your HTML files there will be `<link rel="stylesheet">` tags added, one for each of the chunks that the pages needs.
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.

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.
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.

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

export default defineConfig({
vite: {
build: {
assetsInlineLimit: 1024,
}
};
});
```

If you would rather all project styles remain external, you can configure the `inlineStylesheets` build option.

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

export default defineConfig({
build: {
inlineStylesheets: 'auto'
inlineStylesheets: 'never'
}
});
```

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.

You can also set this option to `'always'` which will inline all stylesheets.

## Advanced
Expand Down