postcss-es-modules

KO | EN

gitlite — search

#javascript #react #ai #machine-learning #nodejs #windows #cli #kubernetes #awesome-list #vue #ios #mcp #openai #open-source

postcss-es-modules

(★ 18)

Postcss plugin which transform css files in to the .js/.ts css modules.

postcss-es-modules 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# postcss-es-modules
[Postcss](https://postcss.org/) plugin which transform css files in to the .js/.ts css modules.

What is this? For example, you have the following CSS:

```css
/* ./component.module.css */
.article {
    font-size: 16px;
}
.title {
  font-size: 24px;
}
.title:hover {
  color: red;
}
```
After the transformation it will become like this:
```javascript
/* ./component.module.css.js */
// File generated by the postcss-es-modules plugin. Please do not modify it !!!
import { injectStyles } from 'css-es-modules';
const key = '77d26384-99a7-48e0-9f08-cd25a85864fb';
const css =`._article_9u0vb_1 {
    font-size: 16px;
}
._title_9u0vb_9 {
    font-size: 24px;
}
._title_9u0vb_9:hover {
    color: red;
}
`;
const styles = {
    get ['article']() { injectStyles(key, css); return '_article_9u0vb_1 article'; },
    get ['title']() { injectStyles(key, css); return '_title_9u0vb_9 title'; },
    inject() { injectStyles(key, css); }
};
export default styles;
```
Then that code can be referred from your component. 
```javascript
/* ./component.jsx */
import styles from './component.module.css.js';
export const Component = () => (
    <div className={styles.article}>
        <div className={styles.title}>Title</div>
    </div>
)
```

## Description
This plugin allows you to write the styles in *css/sass/less/...* syntax and transform it on the 
build time in the efficient *js/ts* code which can be simple referred from your component/application 
code. That code is responsible for attach the styles into the DOM (or to SSR pipeline) in most possible efficient way. 
This plugin also generates scoped class names, so you can be sure that your components styles will not leak 
in to the other parts of the application.

## Features
* **Zero** runtime dependencies (on eject or embed mode, pleas look at the options)
* Framework agnostic  
* Javascript and Typescript support
* Server side rendering
* Lazy, on demand, instant or none styles injection
* Rich (optional) configuration

## Installation
```bash
npm i postcss postcss-es-modules --save-dev
```

## Usage

Configure the postcss to use the plugin:
```javascript
// postcss.config.js
const { postcssEsModules }  = require('postcss-es-modules');
module.exports = (ctx) => ({
    plugins: [
        postcssEsModules({
            // options
        }),
    ]
})
```
> Please remember that this plugin is generating **non css syntax**, so it should be last on the list 
> of the used plugins.

> This plugin is internally using *postcss-modules* plugin, so you do not have to add it by self.

### With the postcss-cli 
```bash
postcss src/**/*.module.css --dir src --base src --ext css.js
```
This command will generate the `.js` files by the post-cli, directly to your src directory.

### With the postcss-cli and typescript

```javascript
// postcss.config.js
const { postcssEsModules }  = require('postcss-es-modules');
module.exports = (ctx) => ({
    plugins: [
        postcssEsModules({ inject: { scriptType: 'ts' } }),
    ]
})
```
```bash
postcss src/**/*.module.css --dir src --base src --ext css.ts
```
 
### With the webpack/rollup/...
There is nothing unique to use of this plugin with bundlers.

### With the webpack/rollup/... and typescript
If you are using typescript, and you do not want to generate es css modules ahead but just 
let the bundler do the job, for solving typescript compilation errors please add global declaration 
to your project, like that:

```typescript
/* ./global.d.ts */
declare module "*.css" {
    type Styles = { [className: string]: string; } & { inject(): void; }
    export const styles: Styles;
    export const key: string;
    export const css: string;
    export default styles;
}
```
This will say to the compiler that each `*.css` import should be mapped to declared type.

### Other usage examples
You can find more examples [here](https://majo44.github.io/postcss-es-modules/#/examples/).

## Options

Here is the list of all available options, for more details please go to [Recipes](#recipes).

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `inject` | `object` | - | The configuration fo the styles injection |
| `inject.useNounce` | `string` | - | The style nounce key |
| `inject.useConstructableStylesheet` | `boolean` | true | Use Constructable Stylesheet for styles injection to DOM if the browser supports Constructable Stylesheet |
| `inject.useStyleTag` | `boolean` | true | Use \<style\> tag for styles injection to DOM |
| `inject.useNodeGlobal` | `boolean` | true | Enable node.js global for collecting the styles, required for server side rendering |
| `inject.moduleType` | `'cjs'` / `'esm'` | `'esm'` | Generated code modules type. Options:<br/> - `esm`: ecmascript 6 modules<br/> - `cjs`: commonjs |
| `inject.injectMode` | `'lazy'` / `'ondemand'` / `'instant'` / `'none'` | `'lazy'` | The mode of the styles injection. Options:<br/> - `lazy` - the stylesheet will be injected on the first use of the style class name within the code<br/>- `ondemand` - the stylesheet will be injected only when the `styles.inject()` method will be called<br/>- `instant` -  the stylesheet will be injected on the module load<br/>- `none` - the stylesheet will be not injected, in order to inject it you will need to import `css` raw string from the module, and inject it manually |
| `inject.script` | `'embed'` / `'eject'` / `'import'` | `'import'` | The way how the styles injector script will be referred from the generated source. Options:</br>- `embed`: embedding styles injector script in to the target source (so each generated file will contains the loader inside)<br/>- `eject`: the styles injector script will be ejected to the provided `inject.scriptEjectPath`<br/>- `import`: the styles injector script will be referred by the import statement |
| `inject.scriptType` | `'ts'` / `'js'` | `'js'` | The generated script type. Options:</br>- `ts`: typescript<br/>- `js`: javascript |
| `inject.scriptEjectPath` | `string` | - | The path where the styles injector script code will be ejected. This option is required if `inject.script` is `eject` |
| `inject.custom` | `object`| - | The custom style injector configuration |
| `inject.custom.importStatement` | `string`| - | The custom style injector statement for import required dependencies. Eg: `"import { injectMyStyles } from 'somelib'";` |
| `inject.custom.injectStatement` | `string`| - | The custom style injector statement for executing the injection. There are available two constants in the context:<br/>- `css` - the raw css string code<br/>- `key` - unique key of the stylesheet<br/>Eg: `"injectMyStyles(css)"` |
| `modules` | `object`| - | The CSS Modules options. It is inherits all options from the [postcss-modules](https://github.com/css-modules/postcss-modules) expect `getJSON` |
| `modules.attachOriginalClassName` | `boolean`| false | The CSS Modules options. If you want to still use the original class name next to local one |

## Recipes

### Server side rendering
Example of server side rendering with the React and Express.js:
```css
/* ./index.css */
.app {
    background-color: red;
}
```

```typescript jsx
// ./index.js
const express = require('express');
const { createElement } = require('react');
const { renderToString } = require('react-dom/server');
const { collectStyles } = require('css-es-modules');
// imports the transformed css file
const { styles } = require('./index.module.css.js');

const app = express();

// example component to render
const App = () => createElement('div', { className: styles.app}, "Hello Word");

/**
 * App template
 * @param styles - the StylesCollector object
 * @param html - prerendered app markup
 */
const template = (styles, html) => `
    <html lang="en">
        <head>${styles.html}</head>
        <body><div id="app">${ html }</div></body>
    </html>`;

// handling request
app.get('/', (req, res) => {
    res.send(
        // render template
        template(
            // firstly start collecting styles
            collectStyles(),
            // then render application
            renderToString(createElement(App))));
});

// starting app
app.listen(3000);
```

To run this example you have to transpile css file ahead. With the `inject.moduleType` set to `cjs`.
The full working example you will find  [here](https://majo44.github.io/postcss-es-modules/#/examples/react-ssr-webpack-typescript/).

### Lazy/On demand/Instant/None styles injection
There are few modes how the styles injection can work.

#### Lazy (default)
The lazy injection means that the generated stylesheet will be not attached to the DOM/Node globals
until some code will not call the getter of className. So even you are importing module with styles
that styles are not applied to the application until some of the components will not use the class. 
This technique is very useful beacause on the server side rendering we will reder just critical 
stylesheets.

```javascript
import { injectStyles } from 'css-es-modules';
const key = '77d26384-99a7-48e0-9f08-cd25a85864fb';
const css =`._title_9u0vb_9 {
    font-size: 24px;
}
`;
const styles = {
    get ['title']() { injectStyles(key, css); return '_title_9u0vb_9 title'; },
    inject() { injectStyles(key, css); }
};
export default styles;
```

#### None
In this mode the provided module will not provide any way for the styles attaching to the DOM/Node globals.
So you will have to take exported raw `css` code and do that by self. You can use various libraries for that
like `lit-element`.

```javascript
const key = 'h6TLzUjXxsnSeNRWMPxAjG';
const css =`._title_6jm2u_1 {
    font-size: 24px;
}
`;
const styles = {
    ['title']: '_title_6jm2u_1',
    inject() { throw "This stylesheet can't be injected, instead please use exported css constant." }
};
export { styles, css, key };
export default styles;
```

#### On demand
This mode gives possibility to call the styles.inject() method for manual on demand styles injection.
```javascript
import { injectStyles } from 'css-es-modules';
const key = 'e1ph4XxYADCPaqpZhcgqRT';
const css =`._title_6jm2u_1 {
    font-size: 24px;
}
`;
const styles = {
    ['title']: '_title_6jm2u_1',
    inject() { injectStyles(key, css); }
};
export { styles, css, key };
export default styles;
```
#### Instant
This mode is calls the styles.inject() method internally.
```javascript
import { injectStyles } from 'css-es-modules';
const key = '63Jw35UDb1fWpxJiCNGuB9';
const css =`._title_6jm2u_1 {
    font-size: 24px;
}
`;
const styles = {
    ['title']: '_title_6jm2u_1',
    inject() { injectStyles(key, css); }
};
styles.inject();
export { styles, css, key };
export default styles;
```

### Embedding or ejecting the injector code
In some development workflows you can decide that you do not want to import the injector code from 
the dependencies library, in such case you have 2 options:

#### Embedding
By setting `embed` value of the `inject.script` option you will force transformer to embed the 
injector code within each transformed file in place. So the generated file will be much bigger but will 
not contain any import statements: 
```javascript
// File generated by the postcss-es-modules plugin. Please do not modify it !!!
/* eslint-disable */
...
function injectStyles(stylesheetKey, stylesheetBody, options) {
    ....
}

#### Ejecting
By setting `eject` value of the `inject.script` option you will force transformer to eject the injector
code into provided `inject.scriptEjectPath`.

Config:
```javascript
const { postcssEsModules }  = require('postcss-es-modules');
module.exports = (ctx) => ({
    plugins: [
        postcssEsModules({
            inject: {
                script: "eject",
                scriptEjectPath: __dirname + "/src/styles-inject"
            }
        }),
    ]
})
```
> The `inject.scriptEjectPath` have to be an absolute path.

Generated code:
```javascript
import { injectStyles } from './styles-inject/inject-styles';
const key = 'hT8K48DCnQc2Z9FkPUDzb7';
const css =`._title_6jm2u_1 {
    font-size: 24px;
}
`;
const styles = {
    get ['title']() { injectStyles(key, css);  return '_title_6jm2u_1'; },
    inject() { injectStyles(key, css); }
};
export { styles, css, key };
export default styles;
```
Within the `.src/styles-inject/inject-styles` you will find ejected code of injector.

> The ejection is not overwriting the existing files, you can eject code once, and modify it. 
> If you will get clean ejected code, please just delete old files.

This option can be very useful on the development process.

## Next steps
For more information please go to the [api reference](https://majo44.github.io/postcss-es-modules/#/api/) documentation
or to the [examples](https://majo44.github.io/postcss-es-modules/#/examples/) section.

## Need a help ?
If you have any problems, issues, ect. please use [github discussions](https://github.com/majo44/postcss-es-modules/discussions).

postcss-es-modules

postcss-es-modules 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

postcss-es-modules

postcss-es-modules 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README