SWAT Bootstrap

Provides ready to use Bootstrap dependencies and configurations.

Usage

The primary use case for this package is the global theme component. In this example, a global theme component is created and attached as a library, allowing all other theme components to use Bootstrap features. The following tree represents the files created or modified for this example.

[webroot]/themes/custom/[theme_name]/
├── components/
│   └── global/
│       ├── public/
│       │   ├── css/
│       │   │   └── global.css
│       │   └── js/
│       │       └── bootstrap.js
│       ├── src/
│       │   ├── js/
│       │   │   └── bootstrap.ts (entry point)
│       │   └── scss/
│       │       └── global.scss (entry point)
│       └── package.json
├── [theme_name].info.yml
└── [theme_name].libraries.yml

Step 1: Create component workspace

Create [webroot]/themes/custom/[theme_name]/components/global/package.json with the following contents, then run npm install from the project root to download the dependencies.

{
  "name": "@theme/global",
  "type": "module",
  "scripts": {
    "build": "swat build"
  },
  "dependencies": {
    "@imagexmedia/bootstrap": "*"
  }
}

Step 2: Import Bootstrap JavaScript

Create [webroot]/themes/custom/[theme_name]/components/global/src/js/bootstrap.ts with the following contents, then run npm run build from the project root to output the compiled JavaScript. To disable unused JavaScript features, comment out the line. Note that the import is from @imagexmedia/bootstrap instead of bootstrap to ensure the bundled TypeScript definitions are applied automatically.

import * as Bootstrap from '@imagexmedia/bootstrap'

window.Alert = Bootstrap.Alert
window.Button = Bootstrap.Button
window.Carousel = Bootstrap.Carousel
window.Collapse = Bootstrap.Collapse
window.Dropdown = Bootstrap.Dropdown
window.Modal = Bootstrap.Modal
window.Offcanvas = Bootstrap.Offcanvas
window.Popover = Bootstrap.Popover
window.ScrollSpy = Bootstrap.ScrollSpy
window.Tab = Bootstrap.Tab
window.Toast = Bootstrap.Toast
window.Tooltip = Bootstrap.Tooltip

Step 3: Import Bootstrap SCSS

Create [webroot]/themes/custom/[theme_name]/components/global/src/scss/global.scss with the following contents, then run npm run build from the project root to output the compiled CSS. The example imports all Bootstrap CSS, which is not usually necessary, and should be changed to import only the required CSS. See https://getbootstrap.com/docs/5.3/customize/sass/#importing for more information.

@import "bootstrap/scss/bootstrap";

Step 4: Add component to library

Add the following entry to [webroot]/themes/custom/[theme_name]/[theme_name].libraries.yml to register the component with the theme library. Note that minified: true is set to prevent double-minifying outputs. When the project is built in production mode, the outputs are already optimized and minified.

global:
  js:
    components/global/public/js/bootstrap.js:
      minified: true
      # Only needed if the build output includes ES Module (ESM) statements.
      attributes: { type: module }
  css:
    layout:
      components/global/public/css/global.css:
        minified: true

Now add the following entry to [webroot]/themes/custom/[theme_name]/[theme_name].info.yml to load the compiled JavaScript and CSS on all theme pages. By adding it to every page, in most cases, it won't be necessary to add it as a dependency for other theme components.

libraries:
  - theme/global

Additional resources

See https://bitbucket.org/ixm/swat/src/7.0.x/defaults/bootstrap/ for a working example.