Перейти к основному контенту Перейти к навигации документации
Просмотреть на GitHub

Bootstrap и Webpack

Официальное руководство по включению и сборке CSS и JavaScript Bootstrap в вашем проекте с использованием Webpack.

На этой странице

Хотите перейти сразу к концу? Скачайте исходный код и рабочее демо для этого руководства из репозитория twbs/examples. Вы также можете открыть пример в StackBlitz для редактирования в реальном времени.

Что такое Webpack?

Webpack — это сборщик JavaScript-модулей, который обрабатывает модули и их зависимости для генерации статических активов. Он упрощает управление сложными веб-приложениями с множественными файлами и зависимостями.

Настройка

Мы создаем проект Webpack с Bootstrap с нуля, поэтому есть некоторые предварительные условия и первоначальные шаги, прежде чем мы сможем по-настоящему начать. Это руководство требует, чтобы у вас был установлен Node.js и некоторое знакомство с терминалом.

  1. Создайте папку проекта и настройте npm. Мы создадим папку my-project и инициализируем npm с аргументом -y, чтобы избежать всех интерактивных вопросов.

    mkdir my-project && cd my-project
npm init -y

  2. Установите Webpack. Далее нам нужно установить зависимости разработки Webpack: webpack для ядра Webpack, webpack-cli, чтобы мы могли запускать команды Webpack из терминала, и webpack-dev-server, чтобы мы могли запускать локальный сервер разработки. Кроме того, мы установим html-webpack-plugin, чтобы иметь возможность хранить наш index.html в каталоге src вместо каталога dist по умолчанию. Мы используем --save-dev, чтобы обозначить, что эти зависимости предназначены только для разработки, а не для продакшена.

    npm i --save-dev webpack webpack-cli webpack-dev-server html-webpack-plugin

  3. Установите Bootstrap. Теперь мы можем установить Bootstrap. Мы также установим Popper, поскольку наши выпадающие списки, поповеры и подсказки зависят от него для позиционирования. Если вы не планируете использовать эти компоненты, вы можете опустить Popper здесь.

    npm i --save bootstrap @popperjs/core

  4. Установите дополнительные зависимости. Помимо Webpack и Bootstrap, нам нужно еще несколько зависимостей для правильного импорта и сборки CSS и JS Bootstrap с Webpack. К ним относятся Sass, некоторые загрузчики и Autoprefixer.

    npm i --save-dev autoprefixer css-loader postcss-loader sass sass-loader style-loader

Теперь, когда у нас установлены все необходимые зависимости, мы можем приступить к созданию файлов проекта и импорту Bootstrap.

Структура проекта

Мы уже создали папку my-project и инициализировали npm. Теперь мы также создадим наши папки src и dist, чтобы завершить структуру проекта. Выполните следующее из my-project или вручную создайте структуру папок и файлов, показанную ниже.

mkdir {src,src/js,src/scss}
touch src/index.html src/js/main.js src/scss/styles.scss webpack.config.js

Когда вы закончите, ваш полный проект должен выглядеть так:

my-project/
├── src/
│   ├── js/
│   │   └── main.js
│   ├── scss/
│   │   └── styles.scss
│   └── index.html
├── package-lock.json
├── package.json
└── webpack.config.js

На этом этапе все находится в нужном месте, но Webpack не будет работать, поскольку мы еще не заполнили наш webpack.config.js.

Конфигурация Webpack

После установки зависимостей и готовности папки проекта к началу кодирования, мы теперь можем настроить Webpack и запустить наш проект локально.

  1. Откройте webpack.config.js в вашем редакторе. Поскольку он пустой, нам нужно добавить в него некоторую шаблонную конфигурацию, чтобы мы могли запустить наш сервер. Эта часть конфигурации сообщает Webpack, где искать JavaScript нашего проекта, куда выводить скомпилированный код (dist) и как должен вести себя сервер разработки (загружая из папки dist с горячей перезагрузкой).

    'use strict'

const path = require('path')
const HtmlWebpackPlugin = require('html-webpack-plugin')

