{"id":20603372,"url":"https://github.com/metalsmith/sass","last_synced_at":"2026-01-05T01:21:20.908Z","repository":{"id":43702926,"uuid":"448713120","full_name":"metalsmith/sass","owner":"metalsmith","description":"A Metalsmith plugin to compile SASS/SCSS","archived":false,"fork":false,"pushed_at":"2025-07-15T10:28:25.000Z","size":1147,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-24T05:27:22.238Z","etag":null,"topics":["css","metalsmith","metalsmith-plugin","sass"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metalsmith.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null}},"created_at":"2022-01-17T00:58:35.000Z","updated_at":"2025-07-15T10:28:28.000Z","dependencies_parsed_at":"2024-02-22T02:29:40.032Z","dependency_job_id":"72746547-1378-4708-a858-d0abd1197b5d","html_url":"https://github.com/metalsmith/sass","commit_stats":{"total_commits":57,"total_committers":2,"mean_commits":28.5,"dds":0.01754385964912286,"last_synced_commit":"d50ece929c1c292c37dee596530ac4b107d038c5"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":"metalsmith/core-plugin","purl":"pkg:github/metalsmith/sass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fsass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fsass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fsass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fsass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metalsmith","download_url":"https://codeload.github.com/metalsmith/sass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fsass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28210167,"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","status":"online","status_checked_at":"2026-01-04T02:00:06.065Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["css","metalsmith","metalsmith-plugin","sass"],"created_at":"2024-11-16T09:17:05.303Z","updated_at":"2026-01-05T01:21:20.903Z","avatar_url":"https://github.com/metalsmith.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @metalsmith/sass\n\nA Metalsmith plugin to compile SASS/SCSS files\n\n[![metalsmith: core plugin][metalsmith-badge]][metalsmith-url]\n[![npm: version][npm-badge]][npm-url]\n[![ci: build][ci-badge]][ci-url]\n[![code coverage][codecov-badge]][codecov-url]\n[![license: MIT][license-badge]][license-url]\n\nCompile SASS/SCSS source \u0026 lib files to CSS using [dart-sass](https://sass-lang.com/dart-sass).\n\n## Features\n\n- Automatically compiles all .scss/.sass files in `Metalsmith.source()` and removes all `_partial.scss/sass` files from the output.\n- Uses sensible defaults according to `metalsmith.env('NODE_ENV')`.\n- Add files from outside the source dir with the `entries` option. Specify `'relative/to/dir/style.scss': 'relative/to/destination/style.css'` key-value pairs in the `entries` object for all root stylesheets.\n- Provides sourcemaps and access to all advanced [sass options](https://sass-lang.com/documentation/js-api/interfaces/Options) except async.\n- Compatible with [@metalsmith/postcss](https://github.com/metalsmith/postcss) (including sourcemaps)\n\n## Installation\n\nNPM:\n\n```\nnpm install @metalsmith/sass\n```\n\nYarn:\n\n```\nyarn add @metalsmith/sass\n```\n\n## Usage\n\nPass `@metalsmith/sass` to `metalsmith.use` :\n\n```js\nimport sass from '@metalsmith/sass'\nconst isDev = metalsmith.env('NODE_ENV') === 'development'\n\n// compile all scss/sass files in metalsmith.source()\nmetalsmith.use(sass()) // defaults\n\nmetalsmith.use(sass({  // explicit defaults\n  style:  isDev ? 'expanded' : 'compressed',\n  sourceMap: isDev,\n  sourceMapIncludeSources: isDev,\n  loadPaths: ['node_modules']\n  entries: {\n    // add scss entry points from\n   'lib/outside-source.scss': 'relative/to/dest.css'\n  }\n}))\n```\n\nIf `metalsmith.env('NODE_ENV')` is _explicitly_ set to development,`@metalsmith/sass` will automatically generate sourcemaps and will not minify the output.\n\n### Entries\n\nIf you had a blog project with 2 SCSS stylesheets, `index.scss` to be loaded everywhere, and `blogposts.scss` only on blog post pages:\n\n```plaintext\nmy-blog\n├── lib\n|   ├── index.scss\n│   └── _lib-partial.scss\n└── src\n    ├── blog.html\n    ├── index.html\n    └── css\n        ├── _in-source-partial.scss\n        └── blogposts.scss\n```\n\n...you could specify the following config:\n\n```js\nmetalsmith.use(\n  sass({\n    entries: {\n      'lib/index.scss': 'css/index.css'\n    }\n  })\n)\n```\n\n_Note: the keys in the `entries` option are *relative to `Metalsmith.directory`*, while the values are *relative to `Metalsmith.destination`*._\n\nWith this setup metalsmith will generate the following build:\n\n```plaintext\nbuild\n  ├── css\n  │   ├── blogposts.css\n  │   └── index.css\n  ├── blog.html\n  └── index.html\n```\n\nPartial `_in-source-partial.scss` is automatically removed from the build after compilation.\nWhen not explicitly specified in the config, in-source `.scss/.sass` files are added as entries `'\u003csource\u003e/file.scss': \u003cdest\u003e/file.css`.\nIf you want to move or rename the in-source SCSS entries in the build, specify them explicitly in the `entries` config. For example let's write the `blogpost.scss` to `css/blog/index.css` instead, without touching our source dir structure:\n\n```js\nmetalsmith.use(\n  sass({\n    entries: {\n      'lib/index.scss': 'css/index.css',\n      'src/blogposts.scss': 'css/blog/index.css'\n    }\n  })\n)\n```\n\nThe result:\n\n```plaintext\nbuild\n  ├── css\n  │   ├── index.css\n  │   └── blog\n  │       └── index.css\n  ├── blog.html\n  └── index.html\n```\n\n### @import/ @use partials\n\nSass partials are processed by [dart-sass](https://sass-lang.com/dart-sass). @metalsmith/sass will gracefully handle in-source partials, but they will be read into memory by Metalsmith. If you don't need to preprocess sass partials with any other metalsmith plugin you can save some disk reads by _storing partials outside the source directory_, eg:\n\n```plaintext\nmy-blog\n├── lib\n│   ├── _partial1.scss\n│   └── _partial2.scss\n└── src\n    └── css\n        └── index.scss\n```\n\n### Passing metadata to SASS files\n\nYou can pass metadata to SASS files inside `Metalsmith.source()` through front-matter in the file or global metadata. For example, let's pass metalsmith `theme` metadata to SASS and pre-compile with [@metalsmith/in-place](https://github.com/metalsmith/in-place) and [jstransformer-handlebars](https://github.com/jstransformers/jstransformer-handlebars) (notice the final `.hbs` extension):\n\n`index.scss.hbs`\n\n```scss\n---\nfontfamily: 'Arial, sans-serif'\n---\n$color-primary: {{ theme.color.primary }};\n$color-background: {{ theme.color.background }};\n\nbody {\n  font-family: {{ fontfamily }};\n  color: $color-primary;\n  background-color: $color-background;\n}\n```\n\nJust take care to run the in-place plugin before sass:\n\n```js\nimport Metalsmith from 'metalsmith'\nimport inPlace from '@metalsmith/in-place'\nimport sass from '@metalsmith/sass'\nimport { fileURLToPath } from 'url'\nimport { dirname } from 'path'\n\nconst __dirname = dirname(fileURLToPath(import.meta.url))\n\nMetalsmith(__dirname)\n  .metadata({\n    theme: {\n      color: {\n        primary: '#333444',\n        background: '#EEEFFF'\n      }\n    }\n  })\n  .use(inPlace({ transform: 'handlebars' }))\n  .use(sass())\n  .build((err) =\u003e {\n    if (err) throw err\n    console.log('Success!')\n  })\n```\n\n### Debug\n\nTo enable debug logs, set the `DEBUG` environment variable to `@metalsmith/sass*`:\n\n```js\nmetalsmith.env('DEBUG', '@metalsmith/sass*')\n```\n\nAlternatively you can set `DEBUG` to `@metalsmith/*` to debug all Metalsmith core plugins.\n\n### CLI usage\n\nTo use this plugin with the Metalsmith CLI, add `@metalsmith/sass` to the `plugins` key in your `metalsmith.json` file:\n\n```json\n{\n  \"plugins\": [\n    {\n      \"@metalsmith/sass\": {\n        \"style\": \"compressed\",\n        \"sourceMap\": false,\n        \"sourceMapIncludeSources\": false,\n        \"loadPaths\": [\"node_modules\"],\n        \"entries\": {\n          \"lib/scss/index.scss\": \"assets/styles.css\"\n        }\n      }\n    }\n  ]\n}\n```\n\n## Node compatibility\n\nThis plugin runs on Node \u003e= 14.18.0. If you need to compile sass/scss on earier Node versions, use [metalsmith-sass](https://github.com/stevenschobert/metalsmith-sass) which uses the (no longer canonical) lib-sass.\n\n## License\n\n[LGPL-3.0](LICENSE)\n\n[npm-badge]: https://img.shields.io/npm/v/@metalsmith/sass.svg\n[npm-url]: https://www.npmjs.com/package/@metalsmith/sass\n[ci-badge]: https://github.com/metalsmith/sass/actions/workflows/test.yml/badge.svg\n[ci-url]: https://github.com/metalsmith/sass/actions/workflows/test.yml\n[metalsmith-badge]: https://img.shields.io/badge/metalsmith-core_plugin-green.svg?longCache=true\n[metalsmith-url]: https://metalsmith.io\n[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/sass\n[codecov-url]: https://coveralls.io/github/metalsmith/sass\n[license-badge]: https://img.shields.io/github/license/metalsmith/sass\n[license-url]: LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Fsass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetalsmith%2Fsass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Fsass/lists"}