gjbkz
EsifyCSS
Introduction
EsifyCSS finds CSS files in your project and generates ES modules for each of them.
Assume that you have src/style1.css and src/style2.css. They have the same
contents:
/* src/style1.css, src/style2.css */
@keyframes FadeIn {
0%: {opacity: 0}
100%: {opacity: 0}
}
@keyframes Rotate {
0%: {transform: rotate( 0deg)}
100%: {transform: rotate(360deg)}
}
#container {
animation: 0.2s linear FadeIn;
}
.icon {
animation-duration: 1s;
animation-iteration-count: infinite;
animation-timing-function: linear;
}
.icon.rotate {
animation-name: Rotate;
}Then, run esifycss --helper src/helper.js src. --helper src/helper.js is
where the helper script is written. The last src specifies the directory that
contains the file to be processed by EsifyCSS.
The process finds CSS files, parses them, extracts identifiers, replaces them with values.
After the process, you'll get src/style1.css.js and src/style2.css.js:
// src/style1.css.js
import {addStyle} from './helper.js';
addStyle(["WYIGqCCQSCaAQEcSCaAUEE","WYIGsCCQSCeAgBiBIIQkBmBEcSCeAgBiByBkBmBEE","0BGQC2BA4BKOA6BoBIqBIGqCKE","sBGUCOM8BAUoBKOM+BMgCAiCKOMkCMmCAqBKE","sBG2CG4CCOMoCAGsCKE"]);
export const className = {
"icon": "_1",
"rotate": "_2"
};
export const id = {
"container": "_0"
};
export const keyframes = {
"FadeIn": "_3",
"Rotate": "_4"
};// src/style2.css.js
import {addStyle} from './helper.js';
addStyle(["WYIGuBCQSCaAQEcSCaAUEE","WYIGwBCQSCeAgBiBIIQkBmBEcSCeAgBiByBkBmBEE","0BGuCC2BA4BKOA6BoBIqBIGuBKE","sBGwCCOM8BAUoBKOM+BMgCAiCKOMkCMmCAqBKE","sBGyCG0CCOMoCAGwBKE"]);
export const className = {
"icon": "_6",
"rotate": "_7"
};
export const id = {
"container": "_5"
};
export const keyframes = {
"FadeIn": "_8",
"Rotate": "_9"
};The two modules are almost the same, but the exported objects are different. And
there will be src/helper.js which exports the addStyle function which
applies the style to documents. You can see the code at
sample/01-mangle/helper.js.
The exported objects are mappings of identifiers of className, id, and
keyframes that were replaced in the process. You should import them and use
the replaced identifiers instead of original in the code:
import style from './style1.css.js';
const element = document.createElement('div');
element.classList.add(style.className.icon);Tools
EsifyCSS consists of PostCSS plugin, Runner and CLI.
PostCSS plugin
The plugin converts the identifiers in CSS and minifies them. It outputs the result of minifications using Root.warn().
Runner
A runner process .css files in your project with PostCSS and output the
results to .css.js or .css.ts.
CLI
Usage: esifycss [options] <include ...>
Options:
-V, --version output the version number
--helper <path> A path where the helper script will be output. You can't use --helper with --css.
--css <path> A path where the css will be output. You can't use --css with --helper.
--ext <ext> An extension of scripts generated from css.
--config <path> A path to configuration files.
--exclude <path ...> Paths or patterns to be excluded.
--noMangle Keep the original name for debugging.
--watch Watch files and update the modules automatically.
-h, --help output usage informationexample: generate .css.ts and css-helper.ts
esifycss --helper=css-helper.ts --ext=.ts <source-directory>example: TypeScript based Next.js project
Assume that you have following files:
src/
styles/
global.css
components/
Button/
index.ts
style.module.css
pages/
_app.tsxThen, run the following command:
esifycss --css=src/pages/all.css --ext=.ts srcYou'll get src/pages/all.css. src/pages/_app.tsx should import it:
// src/pages/_app.tsx
import './all.css';Installation
npm install --save-dev esifycss@import Syntax
You can use @import syntax if the style declarations requires identifiers
declared in other files.
For example, Assume you have the following a.css and b.css.
/* a.css */
.container {...} /* → ._0 *//* b.css */
.container {...} /* → ._1 */The container class names will be shortened to unique names like _0 and
_1. You can import the shortened names with the @import syntax.
/* "modA-" is prefix for a.css */
@import './a.css' modA-;
/* "bbbb" is prefix for b.css */
@import './b.css' BBB;
.wrapper>.modA-container {...} /* → ._2>._0 */
.wrapper>.BBBcontainer {...} /* → ._2>._1 */JavaScript API for Runner
import {Session} from 'esifycss';
new Session(options).start()
.then(() => console.log('Done'))
.catch((error) => console.error(error));Options
export interface SessionOptions {
/**
* Pattern(s) to be included
* @default "*"
*/
include?: string | Array<string>,
/**
* Pattern(s) to be excluded.
* @default ['node_modules']
*/
exclude?: anymatch.Matcher,
/**
* File extension(s) to be included.
* @default ['.css']
*/
extensions?: Array<string>,
/**
* Where this plugin outputs the helper script.
* If you use TypeScript, set a value like '*.ts'.
* You can't use this option with the css option.
* The {hash} in the default value is calculated from the include option.
* @default "helper.{hash}.css.js"
*/
helper?: string,
/**
* File extension of generated script.
* @default options.helper ? path.extname(options.helper) : '.js'
*/
ext?: string,
/**
* Where this plugin outputs the css.
* You can't use this option with the helper option.
* @default undefined
*/
css?: string,
/**
* It it is true, a watcher is enabled.
* @default false
*/
watch?: boolean,
/**
* Options passed to chokidar.
* You can't set ignoreInitial to true.
* @default {
* ignore: exclude,
* ignoreInitial: false,
* useFsEvents: false,
* }
*/
chokidar?: chokidar.WatchOptions,
/**
* An array of postcss plugins.
* esifycss.plugin is appended to this array.
* @default []
*/
postcssPlugins?: Array<postcss.AcceptedPlugin>,
/**
* https://github.com/postcss/postcss#options
* @default undefined
*/
postcssOptions?: postcss.ProcessOptions,
/**
* Parameters for esifycss.plugin.
*/
esifycssPluginParameter?: PluginOptions,
/**
* A stream where the runner outputs logs.
* @default process.stdout
*/
stdout?: stream.Writable,
/**
* A stream where the runner outputs errorlogs.
* @default process.stderr
*/
stderr?: stream.Writable,
}Source: src/runner/types.ts
JavaScript API for Plugin
const postcss = require('postcss');
const esifycss = require('esifycss');
postcss([
esifycss.plugin({/* Plugin Options */}),
])
.process(css, {from: '/foo/bar.css'})
.then((result) => {
const pluginResult = esifycss.extractPluginResult(result);
console.log(pluginResult);
// → {
// className: {bar: '_1'},
// id: {foo: '_0'},
// keyframes: {aaa: '_2'},
// }
});The code is at sample/plugin.js.
You can run it by node sample/plugin.js after cloning this repository and
running npm run build.
Options
export interface PluginOptions {
/**
* When it is true, this plugin minifies classnames.
* @default true
*/
mangle?: boolean,
/**
* A function returns an unique number from a given file id. If you process
* CSS files in multiple postcss processes, you should create an identifier
* outside the processes and pass it as this value to keep the uniqueness
* of mangled outputs.
* @default esifycss.createIdGenerator()
*/
identifier?: IdGenerator,
/**
* Names starts with this value are not passed to mangler but replaced with
* unprefixed names.
* @default "raw-"
*/
rawPrefix?: string,
/**
* A custom mangler: (*id*, *type*, *name*) => string.
* - *id*: string. A filepath to the CSS.
* - *type*: 'id' | 'class' | 'keyframes'. The type of *name*
* - *name*: string. An identifier in the style.
*
* If mangler is set, `mangle` and `identifier` options are ignored.
*
* For example, If the plugin processes `.foo{color:green}` in `/a.css`,
* The mangler is called with `("/a.css", "class", "foo")`. A mangler should
* return an unique string for each input pattern or the styles will be
* overwritten unexpectedly.
* @default undefined
*/
mangler?: PluginMangler,
}Source: src/postcssPlugin/types.ts
LICENSE
The esifycss project is licensed under the terms of the Apache 2.0 License.