@import to @use migration in SASS - Deep Dive

Overview - @import to @use migration

What is it?

@import and @use are ways to include styles from one Sass file into another. @import was the old method, but it has problems like loading files multiple times and polluting the global style space. @use is the new, recommended way that loads files once and keeps styles organized and scoped. Migrating means changing your Sass code from @import to @use to get better performance and clearer code.

Why it matters

Without migrating to @use, your stylesheets can become slow and hard to maintain because @import loads files repeatedly and mixes all styles globally. This can cause bugs and make your project grow messy. Using @use helps keep styles modular and efficient, making your website faster and easier to update.

Where it fits

Before learning this, you should know basic Sass syntax and how @import works. After this, you can learn about Sass modules, namespaces, and advanced features like mixins and functions with @use.

Mental Model

Core Idea

@use loads a Sass file once and keeps its styles in a private box, while @import loads files multiple times and mixes all styles globally.

Think of it like...

Imagine @import as pouring all your paint colors into one big bucket, mixing them all together, which can get messy. @use is like keeping each paint color in its own labeled jar, so you only use what you need without mixing everything.

┌───────────────┐       ┌───────────────┐
│  main.scss    │       │  main.scss    │
│               │       │               │
│ @import a.scss│       │ @use a.scss   │
└──────┬────────┘       └──────┬────────┘
       │                        │
       ▼                        ▼
┌───────────────┐       ┌───────────────┐
│  a.scss       │       │  a.scss       │
│ (loaded each  │       │ (loaded once, │
│  time imported)│      │  scoped styles)│
└───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding @import basics

Concept: Learn how @import includes one Sass file into another and what it does.

In Sass, @import lets you bring styles from another file into your current file. For example, @import 'colors'; will include all styles from colors.scss. This helps split styles into smaller files. But @import copies the content every time it is used, which can cause duplication.

Result

Your styles from the imported file appear in the final CSS as if they were written in the main file.

Understanding @import is key because it shows why loading files multiple times can slow down your project and cause style conflicts.

2

Foundation

Introducing @use for modular styles

Concept: @use loads a Sass file once and keeps its styles private unless explicitly shared.

@use 'colors'; loads colors.scss only once. Unlike @import, it does not copy styles everywhere. Instead, it creates a namespace (like colors.) to access variables or mixins. This keeps styles organized and avoids conflicts.

Result

Styles from colors.scss are available under the colors namespace, preventing accidental overwrites.

Knowing that @use creates a private box for styles helps you write safer and clearer Sass code.

3

Intermediate

Namespaces and accessing styles

🤔Before reading on: do you think you can use variables from a @use file without prefixing the namespace? Commit to your answer.

Concept: Learn how to access variables, mixins, and functions from a @use file using namespaces.

When you @use a file, you must prefix its variables or mixins with the namespace. For example, if you @use 'colors'; and colors.scss has $primary: blue;, you access it as colors.$primary. This avoids naming clashes.

Result

You can safely use styles from multiple files without overwriting each other.

Understanding namespaces prevents bugs caused by variables or mixins with the same name in different files.

4

Intermediate

Using 'as *' to simplify namespaces

🤔Before reading on: do you think using 'as *' removes all namespace prefixes? Commit to your answer.

Concept: Learn how to remove namespaces with @use 'file' as * to access styles directly.

You can write @use 'colors' as *; to use variables without the colors. prefix. But this can cause conflicts if multiple files have the same names. Use it carefully.

Result

Variables and mixins are accessible directly, but risk name clashes.

Knowing when to use 'as *' helps balance convenience and safety in your styles.

5

Intermediate

Migrating variables from @import to @use

🤔Before reading on: do you think variables from @import are global or scoped? Commit to your answer.

Concept: Understand how variables behave differently when moving from @import to @use.

With @import, variables are global and accessible everywhere. With @use, variables are scoped under namespaces. To migrate, you must update your code to use the namespace prefix or use 'as *' carefully.

Result

Your variables work correctly without polluting the global scope.

Knowing variable scoping differences prevents broken styles after migration.

6

Advanced

Handling mixins and functions in migration

🤔Before reading on: do you think mixins from @import require namespace prefixes after @use? Commit to your answer.

Concept: Learn how to update mixins and functions usage when migrating to @use.

Mixins and functions imported with @import are global. With @use, you must prefix them with the namespace, like colors.mixin-name(); Update your calls accordingly.

Result

Mixins and functions work without conflicts or errors.

Understanding this avoids runtime errors and keeps your styles modular.

7

Expert

Avoiding circular dependencies in @use

🤔Before reading on: do you think @use allows circular imports without issues? Commit to your answer.

Concept: Learn why circular dependencies cause errors with @use and how to fix them.

@use loads files once and caches them. If two files @use each other, Sass throws an error. To fix, restructure your files to remove circular references or combine shared code into a separate file.

