askirmas/postcss-d-ts

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

postcss-d-ts

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

postcss-d-ts's Issues

Investigate what rewrite strategy is better for watcher

Successor of #16

1. Write to /tmp, then mv: //fs.rename(os.tmpDir())
2. trunc + append // was before e97c12f
3. rewrite + trunc

Minify

terser or uglify

Document `template` option

Successor of #4

• schema.json
• Readme.md

Show brief diff on checkMode:true

• Add some postfix to filePath. For better naming #27 required
  • option - stdout
• Error: own name, diff line, and link

Consider check mode - error on rewrite

Research `declare module` in template

Depends: #27

Support `destination: string` as output folder

Requires #15

rewrite with trunc

Make templating as stream or lazy iterator

Check can nested source be caught

After

@import "NoLeadingUnderscort.scss"
, "some.module.scss"
;

Change file comparison to not affect blank lines

with .trim() https://jsbench.me/fykmaajqmc/

Check and recipe for bootstrap and tailwind

Delete declaration on empty list

rewrite with `start` and trunc

Doc and Gif delete on empty

Can't run via JS API

[email protected]
[email protected]

My code (index.js):

const dts = require('postcss-d-ts')
const postcss = require('postcss')
const fs = require('fs')

fs.readFile('dx.ligt.css', (err, css) => {
  postcss([
    dts(),
  ], { from: 'dx.ligt.css', to: 'dx.out.css' })
    .process(css)
    .then(result => {
      console.log(result.css)
    })
})

Error:

dmitry@DESKTOP-Q74C34Q:~/H/_postcss/_tmp$ node index.js
/home/dmitry/H/_postcss/_tmp/node_modules/postcss/lib/processor.js:61
        throw new Error(i + ' is not a PostCSS plugin')
        ^

Error: [object Object] is not a PostCSS plugin
    at Processor.normalize (/home/dmitry/H/_postcss/_tmp/node_modules/postcss/lib/processor.js:61:15)
    at new Processor (/home/dmitry/H/_postcss/_tmp/node_modules/postcss/lib/processor.js:9:25)
    at postcss (/home/dmitry/H/_postcss/_tmp/node_modules/postcss/lib/postcss.js:25:10)
    at ReadFileContext.callback (/home/dmitry/H/_postcss/_tmp/index.js:6:3)
    at FSReqCallback.readFileAfterOpen [as oncomplete] (fs.js:273:13)

Investigate selector parsers

1. https://www.npmjs.com/package/postcss-selector-parser

Track `fs.stat` of template

It's like a change of options

Check "fs/promises" support

https://nodejs.org/docs/v12.18.4/api/fs.html#fs_fs_promises_api

option: import "fs/promises" agains import {promisses} from "fs"

Change template source from JSON configs to some *template.d.ts*

Keep type notation

Keyword `__file__` in template and options

postcss v8 support

https://evilmartians.com/chronicles/postcss-8-plugin-migration

Check that selector parser not stucked

Support data-* and it's values

#template: Reuse `mustache`

https://github.com/janl/mustache.js