postcss-plugin-d-ts

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

Installation

npm install postcss-plugin-d-ts

Goal

Provide contract between JS and CSS.

Basic example

If you’re not familiar with PostCss – start from #PostCss Usage

CSS content:

.class1 { ... }
.class2 { ... }

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

export type CssIdentifiersMap = {
  "class1": string|undefined
  "class2": string|undefined
}

declare const identifiersMap: CssIdentifiersMap

export default identifiersMap

Thus, in Component (i.e. React):

import moduleClasses from "./some.module.css"

const {
  class1,
  class2,
    //@ts-expect-error - we have only .class1 and .class2
  class3
} = moduleClasses

export default function Component() {
    return <div className={`${class1} ${class2}`}/>
}

or

// No CSS-modules at all
import type { CssIdentifiersMap } from "./some.css"

const {
  class1,
  class2,
  class3
} = {} as CssIdentifiersMap

export default function Component() {
    return <div className={classNames({class1, class2})}/>
}

// Better to use `react-classnaming` https://www.npmjs.com/package/react-classnaming
// not this function
function classNames(classes: Record<string, string|undefined>) {
  return Object.keys(classes).join(" ")
}

With CSS libraries

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

Basic options

template: string

Local path to a custom template for declarations generating.

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

export type CssIdentifiersMap = {
  "__identifier__": string|undefined
}

declare const identifiersMap: CssIdentifiersMap

export default identifiersMap

• 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-plugin-d-ts", {
+     identifierKeyword: "data"
    }
  }
}

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

Other options

Full list in different formats

• JSON schema ./__recipes__/next_9/postcss.config.json:

  • https://askirmas.github.io/postcss-plugin-d-ts/schema.json
  • ./node_modules/postcss-plugin-d-ts/dist/schema.json

• TypeScript

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

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

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

Additional examples

TBD Clone from specs

• https://github.com/askirmas/postcss-plugin-d-ts/blob/master/__spec__/next_10/pages/index.tsx
• https://github.com/askirmas/postcss-plugin-d-ts/blob/master/__func__/basic.SHOULD.d.ts

PostCss Usage

Check you project for existed PostCSS config: postcss.config.js in the project root, "postcss" section in package.json or postcss in bundle config.

If you already use PostCSS, add the plugin to plugins list:

module.exports = {
  plugins: [
    require('autoprefixer'),
+   require('postcss-plugin-d-ts'),
  ]
}

If you do not use PostCSS, add it according to official docs and set this plugin in settings.