module.exports = {
  mode: 'development',
  entry: './src/js/main.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist')
  },
  devServer: {
    static: path.resolve(__dirname, 'dist'),
    port: 8080,
    hot: true
  },
  plugins: [
    new HtmlWebpackPlugin({ template: './src/index.html' })
  ]
}

  2. Теперь заполним наш src/index.html. Это HTML-страница, которую Webpack будет загружать в браузере для использования собранных CSS и JS, которые мы добавим на следующих шагах. Прежде чем это сделать, нам нужно добавить в неё какой-либо контент и подключить JS-файл output из предыдущего шага.

    <!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Bootstrap w/ Webpack</title>
  </head>
  <body>
    <div class="container py-4 px-3 mx-auto">
      <h1>Hello, Bootstrap and Webpack!</h1>
      <button class="btn btn-primary">Primary button</button>
    </div>
  </body>
</html>

    Мы включаем немного стилей Bootstrap здесь с div class="container" и <button>, чтобы мы видели, когда CSS Bootstrap загружается Webpack.

  3. Теперь нам нужен npm-скрипт для запуска Webpack. Откройте package.json и добавьте скрипт start, показанный ниже (у вас уже должен быть test-скрипт). Мы будем использовать этот скрипт для запуска нашего локального сервера разработки Webpack. Вы также можете добавить скрипт build, показанный ниже, для сборки вашего проекта.

    {
  // ...
  "scripts": {
    "start": "webpack serve",
    "build": "webpack build --mode=production",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  // ...
}

  4. И наконец, мы можем запустить Webpack. Из папки my-project в вашем терминале запустите этот ново добавленный npm-скрипт:

    npm start
    Webpack dev server running

В следующем и заключительном разделе этого руководства мы настроим загрузчики Webpack и импортируем все CSS и JavaScript Bootstrap.

Импорт Bootstrap

Импорт Bootstrap в Webpack требует загрузчиков, которые мы установили в первом разделе. Мы установили их с помощью npm, но теперь Webpack нужно настроить для их использования.

  1. Настройте загрузчики в webpack.config.js. Ваш конфигурационный файл теперь завершен и должен соответствовать фрагменту ниже. Единственная новая часть здесь — это раздел module.

    'use strict'

const path = require('path')
const autoprefixer = require('autoprefixer')
const HtmlWebpackPlugin = require('html-webpack-plugin')

module.exports = {
  mode: 'development',
  entry: './src/js/main.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist')
  },
  devServer: {
    static: path.resolve(__dirname, 'dist'),
    port: 8080,
    hot: true
  },
  plugins: [
    new HtmlWebpackPlugin({ template: './src/index.html' })
  ],
  module: {
    rules: [
      {
        test: /\.(scss)$/,
        use: [
          {
            // Adds CSS to the DOM by injecting a `<style>` tag
            loader: 'style-loader'
          },
          {
            // Interprets `@import` and `url()` like `import/require()` and will resolve them
            loader: 'css-loader'
          },
          {
            // Loader for webpack to process CSS with PostCSS
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  autoprefixer
                ]
              }
            }
          },
          {
            // Loads a SASS/SCSS file and compiles it to CSS
            loader: 'sass-loader',
            options: {
              sassOptions: {
                // Optional: Silence Sass deprecation warnings. See note below.
                silenceDeprecations: [
                  'mixed-decls',
                  'color-functions',
                  'global-builtin',
                  'import'
                ]
              }
            }
          }
        ]
      }
    ]
  }
}

    Вот краткое изложение того, почему мы нужены все эти загрузчики. style-loader вставляет CSS в элемент <style> в <head> HTML-страницы, css-loader помогает использовать @import и url(), postcss-loader требуется для Autoprefixer, а sass-loader позволяет нам использовать Sass.

    Примечание: Предупреждения об устаревании Sass отображаются при компиляции исходных Sass-файлов с последними версиями Dart Sass. Это не препятствует компиляции или использованию Bootstrap. Мы работаем над долгосрочным решением, но пока эти уведомления об устаревании можно игнорировать.

  2. Теперь давайте импортируем CSS Bootstrap. Добавьте следующее в src/scss/styles.scss, чтобы импортировать все исходные файлы Sass Bootstrap.

    // Import all of Bootstrap’s CSS
@import "bootstrap/scss/bootstrap";

    Вы также можете импортировать наши таблицы стилей по отдельности, если хотите. Почитайте нашу документацию по импорту Sass для получения подробностей.

  3. Далее мы загружаем CSS и импортируем JavaScript Bootstrap. Добавьте следующее в src/js/main.js, чтобы загрузить CSS и импортировать все JS Bootstrap. Popper будет импортирован автоматически через Bootstrap.

    // Import our custom CSS
