Migrate Sass from `@import` to `@use`/`@forward` module system #18

New issue

Closed

opened 2025-11-23 15:41:43 +00:00 by Athemis · 0 comments

Athemis commented

2025-11-23 15:41:43 +00:00

Owner

Description

Background
The Sass @import rule is deprecated and will be completely removed in Dart Sass 3.0.0. Currently, we're still using @import in all SCSS files, which causes deprecation warnings during build:

Deprecation Warning [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.

More info and automated migrator: https://sass-lang.com/d/import

Why migrate?

Future-proofing: @import will stop working in Dart Sass 3.0.0
Better performance: The new module system loads each file only once
Clearer namespaces: Variables and mixins are explicitly available through namespaces
Avoid naming conflicts: Each module has its own namespace
Best practices: The new system is the recommended standard since 2019

Current Status
The deprecation warning has been temporarily suppressed in rollup.config.js:

sass: {
  silenceDeprecations: ["import"],
}

This is only a short-term solution and should be replaced with a complete migration.

What needs to be done?

1. Main stylesheet (`scss/ds4.scss`)

Replace all @import statements with @use
Optional: Define namespaces for better readability

2. Partial files (all `_*.scss` files)

Affected files:

scss/global/_*.scss (3 files)
scss/components/shared/_*.scss (13 files)
scss/components/actor/_*.scss (14 files)
scss/components/item/_*.scss (3 files)
scss/components/dice/_*.scss (1 file)
scss/utils/_*.scss (variables, mixins, colors)

For each file, check:

Are variables/mixins used by other files? → Export with @forward
Are variables/mixins imported from other files? → Import with @use and use namespace

3. Test Rollup configuration

The rollup-plugin-styler plugin must work with the new module system
If not: Evaluate alternative plugins (e.g., @rollup/plugin-sass, vite-plugin-sass)

4. Testing

Run build and check for errors
Compare generated CSS with previous CSS (should be identical)
Visual test in browser: All styles should work as before

Migration Tools

Sass provides an official migrator tool:

pnpm exec sass-migrator module --migrate-deps scss/ds4.scss

⚠️ Warning: The tool cannot automatically handle all edge cases, especially:

Naming conflicts for variables
Global variables vs. modular encapsulated variables
Compatibility with build tools

Challenges

Namespace management: Variables will no longer be global
- Example: $primary-color becomes colors.$primary-color
Rollup plugin compatibility: rollup-plugin-styler may have issues with pure @use imports
Breaking changes: If the plugin is not compatible, we may need to adjust the build process

Resources

Acceptance Criteria

All @import statements are replaced with @use/@forward
Build runs without deprecation warnings
Generated CSS is identical to previous version
All styles work correctly in the browser
Temporary warning suppression is removed from rollup.config.js
Documentation is updated (if SCSS development is documented)

Estimated Effort

Medium to high - depending on plugin compatibility and number of manual adjustments

Context

No response

### Description Background The Sass `@import` rule is deprecated and will be completely removed in Dart Sass 3.0.0. Currently, we're still using `@import` in all SCSS files, which causes deprecation warnings during build: ``` Deprecation Warning [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0. More info and automated migrator: https://sass-lang.com/d/import ``` ### Why migrate? 1. **Future-proofing**: `@import` will stop working in Dart Sass 3.0.0 2. **Better performance**: The new module system loads each file only once 3. **Clearer namespaces**: Variables and mixins are explicitly available through namespaces 4. **Avoid naming conflicts**: Each module has its own namespace 5. **Best practices**: The new system is the recommended standard since 2019 Current Status The deprecation warning has been temporarily suppressed in `rollup.config.js`: ```javascript sass: { silenceDeprecations: ["import"], } ``` This is only a short-term solution and should be replaced with a complete migration. ### What needs to be done? #### 1. Main stylesheet (`scss/ds4.scss`) - Replace all `@import` statements with `@use` - Optional: Define namespaces for better readability #### 2. Partial files (all `_*.scss` files) Affected files: - `scss/global/_*.scss` (3 files) - `scss/components/shared/_*.scss` (13 files) - `scss/components/actor/_*.scss` (14 files) - `scss/components/item/_*.scss` (3 files) - `scss/components/dice/_*.scss` (1 file) - `scss/utils/_*.scss` (variables, mixins, colors) For each file, check: - Are variables/mixins used by other files? → Export with `@forward` - Are variables/mixins imported from other files? → Import with `@use` and use namespace #### 3. Test Rollup configuration - The `rollup-plugin-styler` plugin must work with the new module system - If not: Evaluate alternative plugins (e.g., `@rollup/plugin-sass`, `vite-plugin-sass`) #### 4. Testing - Run build and check for errors - Compare generated CSS with previous CSS (should be identical) - Visual test in browser: All styles should work as before ### Migration Tools Sass provides an official migrator tool: ```bash pnpm exec sass-migrator module --migrate-deps scss/ds4.scss ``` **⚠️ Warning**: The tool cannot automatically handle all edge cases, especially: - Naming conflicts for variables - Global variables vs. modular encapsulated variables - Compatibility with build tools ### Challenges 1. **Namespace management**: Variables will no longer be global - Example: `$primary-color` becomes `colors.$primary-color` 2. **Rollup plugin compatibility**: `rollup-plugin-styler` may have issues with pure `@use` imports 3. **Breaking changes**: If the plugin is not compatible, we may need to adjust the build process ### Resources - [Sass Module System Documentation](https://sass-lang.com/documentation/at-rules/use/) - [Sass Migrator Tool](https://sass-lang.com/documentation/cli/migrator/) - [Migrating from @import](https://sass-lang.com/documentation/at-rules/import/#migrating-to-use) - [Deprecation Warning Documentation](https://sass-lang.com/d/import) ### Acceptance Criteria - [x] All `@import` statements are replaced with `@use`/`@forward` - [x] Build runs without deprecation warnings - [x] Generated CSS is identical to previous version - [x] All styles work correctly in the browser - [x] Temporary warning suppression is removed from `rollup.config.js` - [x] Documentation is updated (if SCSS development is documented) ### Estimated Effort Medium to high - depending on plugin compatibility and number of manual adjustments ### Context _No response_