Result

Your Sass compiles without circular import errors.

Knowing this prevents a common migration pitfall that can break your build.

Under the Hood

@use works by loading a Sass file once per compilation and creating a module namespace. It caches the loaded file to avoid duplication. Variables, mixins, and functions inside the file are scoped to this namespace, preventing global pollution. This contrasts with @import, which copies the file content every time it is called, merging all styles globally.

Why designed this way?

@use was designed to fix problems with @import such as slow compilation, duplicated styles, and global namespace pollution. By introducing modules and namespaces, Sass encourages better code organization and performance. Alternatives like keeping @import were rejected because they caused maintenance headaches and bugs in large projects.

┌───────────────┐
│  main.scss    │
│ @use colors;  │
└──────┬────────┘
       │ loads once
       ▼
┌───────────────┐
│  colors.scss  │
│ $primary: blue│
│ mixin button  │
└───────────────┘
       │
       ▼
┌─────────────────────────────┐
│ Namespace 'colors' created   │
│ Access with colors.$primary  │
│ and colors.button() mixin    │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does @use load the same file multiple times like @import? Commit to yes or no.

Common Belief: Many think @use behaves just like @import and loads files multiple times.

Reality: @use loads each file only once per compilation and caches it, improving performance.

Why it matters: Believing @use duplicates files can cause confusion and prevent adopting the better method.

Quick: Can you use variables from a @use file without prefixing the namespace? Commit to yes or no.

Common Belief: Some believe variables from @use files are global and accessible without prefixes.

Reality: Variables are scoped under the namespace and require prefixing unless 'as *' is used.

Why it matters: Assuming global access leads to errors and broken styles after migration.

Quick: Does @use allow circular imports without errors? Commit to yes or no.

Common Belief: Some think circular imports work fine with @use as they did with @import.

Reality: @use throws errors on circular dependencies because it caches files and cannot resolve loops.

Why it matters: Ignoring this causes build failures and confusion during migration.

Quick: Does using 'as *' with @use always improve code clarity? Commit to yes or no.

Common Belief: Many believe 'as *' is always better because it removes namespace prefixes.

Reality: 'as *' can cause naming conflicts and reduce the modular benefits of @use.

Why it matters: Overusing 'as *' can reintroduce problems @use was designed to solve.

Expert Zone

1

Using @forward in combination with @use allows creating public APIs for Sass modules, controlling what is exposed to other files.

2

The order of @use statements matters because Sass loads files once and caches them, so side effects in modules can affect others.

3

You can configure namespaces with aliases in @use, which helps when importing multiple modules with similar names.

When NOT to use

@use is not suitable if you rely heavily on global variables or legacy code that cannot be refactored easily. In such cases, maintaining @import temporarily or using build tools to manage legacy styles might be better.

Production Patterns

In production, teams use @use with @forward to build modular style libraries. They namespace all variables and mixins to avoid conflicts and improve maintainability. Build tools often enforce no @import usage to ensure consistent performance.

Connections

JavaScript ES6 Modules

@use in Sass is similar to ES6 import/export modules in JavaScript.

Understanding how JavaScript modules scope and share code helps grasp Sass @use namespaces and single loading.

Software Encapsulation

@use enforces encapsulation by hiding styles inside namespaces.

Knowing encapsulation principles from software engineering clarifies why @use prevents global style pollution.

Library Management in Package Managers

Like package managers avoid duplicate downloads, @use caches files to avoid repeated loading.

Recognizing caching and deduplication patterns in package management helps understand @use's performance benefits.

Common Pitfalls

#1 Using @import and @use together without understanding their differences.

Wrong approach:

@import 'colors';
@use 'colors';

Correct approach:

@use 'colors';

Root cause:

Confusion about how @import and @use interact leads to redundant or conflicting style loads.

#2 Accessing variables from a @use file without namespace prefix.

Wrong approach:

$main-color: $primary-color;

Correct approach:

$main-color: colors.$primary-color;

Root cause:

Not realizing @use scopes variables under namespaces causes undefined variable errors.

#3 Creating circular dependencies by having two files @use each other.

Wrong approach:

// a.scss
@use 'b';

// b.scss
@use 'a';

Correct approach:

// Combine shared code into c.scss
// a.scss
@use 'c';

// b.scss
@use 'c';

Root cause:

Lack of understanding that @use caches files and cannot resolve circular imports.

Key Takeaways

@use is the modern way to include Sass files, loading each file once and keeping styles scoped.

Namespaces created by @use prevent style conflicts and make your code more maintainable.

Migrating from @import to @use requires updating variable and mixin references to use namespaces.

Avoid circular dependencies with @use by restructuring your Sass files carefully.

Using @use improves performance and clarity, making your stylesheets easier to work with and faster to compile.