import '../scss/styles.scss'

// Import all of Bootstrap’s JS
import * as bootstrap from 'bootstrap'

    Вы также можете импортировать JavaScript-плагины по отдельности по мере необходимости, чтобы уменьшить размеры пакета:

    import Alert from 'bootstrap/js/dist/alert'

// or, specify which plugins you need:
import { Tooltip, Toast, Popover } from 'bootstrap'

    Почитайте нашу документацию по JavaScript для получения дополнительной информации о том, как использовать плагины Bootstrap.

  4. И вы закончили! 🎉 После полной загрузки исходных Sass и JS Bootstrap ваш локальный сервер разработки теперь должен выглядеть так:

    Webpack dev server running with Bootstrap

    Теперь вы можете начать добавлять любые компоненты Bootstrap, которые вы хотите использовать. Обязательно посмотрите полный пример проекта Webpack, чтобы узнать, как включить дополнительные пользовательские Sass и оптимизировать сборку, импортируя только те части CSS и JS Bootstrap, которые вам нужны.

Оптимизации для продакшена

В зависимости от вашей настройки, вы можете реализовать некоторые дополнительные оптимизации безопасности и скорости, полезные для запуска проекта в продакшене. Обратите внимание, что эти оптимизации не применяются в примере проекта Webpack и зависят от вас.

Извлечение CSS

style-loader, который мы настроили выше, удобно выпускает CSS в пакет, поэтому ручное загрузка CSS-файла в dist/index.html не требуется. Однако этот подход может не работать с строгими политикой безопасности контента, однако он может стать узким местом в вашем приложении из-за большого размера пакета.

Чтобы отделить CSS, чтобы мы могли загружать его непосредственно из dist/index.html, используйте плагин mini-css-extract-loader Webpack.

Сначала установите плагин:

npm install --save-dev mini-css-extract-plugin

Затем создайте и используйте плагин в конфигурации Webpack:

--- a/webpack.config.js
+++ b/webpack.config.js
@@ -3,6 +3,7 @@
 const path = require('path')
 const autoprefixer = require('autoprefixer')
 const HtmlWebpackPlugin = require('html-webpack-plugin')
+const miniCssExtractPlugin = require('mini-css-extract-plugin')

 module.exports = {
   mode: 'development',
@@ -17,7 +18,8 @@ module.exports = {
     hot: true
   },
   plugins: [
-    new HtmlWebpackPlugin({ template: './src/index.html' })
+    new HtmlWebpackPlugin({ template: './src/index.html' }),
+    new miniCssExtractPlugin()
   ],
   module: {
     rules: [
@@ -25,8 +27,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
           },
           {

После повторного запуска npm run build будет новый файл dist/main.css, который будет содержать все CSS, импортированное из src/js/main.js. Если вы теперь посмотрите dist/index.html в своем браузере, стиль будет отсутствовать, так как он теперь находится в dist/main.css. Вы можете включить сгенерированный CSS в dist/index.html так:

--- a/dist/index.html
+++ b/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>

Извлечение SVG-файлов

CSS Bootstrap включает в себя несколько ссылок на SVG-файлы через встроенные data: URI. Если вы определите политику безопасности контента для вашего проекта, которая блокирует data: URI для изображений, то эти SVG-файлы не будут загружаться. Вы можете обойти эту проблему, извлекая встроенные SVG-файлы с помощью функции модулей активов Webpack.

Настройте Webpack для извлечения встроенных SVG-файлов так:

--- a/webpack.config.js
+++ b/webpack.config.js
@@ -23,6 +23,14 @@ module.exports = {
   },
   module: {
     rules: [
+      {
+        mimetype: 'image/svg+xml',
+        scheme: 'data',
+        type: 'asset/resource',
+        generator: {
+          filename: 'icons/[hash].svg'
+        }
+      },
       {
         test: /\.(scss)$/,
         use: [

После повторного запуска npm run build вы найдете SVG-файлы извлечены в dist/icons и правильно ссылаются из CSS.

Видите что-то неправильное или устаревшее здесь? Пожалуйста, создайте issue на GitHub. Нужна помощь в устранении неполадок? Найдите или начните обсуждение на GitHub.