@use vs @import: Modernising Your Bootstrap 5 Sass Workflow

@import rules are deprecated and will be removed in Dart Sass 2.0. That single line in your terminal forces a real architectural decision, and it affects every Bootstrap 5 project that relies on the traditional @import workflow. This post explains exactly what changes, what breaks, and how to migrate cleanly to @use and @forward before the deadline arrives.

Why @import Is Going Away

The core problem with @import is that every file it loads dumps its variables, mixins, and functions into a single global namespace. If two partials both define $primary, whichever loads last wins, silently. In a large project with vendor files, component partials, and utility overrides all chained together, tracking which definition is active becomes genuinely difficult.

Dart Sass, the reference implementation since Sass 3.x, introduced the module system in Dart Sass 1.23.0 (2019). By Dart Sass 1.65 (mid-2023), @import warnings became active by default. The Sass team has confirmed that Dart Sass 2.0 will throw a hard error when it encounters @import. LibSass and Ruby Sass are already deprecated and should not be used for any active project.

@use and @forward Explained

@use loads a stylesheet and makes its public members available under a namespace derived from the file name. You access them with dot notation:

// Before (legacy)
@import "variables";
color: $brand-color;

// After (module system)
@use "variables" as vars;
color: vars.$brand-color;

The same file is only compiled once regardless of how many @use statements reference it, which cuts build times on large projects.

@forward solves the re-export problem. If you have a _index.scss that aggregates several partials, you use @forward so that consumers of that index can reach everything inside it with a single @use:

// _index.scss
@forward "colors";
@forward "typography";
@forward "spacing";

// component.scss
@use "design-tokens" as tokens;
// now tokens.$color-primary, tokens.$font-size-base etc. are all available

You can also expose a namespace-free shorthand with @use "tokens" as *, but use this sparingly. It recreates the same pollution risk that @import carried, and the Sass team discourages it outside of carefully controlled entry files.

Bootstrap 5 Sass: The Module Status in 2025

Bootstrap 5 ships its own .scss source files (under scss/ in the npm package) and they still use @import internally as of Bootstrap 5.3. The Bootstrap team has tracked migration to the module system in their GitHub issues but it has not shipped yet. You cannot simply replace your project entry point with pure @use calls against Bootstrap’s source and expect a warning-free compile today.

Two pragmatic approaches work in the meantime:

1. Use the --silence-deprecation=import flag as a short-term measure. Add it to your Sass compile command to suppress warnings while you migrate your own code. It will stop working in Dart Sass 2.0, so treat it as a countdown timer, not a fix.
2. Wrap Bootstrap in a thin forwarding module. Create a _bootstrap.scss in your project that imports Bootstrap’s compiled CSS or pre-built partials, keeping the legacy surface inside one controlled file while the rest of your project uses the module system.

If you are already managing a custom Bootstrap bundle, the post on building a custom Bootstrap 5 bundle covers which component files are safe to include selectively, which matters when you isolate Bootstrap behind a wrapper.

Migrating Your Custom Partials

Start with files that have no upstream dependencies on Bootstrap variables or mixins. Utility helpers and pure token files are good first candidates. The Sass migration tool (sass-migrator) automates the mechanical parts:

npx sass-migrator module --migrate-deps src/scss/main.scss

Run it on a feature branch, review the diff, then fix any namespace collisions it flags. Three issues come up most often after migration:

• Variables referenced without a namespace prefix, because they were previously global.
• Mixins from a shared partial that are now only available in the file that @uses that partial directly.
• Configuration via !default variables, which must now be passed through @use "module" with ($variable: value) syntax.

That last point is significant for Bootstrap theming. Overriding Bootstrap’s $primary or any !default variable used to mean declaring your value before the @import. With the module system, it becomes:

@use "bootstrap" with (
  $primary: #e84c3d,
  $font-size-base: 1rem,
  $grid-gutter-width: 1.5rem
);

This is cleaner and explicit. It also pairs well with CSS custom property strategies. If you are managing per-brand theming, see the guide on theming one HTML template for multiple client brands with CSS variables for how Sass-level overrides and runtime CSS variables complement each other.

For more on Sass-specific Bootstrap customisation including breakpoint and gutter overrides, the post on customising Bootstrap 5 breakpoints and grid gutters with Sass shows the exact !default variables involved, which helps you identify which ones need the @use ... with treatment.

Build Tool Considerations

Your build tool must invoke Dart Sass, not Node Sass. Node Sass is deprecated and does not support the module system at all. Check your compiler against these specifics:

• Vite: Uses sass (Dart Sass) by default when you install the sass package. Module system works with no extra config.
• Webpack + sass-loader: Requires sass-loader version 12 or later and the sass package, not node-sass. Set api: "modern" in sass-loader options to enable the modern Dart Sass API and suppress legacy warnings.
• Gulp: Use gulp-sass with the Dart Sass compiler passed explicitly: gulpSass(sass) where sass is the imported sass npm package.

Verify with sass --version. You need 1.23.0 at an absolute minimum for module support, and 1.65.0 or later to see the deprecation warnings that show you where migration work remains.

Applying This to the Canvas Template Workflow

The Canvas HTML Template ships compiled CSS and a structured Sass source. When you extend Canvas with custom component styles, those custom partials are entirely under your control and are the best place to start a module-system migration today. Isolate Canvas’s own Sass output to a single import line in a dedicated wrapper file, then write all new partials using @use and @forward. Your custom variable overrides for Canvas’s --cnvs-themecolor and related custom properties live at the CSS layer and need no Sass module changes, so that part of your theming pipeline stays untouched.

Structure your custom Sass directory like this:

// src/scss/main.scss
@use "vendor/bootstrap-wrapper";   // contains legacy @import, silenced
@use "tokens" as *;                // design tokens, module system
@use "components/card";
@use "components/hero";
@use "utilities/spacing";

// src/scss/vendor/_bootstrap-wrapper.scss
// sass-lint:disable no-invalid-css  (or silence-deprecation flag in build)
@import "bootstrap/scss/bootstrap";

This pattern quarantines the legacy code, gives you a clear migration target, and keeps your own Sass clean and forward-compatible today.

Looking for a production-ready Bootstrap 5 HTML template? Browse Canvas Template demos and find the perfect starting point for your next project.

If you’re building with the Canvas HTML Template and want to ship production-ready Bootstrap 5 layouts faster, try Canvas Builder free — the visual builder that exports clean Canvas-ready markup in minutes.