Registry / web-framework / node-sass-magic-importer

node-sass-magic-importer

library5.3.3jsnpmunverified

node-sass-magic-importer is a custom importer for node-sass that significantly extends its `@import` capabilities. It integrates several specialized functionalities, including selector-specific imports (allowing users to import only certain CSS selectors or nodes from a file, with optional renaming/transformation), automatic `node_modules` resolution without requiring full paths, and globbing support for importing multiple files with a single pattern (e.g., `scss/**/*.scss`). Additionally, it features de-duplication logic to prevent importing the same file multiple times, except when filters are explicitly applied. The current stable version is 5.3.3, and the package maintains an active release cadence for node-sass compatibility. Its primary differentiator is the consolidation of these advanced import features into a single, configurable plugin, streamlining complex Sass import strategies.

web-framework devops

npm install node-sass-magic-importer

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-SASS-MAGIC-IM

node-sass-magic-importer

web-frameworkjavascriptv5.3.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

magicImporter

✓ import magicImporter from 'node-sass-magic-importer'; // In usage: importer: magicImporter()

✗ const magicImporter = require('node-sass-magic-importer'); // In usage: importer: magicImporter

The default export is a function that, when called, returns the actual importer function compatible with node-sass. Ensure you call it (`magicImporter()`) when assigning it to the `importer` option.

default

✓ import magicImporter from 'node-sass-magic-importer';

✗ import { magicImporter } from 'node-sass-magic-importer';

The primary API is a default export, typically imported as `magicImporter`. There are no named exports for direct use as standalone importers; the default export provides the unified functionality.

This quickstart demonstrates how to set up `node-sass-magic-importer` with `node-sass` to leverage selector filtering from a node module (like Bootstrap) and glob importing for local components. It shows defining an importer, compiling Sass, and handling the output.

import * as sass from 'node-sass'; import magicImporter from 'node-sass-magic-importer'; import * as path from 'path'; import { promises as fs } from 'fs'; const scssContent = `@import '{ .btn, .btn-primary as .button-main } from ../node_modules/bootstrap/scss/buttons'; @import 'components/**/*.scss';`; const filePath = path.join(process.cwd(), 'styles.scss'); const componentPath = path.join(process.cwd(), 'components'); // Create dummy files for globbing and selective import demonstration async function setupDemoFiles() { await fs.mkdir(componentPath, { recursive: true }); await fs.writeFile(filePath, scssContent); await fs.writeFile(path.join(componentPath, 'header.scss'), '.header { color: blue; }'); await fs.writeFile(path.join(componentPath, 'footer.scss'), '.footer { color: red; }'); } async function compileSass() { await setupDemoFiles(); try { const result = await new Promise((resolve, reject) => { sass.render({ file: filePath, importer: magicImporter(), includePaths: [path.join(process.cwd(), 'node_modules')], outputStyle: 'expanded' }, (err, res) => { if (err) reject(err); else resolve(res); }); }); console.log('Compiled CSS:\n', result.css.toString()); // Expected output includes .btn, .button-main, .header, .footer } catch (error) { console.error('Sass compilation failed:', error); } finally { // Cleanup dummy files await fs.rm(filePath, { force: true }); await fs.rm(componentPath, { recursive: true, force: true }); } } compileSass();

Debug

Known issues

breakingThis package is built specifically for `node-sass`, which is considered deprecated and largely unmaintained in favor of `sass` (Dart Sass). Users should be aware that investing heavily in a `node-sass` based workflow may lead to future compatibility issues.

fix

Consider migrating to Dart Sass (the `sass` package) and exploring its built-in module system (`@use`, `@forward`) or alternative globbing solutions if `node-sass` becomes a blocker. There is no direct drop-in replacement for all magic-importer features in Dart Sass.

affects: >=1.0.0

breakingSupport for older Node.js versions was dropped in `v5.3.0`. The package now requires Node.js `>=6.11.1`.

fix

Ensure your Node.js environment is updated to version 6.11.1 or higher to use `node-sass-magic-importer` v5.3.0 and later.

affects: >=5.3.0

gotchaThe `importer` option for `node-sass` expects a function. `node-sass-magic-importer` exports a factory function that you must call to get the actual importer function.

fix

When configuring `node-sass`, ensure you pass `magicImporter()` (with parentheses) to the `importer` option, not `magicImporter` (without parentheses). Correct: `importer: magicImporter()`. Incorrect: `importer: magicImporter`.

affects: >=1.0.0

gotchaTypeScript resolution was fixed in v5.3.2. Older versions might have issues with type declarations.

fix

Upgrade to `node-sass-magic-importer` version 5.3.2 or later to ensure correct TypeScript type resolution.

affects: <5.3.2

Errors

Common errors & fixes

Error: `libsass` bindings not found. Try `npm rebuild node-sass`?

This error originates from `node-sass` itself, indicating a failure to compile or locate its native C++ bindings, often due to Node.js version mismatches or build environment issues.

fix

First, try `npm rebuild node-sass`. If that fails, ensure your Node.js version is compatible with your `node-sass` version (check `node-sass` documentation for supported Node versions), and that you have necessary build tools (like Python and C++ compiler) installed on your system.

TypeError: importer is not a function

The `importer` option in `node-sass.render` was assigned the `magicImporter` factory function directly instead of the function it returns.

fix

Change `importer: magicImporter` to `importer: magicImporter()`.

Error: File to import not found or unreadable:

This can occur if glob patterns are incorrect, if node_modules are not correctly resolved, or if the `includePaths` option in `node-sass.render` is missing required directories.

fix

Verify your glob patterns are correct and match existing files. Ensure `includePaths` includes your `node_modules` directory (`path.join(process.cwd(), 'node_modules')`) if you're importing packages from there. Also check for typos in file paths or selector filters.

Upgrade

Version history

5.3.3latest on npm

Audit

Dependencies

node-sassrequiredThis package is a custom importer specifically designed for node-sass. It will not work with Dart Sass.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/maoberlehner/node-sass-magic-importer ↗

packagehttps://www.npmjs.com/package/node-sass-magic-importer ↗