https://github.com/GoogleChromeLabs/postcss-jit-props
A CSS custom property helper based on PostCSS. Supply a pool of variables and this plugin will add them to the stylesheet as they are used.
https://github.com/GoogleChromeLabs/postcss-jit-props
bundle-size custom-properties postcss-plugin
Last synced: 15 days ago
JSON representation
A CSS custom property helper based on PostCSS. Supply a pool of variables and this plugin will add them to the stylesheet as they are used.
- Host: GitHub
- URL: https://github.com/GoogleChromeLabs/postcss-jit-props
- Owner: GoogleChromeLabs
- License: apache-2.0
- Created: 2021-10-04T17:52:43.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-18T16:20:18.000Z (2 months ago)
- Last Synced: 2025-03-31T19:06:57.020Z (20 days ago)
- Topics: bundle-size, custom-properties, postcss-plugin
- Language: JavaScript
- Homepage: https://stackblitz.com/edit/jit-open-props?file=postcss.config.js
- Size: 826 KB
- Stars: 228
- Watchers: 5
- Forks: 11
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- jimsghstars - GoogleChromeLabs/postcss-jit-props - A CSS custom property helper based on PostCSS. Supply a pool of variables and this plugin will add them to the stylesheet as they are used. (JavaScript)
README
# PostCSS (Just In Time) Props
> Only ship used variables! A CSS custom property helper based on PostCSS
[](https://www.npmjs.com/package/postcss-jit-props)
[](https://postcss.org/)
[](https://github.com/GoogleChromeLabs/postcss-jit-props/actions/workflows/node.js.yml)
`postcss-jit-props` watches for CSS variables and ensures a value entry exists in the stylesheet. [Try in browser](https://stackblitz.com/edit/jit-open-props?file=postcss.config.js)
This lets you **provide a huge pool of properties** for development and design, and rather than try and purge unused variables, **only adds what was used**.
## Example
CSS Before / During Development:
```css
.foo {
color: var(--brand-1);
padding: var(--size-1) var(--size-2);
margin-block-start: var(--size-2);
animation: var(--fade-in);
}@media (--dark) {
.foo {
color: white;
}
}
```CSS After / Result of Plugin:
```diff
+ @custom-media --dark (prefers-color-scheme: dark);+ :root {
+ --brand-1: #81A1C1;
+ --size-1: 1rem;
+ --size-2: 2rem;
+ --fade-in: fade-in .5s ease;
+ }.foo {
color: var(--brand-1);
padding: var(--size-1) var(--size-2);
margin-block-start: var(--size-2);
animation: var(--fade-in);
}@media (--dark) {
.foo {
color: white;
}
}+ @keyframes fade-in {
+ to { opacity: 1; }
+ }
```
## Usage
**Step 1:** Install plugin:
```sh
npm install --save-dev postcss-jit-props
```
**Step 2:** Add the plugin to plugins in `postcss.config.js` and **pass it your props (CSS || JS || JSON)**.
Pass JS objects:
```js
module.exports = {
plugins: [
require('postcss-jit-props')({
'--brand-1': '#81A1C1',
'--size-1': '1rem',
'--size-2': '2rem',
'--fade-in': 'fade-in .5s ease',
'--fade-in-@': '@keyframes fade-in {to { opacity: 1 }}',
'--dark': '@custom-media --dark (prefers-color-scheme: dark);',
'--text': 'white',
'--text-@media:dark': 'black',
}),
require('autoprefixer'),
]
}
```or pass CSS files
```js
module.exports = {
plugins: [
require('postcss-jit-props')({files: ['./props.css']}),
require('autoprefixer'),
]
}
```or JSON ✨
> Javascript and JSON must use the `-@` suffix on their custom property name in order for jit-props to find associated `@keyframes`
Configure where the selector the props are pushed to. Some CSS Module environments, for example, don't want the props in `:root`, so we can configure the plugin to push them where it's acceptable for the environment, like `:global`:
```js
module.exports = {
plugins: [
require('postcss-jit-props')({
...MyProps,
custom_selector: ':global'
}),
require('autoprefixer'),
]
}
```Configure the `@layer` the props are pushed to. :
```js
module.exports = {
plugins: [
require('postcss-jit-props')({
...MyProps,
layer: 'design.system'
}),
require('autoprefixer'),
]
}
```