npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2025 – Pkg Stats / Ryan Hefner

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

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

  1. Process specific files:

    css-vars-docs -f "src/**/*.css"
  2. Run a dry run (no file changes):

    css-vars-docs --preview
  3. 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.