A plugin to process Sass for Eleventy
MIT License
As a dependency:
npm i eleventy-plugin-dart-sass
As a devDependency:
npm i --dev eleventy-plugin-dart-sass
This is a plugin for Eleventy and requires that it also be installed in your project.
In your site's .eleventy.js
file:
eleventyConfig.addPlugin(require("eleventy-plugin-dart-sass"), opts)
The opts
object can contain:
Name | Description | Default |
---|---|---|
domainName | Used by Sass to build source maps and understand links for your templates. | "http://localhost:8080" |
includePaths | An array of paths to include for checking Sass files to watch and build from. | [" ** /*.{scss,sass}", "!node_modules/ ** "] |
sassLocation | Absolute path to your Sass files (usually in your Eleventy site project) | ${absoluteDirectory/path/to/eleventy}/src/_sass/ |
sassIndexFile | The main file at the base of your Sass file structure. The one with nothing but @use statements. | "_index.sass" |
outDir | The directory Eleventy renders your site into. | ${absoluteDirectory/path/to/eleventy}/docs |
outPath | The file path from the base of your site's render target folder (the outDir above) | "/assets/css/" |
outFileName | Name you wish to render your main Sass files out to. (The output file generated from sassIndexFile .) Does not include file name. |
"style" |
sourceMap | If you wish to render source maps, be a good citizen of the web and leave it true! | true |
perTemplateFiles | If you wish to split the rendering of your styles into per-template sub files, here's where you pass the prefix. | false |
cacheBreak | Pass a string here to add a cache-break paramater to the rendering of CSS URLs in your templates. | false |
outputStyle | What style of Sass compression you want to output files in. | "compressed" |
watchSass | Use this bool to instruct Eleventy to include your Sass directory from sassLocation in the set of folders to watch. |
true |
This plugin builds default paths as follows:
sassLocation
:
path.normalize(
path.join(__dirname, "../../../", "src/_sass/")
)
outDir
:
path.normalize(path.join(__dirname, "../../../", "docs")),
This assumes that the plugin resides in the node_modules
folder of your Eleventy
website project. It assumes that your render path for your Eleventy
site is docs
within your project folder. Finally it assumes that your project sits its Sass files in src/_sass
.
The defaults assume that, after this plugin is added to the project, an Eleventy project has a minimum folder structure with these types of files in it (posts
folder is common, but optional):
├── node_modules
| ├── eleventy-plugin-dart-sass
├── src
| ├── _sass
| | ├── _index.sass
| | ├── more-style.scss
| | ├── included.sass
| | └── template-post.sass
| └── posts
├── docs
└── .eleventy.js
You can pass any path into the configuration you'd like. If so, you can free form your project directory structure to work however you'd like.
If you pass your own path into the configuration object for either outDir
or sassLocation
or both the plugin won't normalize that path for you.
You must pass absolute paths into these option properties
For reasons I've yet to figure out, source maps only work in most browsers with full URLs. Relative URLs seem to fail on most browsers. Additionally, we provide a Eleventy shortcode that allows you to pull rendered CSS URLs into your templates. If you do not want to use either of these features you can ignore the domainName
property or pass it an empty string. You should have source maps though. It's the right thing to do!
The following options are directly passed into Dart Sass and you can read about them there:
sourceMap
.The Eleventy Dart Sass plugin provides you with a nifty tool to practice CSS code splitting.
This lets you load template-specific CSS on the specific templates that needs it, shrinking the overall amount the user needs to download at one time.
If you pass a value to perTemplateFiles
, it is considered as a prefix for files in your Sass folder that should be rendered as separate files from your main _index.sass
file.
So if you pass perTemplateFiles
the value of template-
and have a project structure like this:
├── node_modules
| ├── eleventy-plugin-dart-sass
├── src
| ├── _sass
| | ├── _index.sass
| | ├── more-style.scss
| | ├── included.sass
| | └── template-post.sass
| └── posts
├── docs
└── .eleventy.js
with the default settings in the plugin, after your rendering process is complete, your file structure will look as follows:
├── node_modules
| ├── eleventy-plugin-dart-sass
├── src
| ├── _sass
| | ├── _index.sass
| | ├── more-style.scss
| | ├── included.sass
| | └── template-post.sass
| └── posts
├── docs
| ├── assets
| | ├── css
| | | ├── style.css
| | | ├── style.css.map
| | | ├── template-post.css
| | | └── template-post.css.map
└── .eleventy.js
The configuration of this plugin will cause it to rebuild Sass files whenever a build process is initiated. However, your Sass file may not trigger rebuild of the Sass files on watch
mode if the Sass files are not in the set of target folders Eleventy is watching. When watchSass
is set to true
it takes your sassLocation
property value and adds it to Eleventy's watch targets using addWatchTarget
.
The cacheBreak
property can take a value that will be passed into the shortcode at build time to be appended to your CSS files. This is useful if you set it to cacheBreak: "?cb=" + Date.now()
. Now the date in milliseconds will be added as a URL parameter to all your CSS files that you set in templates using the Dart-Sass shortcode.
This plugin provides an Eleventy shortcode named sassFile
to allow you to call your newly created CSS URLs in your templates. The shortcode takes three arguments: template
, append
, and id
.
The template argument is passed when you are rendering a template-specific CSS file. It takes the passed argument and appends perTemplateFiles
from the plugin configuration into the CSS URL name.
The Append argument allows you to add an arbitrary string to the end of the URL. It is anticipated that you will append URL params, if you need them. You may want to do so like "?somArg=abc"
.
If you want to assign an ID value to the link
HTML tag.
Here's an example from a Nunjucks template file of how this might be used:
{% sassFile false, "?v=" + site.github.build_revision %}
{% if templateName %}
{% sassFile templateName, "?v=" + site.github.build_revision, "template-post-stylesheet" %}
{% endif %}
And this will render as:
<link rel="stylesheet" href="https://fightwithtools.dev/assets/css/style.css?v=1628665517" id="">
<link rel="stylesheet" href="https://fightwithtools.dev/assets/css/template-post.css?v=1628665517" id="template-post-stylesheet">
This plugin's dependency on Sass is currently set to "~1.45.1"
. This means only patch updates will be used, but no changes to Sass beyond version 1.45
. This is because of their intent to depreciate renderSync
which is currently in use in this plugin. I don't anticipate this causing issues, however, it is on the to-do list to fix. PRs that resolve this problem would be appreciated!
Works with versions of Eleventy >=0.11
This plugin is maintained in its GitHub repository. All PRs and Issues filed to that repo are welcome and will be reviewed. The GitHub repo includes a test suite and it is recommended that you run tests before filing a PR to make sure you maintain the basic functionality of this plugin.