Ir para o conteúdo principal Pular para a navegação de documentos
Check
in English

Bootstrap e Webpack

O guia oficial de como incluir e empacotar CSS e JavaScript do Bootstrap em seu projeto usando Webpack.

Nesta página
Quer pular para o final? Baixe o código-fonte e a demonstração de trabalho deste guia no repositório twbs/examples . Você também pode abrir o exemplo no StackBlitz para edição ao vivo.

Configurar

Estamos construindo um projeto Webpack com Bootstrap do zero, então existem alguns pré-requisitos e etapas iniciais antes que possamos realmente começar. Este guia requer que você tenha o Node.js instalado e alguma familiaridade com o terminal.

  1. Crie uma pasta de projeto e configure o npm. Vamos criar a my-projectpasta e inicializar o npm com o -yargumento para evitar que ele nos faça todas as perguntas interativas.

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

  2. Instale o Webpack. Em seguida, precisamos instalar nossas dependências de desenvolvimento do Webpack: webpackpara o núcleo do Webpack, webpack-clipara que possamos executar comandos do Webpack a partir do terminal e webpack-dev-serverpara que possamos executar um servidor de desenvolvimento local. Usamos --save-devpara sinalizar que essas dependências são apenas para uso em desenvolvimento e não para produção.

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

  3. Instale o Bootstrap. Agora podemos instalar o Bootstrap. Também instalaremos o Popper, pois nossos menus suspensos, popovers e dicas de ferramentas dependem dele para seu posicionamento. Se você não planeja usar esses componentes, pode omitir Popper aqui.

    npm i --save bootstrap @popperjs/core

  4. Instale dependências adicionais. Além do Webpack e do Bootstrap, precisamos de mais algumas dependências para importar e agrupar corretamente o CSS e o JS do Bootstrap com o Webpack. Estes incluem Sass, alguns carregadores e Autoprefixer.

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

Agora que temos todas as dependências necessárias instaladas, podemos começar a criar os arquivos do projeto e importar o Bootstrap.

Estrutura do projeto

Já criamos a my-projectpasta e inicializamos o npm. Agora também criaremos nossas pastas srce para completar a estrutura do projeto. distExecute o seguinte em my-projectou crie manualmente a estrutura de pastas e arquivos mostrada abaixo.

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

Quando terminar, seu projeto completo deve ficar assim:

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

Neste ponto, tudo está no lugar certo, mas o Webpack não funcionará porque ainda não preenchemos o nosso webpack.config.js.

Configurar Webpack

Com as dependências instaladas e nossa pasta do projeto pronta para começarmos a codificar, agora podemos configurar o Webpack e executar nosso projeto localmente.

  1. Abra webpack.config.jsem seu editor. Como está em branco, precisaremos adicionar algumas configurações padrão para que possamos iniciar nosso servidor. Esta parte da configuração diz ao Webpack para procurar o JavaScript do nosso projeto, para onde enviar o código compilado para ( dist), e como o servidor de desenvolvimento deve se comportar (puxando da distpasta com hot reload).

    const path = require('path')

module.exports = {
  entry: './src/js/main.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist')
  },
  devServer: {
    static: path.resolve(__dirname, 'dist'),
    port: 8080,
    hot: true
  }
}

  2. Em seguida, preenchemos nosso dist/index.html. Esta é a página HTML que o Webpack carregará no navegador para utilizar o pacote CSS e JS que adicionaremos a ele em etapas posteriores. Antes de podermos fazer isso, temos que fornecer algo para renderizar e incluir o outputJS da etapa anterior.

    <!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>
    <script src="./main.js"></script>
  </body>
</html>

    Estamos incluindo um pouco do estilo do Bootstrap aqui com o div class="container"e <button>para que possamos ver quando o CSS do Bootstrap é carregado pelo Webpack.

  3. Agora precisamos de um script npm para executar o Webpack. Abra package.jsone adicione o startscript mostrado abaixo (você já deve ter o script de teste). Usaremos este script para iniciar nosso servidor de desenvolvimento Webpack local.

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

  4. E finalmente, podemos iniciar o Webpack. Na my-projectpasta do seu terminal, execute o script npm recém-adicionado:

    npm start
    Servidor de desenvolvimento do Webpack em execução

Na próxima e última seção deste guia, configuraremos os carregadores do Webpack e importaremos todo o CSS e JavaScript do Bootstrap.

Importar Bootstrap

