Webpack: explain how to extract CSS from bundle

twbs · Jun 30, 2022 · 49b8d72 · 49b8d72
1 parent 9400b8f
commit 49b8d72
Showing 1 changed file with 62 additions and 0 deletions.
diff --git a/site/content/docs/5.2/getting-started/webpack.md b/site/content/docs/5.2/getting-started/webpack.md
@@ -229,6 +229,68 @@ Importing Bootstrap into Webpack requires the loaders we installed in the first
 
    Now you can start adding any Bootstrap components you want to use. Be sure to [checkout the complete Webpack example project](https://github.com/twbs/examples/tree/main/webpack) for how to include additional custom Sass and optimize your build by importing only the parts of Bootstrap's CSS and JS that you need.
 
+## Production optimizations
+The following headings describe some security and speed optimizations useful for running the project in production. Note that these optimizations are not applied on [the Webpack example project](https://github.com/twbs/examples/tree/main/webpack).
+
+### Extracting CSS into a separate file
+
+The `style-loader` we configured above conveniently emits CSS into the bundle so that manually loading a CSS file in `dist/index.html` is not necessary. This approach may not work with a strict Content Security Policy, however, and it may become a bottleneck in your application due to the large bundle size.
+
+To separate the CSS so that we can load it directly from `dist/index.html`, we will use the Webpack plugin `mini-css-extract-loader`.
+
+First, install the plugin.
+```sh
+npm install --save-dev mini-css-extract-plugin
+```
+
+Then instantiate and use the plugin in the Webpack configuration.
+```diff
+--- a/webpack/webpack.config.js
++++ b/webpack/webpack.config.js
+@@ -1,8 +1,10 @@
++const miniCssExtractPlugin = require('mini-css-extract-plugin')
+ const path = require('path')
+
+ module.exports = {
+   mode: 'development',
+   entry: './src/js/main.js',
++  plugins: [new miniCssExtractPlugin()],
+   output: {
+     filename: "main.js",
+     path: path.resolve(__dirname, "dist"),
+@@ -18,8 +20,8 @@ module.exports = {
+         test: /\.(scss)$/,
+         use: [
+           {
+-            // Adds CSS to the DOM by injecting a `<style>` tag
+-            loader: 'style-loader'
++            // Extracts CSS for each JS file that includes CSS
++            loader: miniCssExtractPlugin.loader
+           },
+           {
+```
+
+After running `npm run build` again, there will be a new file `dist/main.css`, which will contain all of the CSS imported by `src/js/main.js`.
+
+If you view `dist/index.html` in your browser now, the style will be missing, as it is now in a separate file.  You can include the generated CSS in `dist/index.html` like this:
+
+```diff
+--- a/webpack/dist/index.html
++++ b/webpack/dist/index.html
+@@ -3,6 +3,7 @@
+   <head>
+     <meta charset="utf-8">
+     <meta name="viewport" content="width=device-width, initial-scale=1">
++    <link rel="stylesheet" href="./main.css">
+     <title>Bootstrap w/ Webpack</title>
+   </head>
+   <body>
+```
+
+### Extracting SVG files
+
+Bootstrap's CSS includes multiple references to SVG files provided as inline `data:` URIs.  If you define a Content Security Policy for your project without allowing `data:` URIs for images, then these SVG files will not load. You can get around this problem by extracting the inline SVG files using Webpack's asset modules feature.
+
 {{< markdown >}}
 {{< partial "guide-footer.md" >}}
 {{< /markdown >}}