{"id":16117977,"url":"https://github.com/wessberg/sass-extended-importer","last_synced_at":"2025-03-18T10:31:07.138Z","repository":{"id":62354869,"uuid":"166832291","full_name":"wessberg/sass-extended-importer","owner":"wessberg","description":"A Custom Sass Import Resolver with included support for Node Module Resolution and additional file extensions","archived":false,"fork":false,"pushed_at":"2023-08-08T22:58:50.000Z","size":291,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T19:46:33.752Z","etag":null,"topics":["algorithm","css","import","importer","node-module-resolution","resolve","sass","scss"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wessberg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"wessberg","patreon":"wessberg"}},"created_at":"2019-01-21T14:59:08.000Z","updated_at":"2022-06-17T19:52:33.000Z","dependencies_parsed_at":"2024-06-19T02:49:59.469Z","dependency_job_id":"34d1fe89-b1f9-4fac-944a-85cd451ddc22","html_url":"https://github.com/wessberg/sass-extended-importer","commit_stats":null,"previous_names":["wessberg/sass-extended-import-resolve"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wessberg%2Fsass-extended-importer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wessberg%2Fsass-extended-importer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wessberg%2Fsass-extended-importer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wessberg%2Fsass-extended-importer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wessberg","download_url":"https://codeload.github.com/wessberg/sass-extended-importer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244201758,"owners_count":20415143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","css","import","importer","node-module-resolution","resolve","sass","scss"],"created_at":"2024-10-09T20:48:09.391Z","updated_at":"2025-03-18T10:31:06.744Z","avatar_url":"https://github.com/wessberg.png","language":"TypeScript","funding_links":["https://github.com/sponsors/wessberg","https://patreon.com/wessberg","https://www.patreon.com/bePatron?u=11315442"],"categories":[],"sub_categories":[],"readme":"\u003c!-- SHADOW_SECTION_LOGO_START --\u003e\n\n\u003cdiv\u003e\u003cimg alt=\"Logo\" src=\"https://raw.githubusercontent.com/wessberg/sass-extended-importer/master/documentation/asset/logo.png\" height=\"200\"   /\u003e\u003c/div\u003e\n\n\u003c!-- SHADOW_SECTION_LOGO_END --\u003e\n\n\u003c!-- SHADOW_SECTION_DESCRIPTION_SHORT_START --\u003e\n\n\u003e A Custom Sass Import Resolver with included support for Node Module Resolution, additional file extensions, and path aliases/path mapping\n\n\u003c!-- SHADOW_SECTION_DESCRIPTION_SHORT_END --\u003e\n\n\u003c!-- SHADOW_SECTION_BADGES_START --\u003e\n\n\u003ca href=\"https://npmcharts.com/compare/sass-extended-importer?minimal=true\"\u003e\u003cimg alt=\"Downloads per month\" src=\"https://img.shields.io/npm/dm/sass-extended-importer.svg\"    /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/sass-extended-importer\"\u003e\u003cimg alt=\"NPM version\" src=\"https://badge.fury.io/js/sass-extended-importer.svg\"    /\u003e\u003c/a\u003e\n\u003cimg alt=\"Dependencies\" src=\"https://img.shields.io/librariesio/github/wessberg%2Fsass-extended-importer.svg\"    /\u003e\n\u003ca href=\"https://github.com/wessberg/sass-extended-importer/graphs/contributors\"\u003e\u003cimg alt=\"Contributors\" src=\"https://img.shields.io/github/contributors/wessberg%2Fsass-extended-importer.svg\"    /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/prettier/prettier\"\u003e\u003cimg alt=\"code style: prettier\" src=\"https://img.shields.io/badge/code_style-prettier-ff69b4.svg\"    /\u003e\u003c/a\u003e\n\u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-yellow.svg\"    /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.patreon.com/bePatron?u=11315442\"\u003e\u003cimg alt=\"Support on Patreon\" src=\"https://img.shields.io/badge/patreon-donate-green.svg\"    /\u003e\u003c/a\u003e\n\n\u003c!-- SHADOW_SECTION_BADGES_END --\u003e\n\n\u003c!-- SHADOW_SECTION_DESCRIPTION_LONG_START --\u003e\n\n## Description\n\n\u003c!-- SHADOW_SECTION_DESCRIPTION_LONG_END --\u003e\n\nThis is an implementation of the [Sass Import Resolve algorithm](https://github.com/sass/dart-sass/blob/0f7f9e69a72e612412b51bfa2fe1384f778e2821/lib/src/importer/utils.dart), with added support for [Node Module Resolution](https://nodejs.org/api/modules.html#modules_all_together), and path mapping/path aliasing.\n\nAt the moment, without this Custom importer, to import files via Node Module Resolution, Sass library creators and consumers can:\n\n- Ship `.scss`, `.sass`, or `.css` files via `node_modules`, and let consumers depend on files directly, - but not support hoisted dependencies/monorepos.\n- Use [`Eyeglass`](https://github.com/sass-eyeglass/eyeglass)\n\nOne major use case for this library is to support path mapping, which can be useful for many things, includiong simplifying import paths or dividing packages in a monorepo.\n\nThis implementation follows the convention of existing tooling and similar solutions that paths with a leading `~` will be resolved via [Node Module Resolution](https://nodejs.org/api/modules.html#modules_all_together).\n\n\u003c!-- SHADOW_SECTION_FEATURES_START --\u003e\n\n### Features\n\n\u003c!-- SHADOW_SECTION_FEATURES_END --\u003e\n\n\u003c!-- SHADOW_SECTION_FEATURE_IMAGE_START --\u003e\n\n\u003c!-- SHADOW_SECTION_FEATURE_IMAGE_END --\u003e\n\n\u003c!-- SHADOW_SECTION_BACKERS_START --\u003e\n\n## Backers\n\n[Become a sponsor/backer](https://github.com/wessberg/sass-extended-importer?sponsor=1) and get your logo listed here.\n\n| \u003ca href=\"https://changelog.me\"\u003e\u003cimg alt=\"Trent Raymond\" src=\"https://avatars.githubusercontent.com/u/1509616?v=4\" height=\"70\"   /\u003e\u003c/a\u003e | \u003ca href=\"https://scrubtheweb.com/computers/programming/1\"\u003e\u003cimg alt=\"scrubtheweb\" src=\"https://avatars.githubusercontent.com/u/41668218?v=4\" height=\"70\"   /\u003e\u003c/a\u003e |\n| -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Trent Raymond](https://changelog.me)                                                                                                  | [scrubtheweb](https://scrubtheweb.com/computers/programming/1)                                                                                                   |\n\n### Patreon\n\n\u003ca href=\"https://www.patreon.com/bePatron?u=11315442\"\u003e\u003cimg alt=\"Patrons on Patreon\" src=\"https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Dwessberg%26type%3Dpatrons\"  width=\"200\"  /\u003e\u003c/a\u003e\n\n\u003c!-- SHADOW_SECTION_BACKERS_END --\u003e\n\n\u003c!-- SHADOW_SECTION_TOC_START --\u003e\n\n## Table of Contents\n\n- [Description](#description)\n  - [Features](#features)\n- [Backers](#backers)\n  - [Patreon](#patreon)\n- [Table of Contents](#table-of-contents)\n- [Install](#install)\n  - [npm](#npm)\n  - [Yarn](#yarn)\n  - [pnpm](#pnpm)\n- [Usage](#usage)\n  - [Usage with sass](#usage-with-sass)\n  - [Usage with node-sass](#usage-with-node-sass)\n  - [Resolving files within Node Modules](#resolving-files-within-node-modules)\n    - [Customizing the prefix](#customizing-the-prefix)\n  - [Path mapping/aliasing](#path-mappingaliasing)\n  - [Adjusting allowed extensions](#adjusting-allowed-extensions)\n  - [Customizing the file system](#customizing-the-file-system)\n  - [Usage with other tools and libraries](#usage-with-other-tools-and-libraries)\n- [Contributing](#contributing)\n- [Maintainers](#maintainers)\n- [FAQ](#faq)\n- [License](#license)\n\n\u003c!-- SHADOW_SECTION_TOC_END --\u003e\n\n\u003c!-- SHADOW_SECTION_INSTALL_START --\u003e\n\n## Install\n\n### npm\n\n```\n$ npm install sass-extended-importer --save-dev\n```\n\n### Yarn\n\n```\n$ yarn add sass-extended-importer --dev\n```\n\n### pnpm\n\n```\n$ pnpm add sass-extended-importer --save-dev\n```\n\n\u003c!-- SHADOW_SECTION_INSTALL_END --\u003e\n\n\u003c!-- SHADOW_SECTION_USAGE_START --\u003e\n\n## Usage\n\n\u003c!-- SHADOW_SECTION_USAGE_END --\u003e\n\n### Usage with sass\n\nTo use it with the primary [`sass`](https://github.com/sass/dart-sass) package (dart-sass), simply import the `createImporter` function from this package and invoke it with the options you want to provide.\nThen pass it to `sass` is an import resolver:\n\n```typescript\nimport {createImporter} from \"sass-extended-importer\";\nimport sass from \"sass\";\n\nsass({\n\tfile: \"/path/to/your/file.scss\",\n\timporter: createImporter({\n\t\t// options\n\t})\n});\n```\n\n### Usage with node-sass\n\nTo use it with [`node-sass`](https://github.com/sass/node-sass), simply import the `createImporter` function from this package and invoke it with the options you want to provide.\nThen pass it to `node-sass` is an import resolver:\n\n```typescript\nimport {createImporter} from \"sass-extended-importer\";\nimport sass from \"node-sass\";\n\nsass({\n\tfile: \"/path/to/your/file.scss\",\n\timporter: createImporter({\n\t\t// options\n\t})\n});\n```\n\n### Resolving files within Node Modules\n\nPrefix the path with a `~` to indicate that the Node Module Resolution algorithm should be used:\n\n```scss\n@import \"~my-library\";\n```\n\nThe resolve function will use [Node Module Resolution](https://nodejs.org/api/modules.html#modules_all_together) to find the library, and then look at the `main` property within the related `package.json` file.\nIf it points to a file, for example `index.js`, for which there is an identically named file with an extension of `.scss`, `.sass` , or `.css`, or if the `main`\nproperty directly points to a file with a supported extension, that file will be resolved. Alternatively, if the main property is left out, it will default to looking for a file called `index` with one of the supported extensions directly within the package folder.\n\nThis means that all of the following examples will work:\n\n```scss\n// Uses the package.json file's main property to look for a file with a supported extension.\n// Defaults to looking for a file named `index` with a supported extension\n@import \"~my-library\";\n\n// Specifically looks for a file called 'index' inside the package folder, with a supported extension\n@import \"~my-library/index\";\n\n// Specifically looks for a file with the filename `index.scss`\n@import \"~my-library/index.scss\";\n\n// Looks inside the /foo folder from the package folder and for a file called `bar` with a supported extension\n// (or if bar is a folder, a file within it called `index` with a supported extension)\n@import \"~my-library/foo/bar\";\n```\n\n#### Customizing the prefix\n\nThe default prefix of `~` (tilde) is a convention used by several popular tools and is the general recommendation. However, you can customize it with the `nodeModuleResolutionPrefix` option for the importer:\n\n```typescript\nimport {createImporter} from \"sass-extended-importer\";\nimport sass from \"sass\";\n\nsass({\n\t// ...\n\timporter: createImporter({\n\t\t// Use # instead of ~\n\t\tnodeModuleResolutionPrefix: \"#\"\n\t})\n});\n```\n\n### Path mapping/aliasing\n\nYou can use path mapping to map import paths to other import paths.\nThis can be useful to simplify import statements, or if you use sass/scss/css in combination with a build pipeline that performs path mapping on your other application- or library code.\nFor example, you might be using TypeScript's path mapping feature, and want to make sure the same paths are supported inside the sass/scss/css files you're importing from there.\nYou can customize it with the `paths` option for the importer:\n\n```typescript\nimport {createImporter} from \"sass-extended-importer\";\nimport sass from \"sass\";\n\nsass({\n\t// ...\n\timporter: createImporter({\n\t\tpaths: {\n\t\t\t\"my-alias\": [\"../other-folder/src/index.scss\"],\n\t\t\t\"my-alias/*\": [\"../other-folder/src/*\"]\n\t\t}\n\t})\n});\n```\n\nThis allows you do write styles such as:\n\n```scss\n@import \"my-alias/foo\";\n```\n\nWhich will actually be mapped to `../other-folder/src/foo.scss`.\n\n### Adjusting allowed extensions\n\nYou can alter what kind of extensions that can be resolved via the `extensions` option for the importer:\n\n```typescript\nimport {createImporter} from \"sass-extended-importer\";\nimport sass from \"sass\";\n\nsass({\n\t// ...\n\timporter: createImporter({\n\t\t// Use # instead of ~\n\t\textensions: [\".myextension\", \".foo\", \".bar\"]\n\t})\n});\n```\n\n### Customizing the file system\n\nIf you use a virtual file system, such as one that exists within memory, you can pass it in as the `fileSystem` option for the importer. If you don't, it defaults to using the `fs` module:\n\n```typescript\nimport {createImporter} from \"sass-extended-importer\";\nimport sass from \"sass\";\nimport path from \"path\";\nimport {createFsFromVolume, Volume} from \"memfs\";\n\nconst volume = new Volume();\n\nvol.mkdirSync(\"/my/directory\", {recursive: true});\nvol.writeFileSync(\"/my/directory/foo.scss\", \"p {color: red}\");\nconst fileSystem = createFsFromVolume(vol);\n\nsass({\n\t// ...\n\timporter: createImporter({\n\t\t// Use another file system\n\t\tfileSystem\n\t})\n});\n```\n\n### Usage with other tools and libraries\n\nThe resolve algorithm implemented by this library is also exported as as helper function, `resolve`, that can be used outside of just as a Custom Importer for Sass.\nTo use it directly, simply import `resolve`:\n\n```typescript\nimport {resolve} from \"sass-extended-importer\";\n\nresolve(\"~my-library\", {cwd: \"/path/to/directory\"});\n```\n\n\u003c!-- SHADOW_SECTION_CONTRIBUTING_START --\u003e\n\n## Contributing\n\nDo you want to contribute? Awesome! Please follow [these recommendations](./CONTRIBUTING.md).\n\n\u003c!-- SHADOW_SECTION_CONTRIBUTING_END --\u003e\n\n\u003c!-- SHADOW_SECTION_MAINTAINERS_START --\u003e\n\n## Maintainers\n\n| \u003ca href=\"mailto:frederikwessberg@hotmail.com\"\u003e\u003cimg alt=\"Frederik Wessberg\" src=\"https://avatars2.githubusercontent.com/u/20454213?s=460\u0026v=4\" height=\"70\"   /\u003e\u003c/a\u003e                                                                |\n| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Frederik Wessberg](mailto:frederikwessberg@hotmail.com)\u003cbr\u003e\u003cstrong\u003eTwitter\u003c/strong\u003e: [@FredWessberg](https://twitter.com/FredWessberg)\u003cbr\u003e\u003cstrong\u003eGithub\u003c/strong\u003e: [@wessberg](https://github.com/wessberg)\u003cbr\u003e_Lead Developer_ |\n\n\u003c!-- SHADOW_SECTION_MAINTAINERS_END --\u003e\n\n\u003c!-- SHADOW_SECTION_FAQ_START --\u003e\n\n## FAQ\n\n\u003c!-- SHADOW_SECTION_FAQ_END --\u003e\n\n\u003c!-- SHADOW_SECTION_LICENSE_START --\u003e\n\n## License\n\nMIT © [Frederik Wessberg](mailto:frederikwessberg@hotmail.com) ([@FredWessberg](https://twitter.com/FredWessberg)) ([Website](https://github.com/wessberg))\n\n\u003c!-- SHADOW_SECTION_LICENSE_END --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwessberg%2Fsass-extended-importer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwessberg%2Fsass-extended-importer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwessberg%2Fsass-extended-importer/lists"}