A importação do Bootstrap para o Webpack requer os carregadores que instalamos na primeira seção. Nós os instalamos com o npm, mas agora o Webpack precisa ser configurado para usá-los.

  1. Configure os carregadores em webpack.config.js. Seu arquivo de configuração agora está completo e deve corresponder ao snippet abaixo. A única parte nova aqui é a moduleseção.

    const path = require('path')

module.exports = {
  entry: './src/js/main.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist')
  },
  devServer: {
    static: path.resolve(__dirname, 'dist'),
    port: 8080,
    hot: true
  },
  module: {
    rules: [
      {
        test: /\.(scss)$/,
        use: [
          {
            loader: 'style-loader'
          },
          {
            loader: 'css-loader'
          },
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: () => [
                  require('autoprefixer')
                ]
              }
            }
          },
          {
            loader: 'sass-loader'
          }
        ]
      }
    ]
  }
}

    Aqui está uma recapitulação de por que precisamos de todos esses carregadores. style-loaderinjeta o CSS em um <style>elemento na <head>página HTML, css-loaderajuda a usar @importe url(), postcss-loaderé necessário para o Autoprefixer e sass-loadernos permite usar Sass.

  2. Agora, vamos importar o CSS do Bootstrap. Adicione o seguinte para src/scss/styles.scssimportar todos os Sass de origem do Bootstrap.

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

    Você também pode importar nossas folhas de estilo individualmente, se desejar. Leia nossos documentos de importação Sass para obter detalhes.

  3. Em seguida carregamos o CSS e importamos o JavaScript do Bootstrap. Adicione o seguinte para src/js/main.jscarregar o CSS e importar todos os JS do Bootstrap. O Popper será importado automaticamente através do Bootstrap.

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

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

    Você também pode importar plug-ins JavaScript individualmente, conforme necessário, para reduzir o tamanho dos pacotes:

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

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

    Leia nossos documentos JavaScript para obter mais informações sobre como usar os plugins do Bootstrap.

  4. E pronto! 🎉 Com a fonte Sass e JS do Bootstrap totalmente carregadas, seu servidor de desenvolvimento local agora deve ficar assim.

    Servidor de desenvolvimento Webpack rodando com Bootstrap

    Agora você pode começar a adicionar quaisquer componentes do Bootstrap que deseja usar. Certifique-se de verificar o projeto de exemplo completo do Webpack para saber como incluir Sass personalizado adicional e otimizar sua compilação importando apenas as partes do CSS e JS do Bootstrap que você precisa.

Otimizações de produção

Dependendo de sua configuração, talvez você queira implementar algumas otimizações adicionais de segurança e velocidade úteis para executar o projeto em produção. Observe que essas otimizações não são aplicadas no projeto de exemplo do Webpack e cabe a você implementá-las.

Extraindo CSS

O style-loaderque configuramos acima emite CSS convenientemente no pacote para que dist/index.htmlnão seja necessário carregar manualmente um arquivo CSS. No entanto, essa abordagem pode não funcionar com uma Política de Segurança de Conteúdo estrita e pode se tornar um gargalo em seu aplicativo devido ao grande tamanho do pacote.

Para separar o CSS para que possamos carregá-lo diretamente do dist/index.html, use o mini-css-extract-loaderplugin Webpack.

Primeiro, instale o plug-in:

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

Em seguida, instancie e use o plugin na configuração do Webpack:

--- 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
           },
           {

Após executar npm run buildnovamente, haverá um novo arquivo dist/main.css, que conterá todo o CSS importado pelo src/js/main.js. Se você visualizar dist/index.htmlem seu navegador agora, o estilo estará ausente, pois está agora em dist/main.css. Você pode incluir o CSS gerado dist/index.htmlassim:

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

Extraindo arquivos SVG

O CSS do Bootstrap inclui várias referências a arquivos SVG por meio de data:URIs embutidos. Se você definir uma política de segurança de conteúdo para seu projeto que bloqueie data:URIs para imagens, esses arquivos SVG não serão carregados. Você pode contornar esse problema extraindo os arquivos SVG embutidos usando o recurso de módulos de ativos do Webpack.

Configure o Webpack para extrair arquivos SVG embutidos como este:

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

Depois de executar npm run buildnovamente, você encontrará os arquivos SVG extraídos dist/iconse referenciados corretamente do CSS.

Vê algo errado ou desatualizado aqui? Por favor , abra um problema no GitHub . Precisa de ajuda para solucionar problemas? Pesquise ou inicie uma discussão no GitHub.