postcss-cva

postcss-cva

A postcss plugin that generates cva functions based on comments

• postcss-cva
  • What is cva (class-variance-authority)?
  • Concept
  • Usage
    • Install
    • postcss.config.[c]js
  • References
    • @meta
  • Options
    • outdir
    • importFrom
    • dryRun
    • cwd
    • format
    • prefix
    • remove
    • include / exclude
  • License

What is cva (class-variance-authority)?

The CVA function is an excellent atomic tool function, refer to https://cva.style/docs

Concept

For example. A cva function consists of 4 parts: base,variants,compoundVariants,defaultVariants

import { cva } from 'class-variance-authority'
//                     ⬇️ base
const button = cva(['font-semibold', 'border', 'rounded'], {
  // ⬇️ variants
  variants: {
    intent: {
      primary: ['bg-blue-500', 'text-white', 'border-transparent', 'hover:bg-blue-600'],
      secondary: ['bg-white', 'text-gray-800', 'border-gray-400', 'hover:bg-gray-100']
    },
    size: {
      small: ['text-sm', 'py-1', 'px-2'],
      medium: ['text-base', 'py-2', 'px-4']
    }
  },
  // ⬇️ compoundVariants
  compoundVariants: [
    {
      intent: 'primary',
      size: 'medium',
      class: 'uppercase'
    }
  ],
  // ⬇️ defaultVariants
  defaultVariants: {
    intent: 'primary',
    size: 'medium'
  }
})

button()
// => "font-semibold border rounded bg-blue-500 text-white border-transparent hover:bg-blue-600 text-base py-2 px-4 uppercase"

button({ intent: 'secondary', size: 'small' })
// => "font-semibold border rounded bg-white text-gray-800 border-gray-400 hover:bg-gray-100 text-sm py-1 px-2"

Usage

This plugin has been integrated internally in icestack, no need to install and register.

Install

npm i -D postcss-cva
yarn add -D postcss-cva
pnpm add -D postcss-cva

postcss.config.[c]js

add postcss-cva to your postcss config:

module.exports = {
  plugins: {
    // options
    'postcss-cva': {},
  }
}

Then you can write some comment start with @ in your css:

tip: command + / can get /* */ quickly

/* @meta path="button" */
.btn {
  /* @b */
}
.btn-primary {
  /* @v type="primary" */
}
.btn-xs {
  /* @v size="xs" */
}
.uppercase {
  /* @cv type="primary" size="xs" */
}
/* @dv type="primary" */

/* @gb ["rounded"] */
/* @gv type="primary" ["shadow-sm"] */
/* @gcv type="primary" size="xs" ["p-1"] */

In this plugin, type="primary" is called query, ["shadow-sm"] is called params

The same query will be merged with params together

Above css will generate button.ts at your $cwd/cva dir:

import { cva, VariantProps } from 'class-variance-authority'
//                 ⬇️ @b 
//                 ⬇️ @gb ["rounded"]
const index = cva(['btn', 'rounded'], {
  variants: {
    // ⬇️ @v type="primary" 
    // ⬇️ @gv type="primary" ["shadow-sm"]
    type: {
      primary: ['btn-primary', 'shadow-sm']
    },
    // ⬇️ @v size="xs"
    size: {
      xs: ['btn-xs']
    }
  },
  // ⬇️ @cv type="primary" size="xs" 
  // ⬇️ @gcv type="primary" size="xs" ["p-1"]
  compoundVariants: [
    {
      class: ['uppercase', 'p-1'],
      type: ['primary'],
      size: ['xs']
    }
  ],
  // ⬇️ @dv type="primary"
  defaultVariants: {
    type: 'primary'
  }
})
export type Props = VariantProps<typeof index>
export default index

you should install class-variance-authority, run npm i class-variance-authority

References

keyword	target	type	description
@b	base	node	add current node selector to base
@v	variants	node	add current node selector to variants
@cv	compoundVariants	node	add current node selector to compoundVariants
@dv	defaultVariants	global	define defaultVariants
@gb	base	global	define base
@gv	variants	global	define variants
@gcv	compoundVariants	global	define defaultVariants
@meta	meta	global	define metadata

type node will add current css node selector (the last class selector) to their target.

type global will define some query and params. It can be defined anywhere. The one defined later will overwrite the one defined before.

@meta

@meta query:

/* @meta path="{your-cva-filepath}" format="ts/js" */

path is generate cva file path, can be a/b/c/button

format can be js or ts

You can use the js variables to dynamically generate functions

Options

outdir

Type: string Default: cva

The location of the output directory

importFrom

Type: string Default: class-variance-authority

From which package to import the cva function

dryRun

Type: boolean Default: false

cwd

Type: string Default: process.cwd()

format

Type: js | ts Default: ts

prefix

Type: string Default: ''

remove

Type: boolean Default: true

remove all @xx comment

include / exclude

Type: String | RegExp | Array[...String|RegExp]

A valid picomatch pattern, or array of patterns. If options.include is omitted or has zero length, filter will return true by default. Otherwise, an ID must match one or more of the picomatch patterns, and must not match any of the options.exclude patterns.

Note that picomatch patterns are very similar to minimatch patterns, and in most use cases, they are interchangeable. If you have more specific pattern matching needs, you can view this comparison table to learn more about where the libraries differ.

License

MIT License © 2023-PRESENT sonofmagic