Project Setup with npm, Vite and Sass Imports

The CDN link from the previous lesson is perfect for experiments, but real projects install Bootstrap as a dependency so the version is locked, the CSS can be customized with Sass, and the JavaScript can be bundled with the rest of your code. In this lesson you will create a Vite project, install Bootstrap and its peer dependency Popper, import the Sass source and JavaScript, and understand which files in the package do what.

Why Install Instead of Linking the CDN?

| Approach | Pros | Cons | |---|---|---| | CDN <link> and <script> | Zero setup, cached across sites | Cannot change Sass variables, one more external request, version pinned in HTML | | npm + bundler | Customizable theme, tree-shakable JS, single build pipeline | Needs Node.js and a build step | | Download compiled files | No network dependency | Same limits as CDN, manual updates |

If you plan to change brand colors, remove unused components, or ship a single optimized bundle, install the package.

Creating the Project

Vite is the quickest modern bundler to start with. Any recent Node.js LTS works.

bash

npm create vite@latest my-bootstrap-app -- --template vanilla
cd my-bootstrap-app
npm install
npm install bootstrap @popperjs/core
npm install --save-dev sass

@popperjs/core positions dropdowns, tooltips and popovers; Bootstrap lists it as a peer dependency, so you install it yourself. sass is only needed if you want to compile the .scss source rather than use the prebuilt CSS.

What Ships in the Package

Inside node_modules/bootstrap/ you will find:

dist/css/bootstrap.min.css - the compiled, full stylesheet (plus RTL and per-part builds such as bootstrap-grid.css and bootstrap-utilities.css).
dist/js/bootstrap.bundle.min.js - all plugins with Popper included.
dist/js/bootstrap.min.js - all plugins without Popper (you load Popper separately).
scss/ - the Sass source: _variables.scss, _maps.scss, mixins/, and one partial per component.
js/src/ - ES module source for each plugin (js/src/modal.js, js/src/toast.js, etc.).

Importing the Styles

Create src/styles.scss and replace the default style.css import in src/main.js:

scss

// src/styles.scss
// 1. Override defaults here (must come before the import)
$primary: #4f46e5;
$border-radius: 0.5rem;

// 2. Pull in all of Bootstrap
@import "bootstrap/scss/bootstrap";

// 3. Your own styles come after, so they can use Bootstrap variables and mixins
.hero {
  padding: 4rem 0;
  background: tint-color($primary, 90%);
}

If you do not need customization yet, you can skip Sass entirely:

javascript

// src/main.js
import "bootstrap/dist/css/bootstrap.min.css";

Importing the JavaScript

There are two common styles. Import everything when you use many components:

javascript

// src/main.js
import "./styles.scss";
import * as bootstrap from "bootstrap";

const modal = new bootstrap.Modal("#signup-modal");
modal.show();

Import individual plugins when bundle size matters. Vite tree-shakes what you do not use:

javascript

import Tooltip from "bootstrap/js/dist/tooltip";
import Toast from "bootstrap/js/dist/toast";

document.querySelectorAll('[data-bs-toggle="tooltip"]').forEach((el) => new Tooltip(el));

Note that data-bs-* attributes only work for a plugin that has been imported; Bootstrap registers the click handlers when the module loads. If a dropdown does nothing, the first thing to check is whether Dropdown (or the full bundle) was imported.

Running and Building

bash

npm run dev      # dev server with hot reload, usually http://localhost:5173
npm run build    # writes an optimized bundle to dist/
npm run preview  # serves the production build locally

The production build minifies CSS, hashes filenames for caching, and drops any plugin you never imported.

Common Mistakes

Overriding variables after the import. Sass variables in Bootstrap are declared with !default, which means your value only wins if it is set before @import "bootstrap/scss/bootstrap".
Forgetting Popper. Dropdowns and tooltips throw Bootstrap's dropdowns require Popper when @popperjs/core is missing and you import bootstrap.min.js instead of the bundle.
Importing both the CDN and the npm copy. Two copies of the JavaScript register duplicate event handlers, so a modal can open and instantly close.
Ignoring Sass deprecation warnings. Bootstrap 5.3 still uses @import; Dart Sass prints warnings about it. They are safe to ignore for now and will be addressed in Bootstrap 6.

Key Takeaways

Install with npm install bootstrap @popperjs/core and add sass as a dev dependency if you want to customize.
The package ships compiled CSS/JS in dist/ and Sass and ES module sources in scss/ and js/.
Override Sass variables before importing bootstrap/scss/bootstrap, never after.
Import the whole library with import * as bootstrap from "bootstrap" or individual plugins from bootstrap/js/dist/* for a smaller bundle.
data-bs-* attributes only work for plugins whose JavaScript you actually imported.

Next lesson: Containers and the Grid System - learn how .container, .row and .col build every responsive Bootstrap layout.