372 lines
14 KiB
Markdown
372 lines
14 KiB
Markdown
|
||
|
||
|
||
[![Build Status][travis-image]][travis-url]
|
||
|
||
A plugin for [esbuild](https://esbuild.github.io/) to handle Sass & SCSS files.
|
||
|
||
### Features
|
||
* **PostCSS** & **CSS modules**
|
||
* support for **constructable stylesheet** to be used in custom elements or `dynamic style` to be added to the html page
|
||
* uses the **new [Dart Sass](https://www.npmjs.com/package/sass) Js API**.
|
||
* caching
|
||
* **url rewriting**
|
||
* pre-compiling (to add **global resources** to the sass files)
|
||
|
||
### Breaking Changes
|
||
* `type` has been simplified and now accepts only a string. If you need different types in a project [you can use more
|
||
than one instance](https://github.com/glromeo/esbuild-sass-plugin/issues/60) of the plugin.
|
||
You can have a look at the [**multiple** fixture](https://github.com/glromeo/esbuild-sass-plugin/blob/main/test/fixture/multiple)
|
||
for an example where **lit CSS** and **CSS modules** are both used in the same app
|
||
* The support for [node-sass](https://github.com/sass/node-sass) has been removed and for good.
|
||
Sadly, node-sass is at a dead end and so it's 1.x.
|
||
* `transform` now is expected to send back the CSS text in contents and anything that has to be default exported in `pluginData`.
|
||
|
||
### Install
|
||
|
||
```console
|
||
$ npm i esbuild-sass-plugin
|
||
```
|
||
|
||
### Usage
|
||
|
||
Just add it to your esbuild plugins:
|
||
|
||
```javascript
|
||
import {sassPlugin} from 'esbuild-sass-plugin'
|
||
|
||
await esbuild.build({
|
||
...
|
||
plugins: [sassPlugin()]
|
||
})
|
||
```
|
||
|
||
### Options
|
||
|
||
You can pass a series of **options** to the plugin that are a superset of Sass
|
||
[compile string options](https://sass-lang.com/documentation/js-api/interfaces/StringOptionsWithImporter). \
|
||
The following are the options specific to the plugin with their defaults whether provided:
|
||
|
||
| Option | Type | Default |
|
||
|---------------|---------------------------------------------------------|-----------------------------------------|
|
||
| filter | regular expression (in Go syntax) | <code>/\.(s[ac]ss|css)$/</code> |
|
||
| type | `"css"`<br/>`"style"`<br/>`"lit-css"`<br/>`"css-text"` | `"css"` |
|
||
| cache | boolean or Map | `true` (there is one Map per namespace) |
|
||
| transform | function | |
|
||
| [loadPaths](https://sass-lang.com/documentation/js-api/interfaces/Options#loadPaths) | string[] | [] |
|
||
| precompile | function | |
|
||
| importMapper | function | |
|
||
| cssImports | boolean | false |
|
||
| nonce | string | |
|
||
| prefer | string | preferred package.json field |
|
||
| quietDeps | boolean | false |
|
||
|
||
Two main options control the plugin: `filter` which has the same meaning of filter in [esbuild](https://esbuild.github.io/plugins/#on-load)
|
||
allowing to select the URLs handled by a plugin instance and then `type` that's what specifies how the css should be rendered and imported.
|
||
|
||
### `filter`
|
||
The default filter is quite simple but also quite permissive. When specifying a custom regex bear in mind that this
|
||
is in [Go syntax](https://pkg.go.dev/regexp/syntax)
|
||
|
||
> If you have URLs in your imports and you want the plugin to ignore them you can't just a filter expression like:
|
||
`/^(?!https?:).*\.(s[ac]ss|css)$/` because *Go regex engine doesn't support lookarounds* but you can use
|
||
> **esbuild**'s `external` option to ignore these imports or try a [solution like this one](https://esbuild.github.io/plugins/#on-resolve).
|
||
|
||
You can try to list multiple plugin instances in order so that the most specific RegEx come first:
|
||
```javascript
|
||
await esbuild.build({
|
||
...
|
||
plugins: [
|
||
sassPlugin({
|
||
filter: /\.module\.scss$/,
|
||
transform: postcssModules()
|
||
}),
|
||
sassPlugin({
|
||
filter: /\.scss$/
|
||
}),
|
||
],
|
||
...
|
||
})
|
||
```
|
||
|
||
### `type`
|
||
|
||
The example in [Usage](#usage) uses the default type `css` and will use esbuild CSS loader so your transpiled Sass
|
||
will be in `index.css` alongside your bundle.
|
||
|
||
In all other cases `esbuild` won't process the CSS content which instead will be handled by the plugin.
|
||
> if you want `url()` resolution or other processing you have to use `postcss` like in [this example](https://github.com/glromeo/esbuild-sass-plugin/issues/92#issuecomment-1219209442)
|
||
|
||
**NOTE:** Since version `2.7.0` the `css` type works also with postcss, CSS modules and more in general
|
||
with any transformation function by keeping an internal cache of CSS chunks (virtual CSS files)
|
||
importing them in the module wrapping the contents
|
||
|
||
#### `type: "style"`
|
||
In this mode the stylesheet will be in the javascript bundle
|
||
and will be dynamically added to the page when the bundle is loaded.
|
||
|
||
#### `type: "css-text"`
|
||
You can use this mode if you want to use the resulting css text as a string import
|
||
|
||
```javascript
|
||
await esbuild.build({
|
||
...
|
||
plugins: [sassPlugin({
|
||
type: "css-text",
|
||
... // for the options availanle look at 'SassPluginOptions' in index.ts
|
||
})]
|
||
})
|
||
```
|
||
|
||
...and in your module do something like
|
||
|
||
```javascript
|
||
import cssText from './styles.scss'
|
||
|
||
customElements.define('hello-world', class HelloWorld extends HTMLElement {
|
||
constructor() {
|
||
super();
|
||
this.attachShadow({mode: 'open'});
|
||
this.sheet = new CSSStyleSheet();
|
||
this.sheet.replaceSync(cssText);
|
||
this.shadowRoot.adoptedStyleSheets = [this.sheet];
|
||
}
|
||
}
|
||
```
|
||
|
||
#### `type: "lit-css"`
|
||
Or you can import a **lit-element** css result using `type: "lit-css"`
|
||
|
||
```javascript
|
||
import styles from './styles.scss'
|
||
|
||
@customElement("hello-world")
|
||
export default class HelloWorld extends LitElement {
|
||
|
||
static styles = styles
|
||
|
||
render() {
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
Look in `test/fixtures` folder for more usage examples.
|
||
|
||
### `cache`
|
||
The cache is enabled by default and can be turned off with `cache: false`.
|
||
Each plugin instance creates and maintain its own cache (as a Map) and this cache lives for the duration of the build.
|
||
If you want to pass a Map to preserve the cache amongst subsequent builds bear in mind that sharing the very same cache
|
||
between different instances might work just fine or it might lead to issues if the contents are incompatible.
|
||
> If you are not sure of what to do just keep a separate Map for each plugin instance.
|
||
|
||
### `cssImports`
|
||
when this is set to `true` the plugin rewrites the node-modules relative URLs starting with the `~` prefix so that
|
||
esbuild can resolve them similarly to what `css-loader` does.
|
||
> Although this practice is [kind of deprecated nowadays](https://webpack.js.org/loaders/sass-loader/#resolving-import-at-rules)
|
||
> some packages out there still use this notation (e.g. `formio`)
|
||
> \
|
||
> so I added this feature to help in cases [like this one](https://github.com/glromeo/esbuild-sass-plugin/issues/74).
|
||
|
||
### `nonce`
|
||
in presence of Content-Security-Policy
|
||
[(CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src)
|
||
the `nonce` option allows to specify the nonce attribute for the dynamically generated `<style>`
|
||
|
||
If the `nonce` string is a field access starting with `window`, `process` or `globalThis` it is left in the code without quotes.
|
||
```javascript
|
||
sassPlugin({
|
||
type: 'style',
|
||
nonce: 'window.__esbuild_nonce__'
|
||
})
|
||
```
|
||
This allows to define it globally or to leave it for a subsequent build to resolve it using [esbuild define](https://esbuild.github.io/api/#define).
|
||
```javascript
|
||
define: {'window.__esbuild_nonce__': '"12345"'}
|
||
```
|
||
|
||
### `prefer`
|
||
when this option is specified it allows to import npm packages which have `sass` or `style` fields preferring those to `main`.
|
||
|
||
> **NOTE**: This is an experimental feature
|
||
> * it replaces the internal use of `require.resolve` with browserify `resolve.sync`
|
||
> * it only applies to import prefixed by `~`
|
||
|
||
### `importMapper`
|
||
|
||
A function to customize/re-map the import path, both `import` statements in JavaScript/TypeScript code and `@import`
|
||
in Sass/SCSS are covered.
|
||
You can use this option to re-map import paths like tsconfig's `paths` option.
|
||
|
||
e.g. given this `tsconfig.json` which maps image files paths
|
||
|
||
```json
|
||
{
|
||
"compilerOptions": {
|
||
"baseUrl": ".",
|
||
"paths": {
|
||
"@img/*": [
|
||
"./assets/images/*"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
now you can resolve these paths with `importMapper`
|
||
|
||
```javascript
|
||
await esbuild.build({
|
||
...,
|
||
plugins: [sassPlugin({
|
||
importMapper: (path) => path.replace(/^@img\//, './assets/images/')
|
||
})]
|
||
})
|
||
```
|
||
|
||
### `precompile`
|
||
|
||
#### - Rewriting relative `url(...)`s
|
||
If your sass reference resources with relative urls (see [#48](https://github.com/glromeo/esbuild-sass-plugin/issues/48))
|
||
esbuild will struggle to rewrite those urls because it doesn't have idea of the imports that the Sass compiler
|
||
has gone through. Fortunately the new importer API allows to rewrite those relative URLs in absolute ones which
|
||
then esbuild will be able to handle.
|
||
|
||
Here is an example of how to do the `url(...)` rewrite ([make sure to handle `\` in *Windows*](https://github.com/glromeo/esbuild-sass-plugin/issues/58))
|
||
```javascript
|
||
const path = require('path')
|
||
|
||
await esbuild.build({
|
||
...,
|
||
plugins: [sassPlugin({
|
||
precompile(source, pathname) {
|
||
const basedir = path.dirname(pathname)
|
||
return source.replace(/(url\(['"]?)(\.\.?\/)([^'")]+['"]?\))/g, `$1${basedir}/$2$3`)
|
||
}
|
||
})]
|
||
})
|
||
```
|
||
|
||
#### - Globals and other Shims (like sass-loader's additionalData)
|
||
Look for a complete example in the [precompile](https://github.com/glromeo/esbuild-sass-plugin/tree/main/test/fixture/precompile) fixture.
|
||
|
||
Prepending a variable for a specific `pathname`:
|
||
```javascript
|
||
const context = { color: "blue" }
|
||
|
||
await esbuild.build({
|
||
...,
|
||
plugins: [sassPlugin({
|
||
precompile(source, pathname) {
|
||
const prefix = /\/included\.scss$/.test(pathname) ? `
|
||
$color: ${context.color};
|
||
` : env
|
||
return prefix + source
|
||
}
|
||
})]
|
||
})
|
||
```
|
||
|
||
Prepending an `@import` of globals file only for the root file that triggered the compilation (to avoid nested files from importing it again):
|
||
```javascript
|
||
const context = { color: "blue" }
|
||
|
||
await esbuild.build({
|
||
...,
|
||
plugins: [sassPlugin({
|
||
precompile(source, pathname, isRoot) {
|
||
return isRoot ? `@import '/path/to/globals.scss';\n${source}` : source
|
||
}
|
||
})]
|
||
})
|
||
```
|
||
|
||
### `transform`
|
||
|
||
```typescript
|
||
async (this: SassPluginOptions, css: string, resolveDir?: string) => Promise<string>
|
||
```
|
||
|
||
It's a function which will be invoked before passing the css to esbuild or wrapping it in a module.\
|
||
It can be used to do **PostCSS** processing and/or to create **modules** like in the following examples.
|
||
|
||
> **NOTE:** Since `v1.5.0` transform can return either a string or an esbuild `LoadResult` object. \
|
||
> This is what `postcssModules` uses to pass Javascript modules to esbuild bypassing the plugin output altogether.
|
||
|
||
#### - PostCSS
|
||
|
||
The simplest use case is to invoke PostCSS like this:
|
||
|
||
```javascript
|
||
const postcss = require('postcss')
|
||
const autoprefixer = require('autoprefixer')
|
||
const postcssPresetEnv = require('postcss-preset-env')
|
||
|
||
esbuild.build({
|
||
...,
|
||
plugins: [sassPlugin({
|
||
async transform(source, resolveDir) {
|
||
const {css} = await postcss([autoprefixer, postcssPresetEnv({stage: 0})]).process(source)
|
||
return css
|
||
}
|
||
})]
|
||
})
|
||
|
||
```
|
||
|
||
#### - CSS Modules
|
||
|
||
A helper function is available to do all the work of calling PostCSS to create a CSS module. The usage is something
|
||
like:
|
||
|
||
```javascript
|
||
const {sassPlugin, postcssModules} = require('esbuild-sass-plugin')
|
||
|
||
esbuild.build({
|
||
...,
|
||
plugins: [sassPlugin({
|
||
transform: postcssModules({
|
||
// ...put here the options for postcss-modules: https://github.com/madyankin/postcss-modules
|
||
})
|
||
})]
|
||
})
|
||
|
||
```
|
||
`postcssModules` produces Javascript modules which are handled by esbuild's `js` loader
|
||
|
||
`postcssModules` also accepts an optional array of plugins for PostCSS as second parameter.
|
||
|
||
Look into [fixture/css-modules](https://github.com/glromeo/esbuild-sass-plugin/tree/main/test/fixture/css-modules) for
|
||
the complete example.
|
||
|
||
> **NOTE:** `postcss` and `postcss-modules` have to be added to your `package.json`.
|
||
|
||
### quietDeps
|
||
|
||
In order for `quietDeps` to correctly identify external dependencies the `url` option is defaulted to the importing file path URL.
|
||
|
||
> The `url` option creates problems when importing source SASS files from 3rd party modules in which case the best workaround is to avoid `quietDeps` and [mute the logger](https://sass-lang.com/documentation/js-api/interfaces/StringOptionsWithImporter#logger) if that's a big issue.
|
||
|
||
### pnpm
|
||
|
||
There's a working example of using `pnpm` with `@material` design
|
||
in [issue/38](https://github.com/glromeo/esbuild-sass-plugin/tree/main/test/issues/38)
|
||
|
||
### Benchmarks
|
||
**Windows 10** Pro - **i7-4770K** CPU @ **3.50**GHz - RAM **24**GB - SSD **500**GB
|
||
|
||
Given 24 × 24 = 576 lit-element files & 576 imported CSS styles plus the import of the full bootstrap 5.1
|
||
|
||
| | dart sass | dart sass (no cache) | node-sass* | node-sass (no cache) |
|
||
|------------------------|-----------|-----------------------|-------------|----------------------|
|
||
| **initial build** | 2.750s | 2.750s | 1.903s | 1.858s |
|
||
| rebuild (.ts change) | 285.959ms | 1.950s | 797.098ms | 1.689s |
|
||
| rebuild (.ts change) | 260.791ms | 1.799s | 768.213ms | 1.790s |
|
||
| rebuild (.scss change) | 234.152ms | 1.801s | 770.619ms | 1.652s |
|
||
| rebuild (.scss change) | 267.857ms | 1.738s | 750.743ms | 1.682s |
|
||
|
||
(*) node-sass is here just to give a term of comparison ...those samples were taken from 1.8.x
|
||
|
||
[travis-url]: https://app.travis-ci.com/glromeo/esbuild-sass-plugin
|
||
[travis-image]: https://app.travis-ci.com/glromeo/esbuild-sass-plugin.svg?branch=main
|