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 1 commit
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. This is why Astro will link only the larger ones in your HTML as `<link rel="stylesheet">` tags, while inlining the 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.
lilnasy marked this conversation as resolved.
Show resolved Hide resolved

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.
The default threshold a stylesheet must meet to be linked externally is 4kB. To configure it, you can set the `assetsInlineLimit` vite build option to the intended size, in bytes. Note that this option affects script and image inlining as well.
lilnasy marked this conversation as resolved.
Show resolved Hide resolved

```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
Loading