Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thepassle/rollup-plugin-native-css-modules
Use native CSS modules with import assertions in Rollup, without transforming CSS to JS.
https://github.com/thepassle/rollup-plugin-native-css-modules
assertions css import modules rollup
Last synced: 28 days ago
JSON representation
Use native CSS modules with import assertions in Rollup, without transforming CSS to JS.
- Host: GitHub
- URL: https://github.com/thepassle/rollup-plugin-native-css-modules
- Owner: thepassle
- Created: 2023-01-21T09:54:20.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-12-16T21:33:11.000Z (11 months ago)
- Last Synced: 2024-10-05T07:43:25.692Z (about 1 month ago)
- Topics: assertions, css, import, modules, rollup
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/rollup-plugin-native-css-modules
- Size: 36.1 KB
- Stars: 20
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Rollup-plugin-native-css-modules
Use native CSS modules with import assertions in Rollup. This plugin is intended to be used if you want to use import assertions in your build _output_, either in browsers that already support it, or because you're using something like [es-module-shims](https://github.com/guybedford/es-module-shims) to support native CSS modules.
This plugin does **not** transform any CSS module imports to JavaScript, it leaves the import statements and imports in tact.
## Example
Checkout the example on [Stackblitz](https://stackblitz.com/edit/rollup-repro-fbdojc).
Or take a look at the [example project](https://github.com/thepassle/css-example-project) for a more elaborate example.
### Input
`src/index.js`:
```js
import styles from './styles.css' assert { type: 'css' };
```
### Output:
`dist/index.js`:
```js
import styles from './styles-3275f665.css' assert { type: 'css' };
```
## Usage
```
npm i -S rollup-plugin-native-css-modules
```
```js
import css from 'rollup-plugin-native-css-modules';
export default {
input: 'index.js',
output: {
dir: 'dist',
format: 'esm'
},
plugins: [
css(),
/**
* Or:
*/
css({
transform: (code) => {
// modify the CSS code, minify, post-process, etc
return code;
}
})
]
};
```
## Features
At time of writing Rollup V3 supports import assertion syntax, however, Rollup will still try to parse any module that gets imported in your source code and expect it to be JavaScript. This will cause Rollup to throw an error, because it'll try to parse CSS files expecting it to be JavaScript. This plugin fixes that.
### Support
This plugin supports:
```js
import styles from './styles.css' assert { type: 'css' };
import styles from 'bare-module-specifier/styles.css' assert { type: 'css' };
import('./styles.css', { assert: { type: 'css'} });
```
This plugin does NOT support:
```js
import(`./styles-${i}.css`, { assert: { type: 'css'} });
import('./styles-' + i + '.css', { assert: { type: 'css'} });
```
The reason for this is that imports with dynamic variables are hard to statically analyze, because they rely on runtime code.
External stylesheets are ignored:
```js
import styles from 'http://styles.com/index.css' assert { type: 'css' };
import styles from 'https://styles.com/index.css' assert { type: 'css' };
```
Data uri's are also ignored.
### Deduplication
This plugin also deduplicates imports for the same module. If `foo.js` and `bar.js` both import `my-styles.css`, only one CSS file will be output in the output directory, as opposed to two.
### Hashing
CSS modules output by this plugin receive a hash based on the contents of the CSS file. E.g.:
**input:**
```js
import styles from './styles.css' assert { type: 'css' };
```
**output:**
```js
import styles from './styles-3275f665.css' assert { type: 'css' };
```
### Transform
You can use the `transform` hook to modify the CSS that gets output to, for example, minify your CSS using a tool like [lightning CSS](https://lightningcss.dev/docs.html) or something like postcss.
```js
import css from 'rollup-plugin-native-css-modules';
import { transform } from 'lightningcss';
export default {
input: 'demo/index.js',
output: {
dir: 'demo/dist',
format: 'esm'
},
plugins: [
css({
transform: (css) => transform({
code: Buffer.from(css),
minify: true
}).code.toString()
})
]
};
```
## FAQ
### Polyfilling
At the time of writing, browser support for import assertions is still low, so you're probably going to need to polyfill them. You can do this via [`es-module-shims`](https://github.com/guybedford/es-module-shims), note that you'll also need a polyfill for constructable stylesheets, which you can polyfill via [`construct-style-sheets-polyfill`](https://www.npmjs.com/package/construct-style-sheets-polyfill).
### Why are CSS files not combined and bundled?
Because you can't. Consider the following example:
```
my-app/
├─ index.js
├─ element-a.js
├─ element-b.js
├─ blue-styles.css
├─ red-styles.css
```
index.js
```js
import './element-a.js';
import './element-b.js';
```
element-a.js
```js
import blueStyles from './blue-styles.css' assert { type: 'css' };
class ElementA extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.adoptedStyleSheets = [blueStyles];
}
connectedCallback() {
this.shadowRoot.innerHTML = '
blue
';
}
}
customElements.define('element-a', ElementA);
```
element-b.js
```js
import redStyles from './red-styles.css' assert { type: 'css' };
class ElementB extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.adoptedStyleSheets = [redStyles];
}
connectedCallback() {
this.shadowRoot.innerHTML = '
red
';
}
}
customElements.define('element-b', ElementB);
```
blue-styles.css
```css
h1 {
color: blue;
}
```
red-styles.css
```css
h1 {
color: red;
}
```
Bundling this would lead to the following build output:
bundle.js
```js
import blueStyles from './styles-3275f665.css' assert { type: 'css' };
import redStyles from './styles-3a3f9686.css' assert { type: 'css' };
class ElementA extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.adoptedStyleSheets = [blueStyles];
}
connectedCallback() {
this.shadowRoot.innerHTML = '
blue
';
}
}
customElements.define('element-a', ElementA);
class ElementB extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.adoptedStyleSheets = [redStyles];
}
connectedCallback() {
this.shadowRoot.innerHTML = '
red
';
}
}
customElements.define('element-b', ElementB);
```
styles-3a3f9686.css
```css
h1 {
color: red;
}
```
styles-3275f665.css
```css
h1 {
color: blue;
}
```
If you would combine the CSS files for `blueStyles` and `redStyles` into one, and use that stylesheet in both components, it would lead to style clashes; you would only have red `
`s, instead of one blue `` for `` and one red `` for ``.
To illustrate:
bundle.js
```js
import bundledStyles from './styles-f32a2851.css' assert { type: 'css' };
class ElementA extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.adoptedStyleSheets = [bundledStyles];
}
connectedCallback() {
this.shadowRoot.innerHTML = '
blue
';
}
}
customElements.define('element-a', ElementA);
class ElementB extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.adoptedStyleSheets = [bundledStyles];
}
connectedCallback() {
this.shadowRoot.innerHTML = '
red
';
}
}
customElements.define('element-b', ElementB);
```
styles-f32a2851.css
```css
h1 {
color: blue;
}
h1 {
color: red;
}
```