PostCSS plugin to generate .d.ts of all used CSS classes and ids in imported stylesheets

Goal

Provide contract between JS and CSS.

Installation and setup

npm install postcss-d-ts

// postcss.config.js
module.exports = {
	plugins: [
	  "postcss-preset-env",
  	...
+	  "postcss-d-ts"  // or "postcss-d-ts/dist/7" for postcss v7
	]
}

Check postcss#usage for details.

Features

Languages

Language agnostic because of PostCss philosophy

CSS libraries/frameworks

In ./__typing__/ results of applying to some popular libraries: bootstrap v3, bootstrap v4, material v10, tailwind v2.

Applyment

CSS content:

/* some.css or some.module.css */
.class1 { ... }
.class2 { ... }

Generated declaration from template (i.e. default ./src/_css-template.d.ts):

declare const identifiersMap: CssIdentifiersMap
export default identifiersMap
export type CssIdentifiersMap = {
  "class1": string|undefined
  "class2": string|undefined
}

Thus, in Component (i.e. React): ./__recipes__/pages/module.tsx

import moduleClasses from "./some.module.css"
const {
  class1,
  class2,
  //@ts-expect-error - we have only .class1 and .class2
  class3
} = moduleClasses
const Component = () => <div className={`${class1} ${class2}`}/>

or ./__recipes__/pages/button.tsx

// Ordinary CSS
import type { CssIdentifiersMap } from "./some.css"
// I.e. with help of https://www.npmjs.com/package/react-classnaming
import classNaming from "react-classnaming"
const {
  class1,
  class2,
  //@ts-expect-error - we have only .class1 and .class2
  class3
} = {} as CssIdentifiersMap
const classNames = classNaming()
const Component() => <div {...classNames({class1, class2})} />

npm install react-classnaming

Options

`template: string`

Local path to a custom template for declarations generating.

Default: ./src/_css-template.d.ts

declare const identifiersMap: CssIdentifiersMap
export default identifiersMap
export type CssIdentifiersMap = {
  "__identifier__": string|undefined
}

Example: ./__func__/template--custom_path/template.d.ts

import type { CSSProperties } from "react";
interface Styled {
  __identifier__: Record<string, CSSProperties>;
}
declare const styled: Styled;
export default styled;
export declare const __identifier__: CSSProperties;

`identifierKeyword: string`

The word in d.ts template to be replaced with CSS classes, ids, etc.

// postcss.config.js
module.exports = {
  plugins: {
    "postcss-d-ts": {
+     identifierKeyword: "data"
    }
  }
}

// _css-template.d.ts
export type CssIdentifiersMap = {
-  "__identifier__": string|undefined
+  "data": string|undefined
}

`checkMode: boolean`

Throw an error instead of declaration file rewrite. By default, this mode is on for NODE_ENV === 'production'

Other options

Full list in different formats

JSON schema: ./__recipes__/next_9/postcss.config.json:
- https://askirmas.github.io/postcss-d-ts/schema.json
- ./node_modules/postcss-d-ts/dist/schema.json
- For all config file replace schema.json with postconfig.schema.json
TypeScript

import { Options } from "postcss-d-ts/dist/options.types"

JSDoc: ./__recipes__/next_10/postcss.config.js

/** @type {{
 *  plugins: Array<
*    ["postcss-d-ts", import("postcss-d-ts/dist/options.types").Options]
 *  >
 * }}
 */
module.exports = {
  plugins: [
    ["postcss-d-ts", {}]
  ]
}

Additional notes

CLI

Simply install postcss-cli and add it to npm scripts with desired options: example@cra and another:

// package.json
{
  "scripts": {
    "postcss-d-ts": "postcss --use postcss-d-ts styles/index.css --watch > /dev/null"
  }
}

With `create-react-app`

You need to launch postcss as a separate process. See commit https://github.com/askirmas/postcss-d-ts/commit/f9f07f009a02db69d9332bdd029a95420ce1a6d9 as an additional option how to establish