css-vars-docs
v1.4.0
Published
Generates a comment block with all CSS variables from the specified file to improve readability and provide documentation. The block is added at the beginning of the file, or in the first <style> block for non-CSS files, if available.
Downloads
47
Maintainers
Readme
CssVarsDocs
CssVarsDocs generates a comment block containing all CSS variables from a specified file to improve readability and provide automatic documentation. Comments are added at the beginning of CSS files or inside <style>
blocks for non-CSS files (e.g., HTML or Vue).
Features
- CLI Tool for direct file modification
- Supports PostCSS and Vite as plugins
- Compatible with CommonJS and ES Modules (Dual Output)
- Flexible configuration via CLI options or configuration files
Installation
Use without Installation (npx
/pnpx
)
npx css-vars-docs [options]
pnpx css-vars-docs [options]
Install Locally (as a Dev Dependency)
npm install -D css-vars-docs
pnpm add -D css-vars-docs
Install Globally
npm install -g css-vars-docs
Usage
CLI Usage
Run the CLI directly:
npx css-vars-docs [options]
Or globally:
css-vars-docs [options]
Example Commands
Process specific files:
css-vars-docs -f "src/**/*.css"
Run a dry run (no file changes):
css-vars-docs --preview
Remove comments:
css-vars-docs --remove
CLI Options
| Option | Description |
| ------------------------------------- | ------------------------------------------------------------------ |
| -f, --files <files>
| Files to process, separated by spaces or commas |
| -r, --remove
| Remove existing comments from the files |
| -p, --preview
| Dry run: show changes without writing to files |
| -t, --title <title>
| Header for the comment block |
| -b, --block-identifier <identifier>
| Unique identifier for generated blocks |
| -i, --indent <indent>
| Default indentation |
| -is, --indent-style
| Add extra indentation in <style>
blocks |
| -ex, --exclude-node-modules
| Exclude node_modules
by default |
| -n, --new-lines-before-group
| Add a new line between variable groups |
| -lp, --log-prefix <prefix>
| Prefix for log messages |
| -ll, --log-level <level>
| Log level: 0
= errors, 1
= changes, 2
= verbose, 3
= debug |
| -lc, --load-config
| Load config file: true
(default) or false
|
Configuration Files
css-vars-docs
supports multiple configuration file formats out of the box. You can use the same configuration file for both CLI and programmatic usage, regardless of the module system (CommonJS or ESM).
Supported Files:
| File Format | Description |
| -------------------------- | ----------------------------------------------------------------------- |
| css-vars-docs.config.cjs
| CommonJS configuration file. |
| css-vars-docs.config.mjs
| ES Module configuration file. |
| css-vars-docs.config.js
| Automatically interpreted as CommonJS or ESM based on your environment. |
Example Configuration Files
CommonJS (css-vars-docs.config.cjs
)
module.exports = {
indent: ' ',
files: ['src/**/*.css', 'src/**/*.vue'],
logLevel: 2,
newLinesBeforeGroup: true,
preview: false
};
ES Module (css-vars-docs.config.mjs
)
export default {
indent: ' ',
files: ['src/**/*.css', 'src/**/*.vue'],
logLevel: 2,
newLinesBeforeGroup: true,
preview: false
};
PostCSS Config
PostCSS Config:
const cssVarsDocs = require('css-vars-docs/postcss-plugin');
module.exports = {
plugins: [
cssVarsDocs({
logLevel: 3
})
]
};
Vite Config
Vite Config:
import { defineConfig } from 'vite';
import cssVarsDocsVite from 'css-vars-docs/vite-plugin';
export default defineConfig({
plugins: [
cssVarsDocsVite({
delay: 200, // Delay between file processing
extensions: ['.css', '.vue'], // Files to process
config: {
logLevel: 2,
preview: false
}
})
]
});
Programmatic Usage
You can use CssVarsDocs
directly in your Node.js scripts:
import { CssVarsDocs } from 'css-vars-docs';
const cssVarsDocs = new CssVarsDocs({
files: ['src/**/*.css'],
logLevel: 2
});
cssVarsDocs.processFiles();
Dual Output: ESM and CJS
Why Dual Output?
- ESM: Modern JavaScript environments and bundlers (e.g., Vite, Rollup).
- CJS: Node.js CLI compatibility and legacy projects.
Node.js automatically selects the correct format based on your environment.
Example Imports:
// ESM
import { CssVarsDocs } from 'css-vars-docs';
// CommonJS
const { CssVarsDocs } = require('css-vars-docs');
License
This project is licensed under the MIT License.
Notes
This tool modifies files directly. Use the preview
option to test changes before applying them. Always consider committing your code before running file modifications.