Dart Sass @use module compatibility with legacy @import consumers

Answer the question first

Yes – a library that adopts the Dart‑Sass module system can still be consumed by legacy @import consumers, but only if the public entry point contains no @use statements. The internal modules may use @use and @forward, and a thin wrapper file forwards the public API to the legacy consumers.

Confirmed facts

• Any file that contains @use cannot be @import-ed; Sass will throw an error.
• Files that contain only @forward can be @import-ed, but @forward is not understood by LibSass (node‑sass).
• Private identifiers (prefixed with _ or -) are exported by @forward unless you explicitly hide them.
• The safe boundary is a wrapper that only forwards public members; all @use statements must be confined to modules that are never imported directly.

How to implement it for this library

1. Keep all internal source files written with @use and @forward.
2. Create a top‑level wrapper, e.g. src/_wrapper.scss, that contains only @forward statements and no @use:

@forward "core";
@forward "components";

Optionally, rename or hide private members:

@forward "core" as core hide $internal-color;

Publish the wrapper as the single public entry point. Legacy consumers can @import "_wrapper";.

For projects that still use node‑sass, ship a separate legacy file that only uses @import:

// legacy.scss – node‑sass compatible
@import "core";
@import "components";

Document the two entry points: _wrapper.scss for Dart‑Sass and legacy.scss for node‑sass.

When node‑sass support is no longer required, deprecate legacy.scss and keep only the wrapper.

Boundary for exposing @forward members

The wrapper should only forward the API you want to expose. Use the :as and hide modifiers to keep private helpers out of the public surface.

Documentation strategy for dual‑consumer libraries

Most libraries ship two entry points during the transition: a Dart‑Sass‑only wrapper and a node‑sass‑compatible legacy file. This keeps the public API stable for both consumers while the internal codebase moves to the module system.

Missing diagnostic detail

Do you currently ship a single public entry point, or do you already have separate legacy files? Knowing that will help refine the wrapper strategy or confirm that a dual‑entry approach is necessary.