README.md
# [postcss-d-ts](https://github.com/askirmas/postcss-d-ts) [<img src="https://raw.githubusercontent.com/askirmas/postcss-d-ts/master/images/postcss-d-ts.svg" alt="logo" height="51px" align="right" />](https://github.com/askirmas/postcss-d-ts)
[PostCSS] plugin to generate [`.d.ts`] of all used CSS classes and ids in imported stylesheets
[](https://github.com/askirmas/postcss-d-ts/actions)
[](https://codecov.io/gh/askirmas/postcss-d-ts)
[](https://sonarcloud.io/dashboard?id=askirmas_postcss-d-ts)
[](https://codeclimate.com/github/askirmas/postcss-d-ts/maintainability)
[](https://scrutinizer-ci.com/g/askirmas/postcss-d-ts/?branch=master)
[](https://deepscan.io/dashboard#view=project&tid=13158&pid=16299&bid=346523)
[](https://www.codefactor.io/repository/github/askirmas/postcss-d-ts)
[](https://david-dm.org/askirmas/postcss-d-ts)
[](https://www.npmjs.com/package/postcss-d-ts)
[](https://github.com/askirmas/postcss-d-ts/blob/master/LICENSE)
<p align="center"><a href="https://github.com/askirmas/postcss-d-ts/blob/master/images/postcss-d-ts.gif"><img src="https://raw.githubusercontent.com/askirmas/postcss-d-ts/master/images/postcss-d-ts.gif"/></a></p>
## Goal
Provide [contract](https://en.wikipedia.org/wiki/Design_by_contract) between JS and CSS.
## Installation and setup
```bash
npm install postcss-d-ts
```
```diff
// postcss.config.js
module.exports = {
plugins: [
"postcss-preset-env",
...
+ "postcss-d-ts" // or "postcss-d-ts/dist/7" for postcss v7
]
}
```
Check [postcss#usage](https://github.com/postcss/postcss#Usage) for details.
## Features
### Languages <img src="https://raw.githubusercontent.com/askirmas/postcss-d-ts/master/images/postcss-d-ts.frameworks.gif" width="50%" align="right"/>
Language agnostic because of PostCss philosophy
<br clear="all"/>
### CSS libraries/frameworks
In [./\_\_typing\_\_/](https://github.com/askirmas/postcss-d-ts/blob/master/__typing__/) results of applying to some popular libraries: [bootstrap v3](https://github.com/askirmas/postcss-d-ts/blob/master/__typing__/bootstrap3.SHOULD.d.ts), [bootstrap v4](https://github.com/askirmas/postcss-d-ts/blob/master/__typing__/bootstrap4.SHOULD.d.ts), [material v10](https://github.com/askirmas/postcss-d-ts/blob/master/__typing__/material10.SHOULD.d.ts), [tailwind v2](https://github.com/askirmas/postcss-d-ts/commit/9514c9e62539127ffd9eaf85fb014efe2daec793#diff-f4d033574661830df6b3d15cfd8d47b76c2ed02cc525b1934242dcff8fc816c0).
## Applyment <img src="https://raw.githubusercontent.com/askirmas/postcss-d-ts/master/images/postcss-d-ts.full.gif" width="50%" align="right"/>
CSS content:
```css
/* some.css or some.module.css */
.class1 { ... }
.class2 { ... }
```
Generated declaration from template (i.e. default *[./src/\_css-template.d.ts](https://github.com/askirmas/postcss-d-ts/blob/master/src/_css-template.d.ts)*):
```typescript
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](https://github.com/askirmas/postcss-d-ts/blob/master/__recipes__/pages/module.tsx)*
```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](https://github.com/askirmas/postcss-d-ts/blob/master/__recipes__/pages/button.tsx)*
```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`](https://github.com/askirmas/react-classnaming)
## Options
### `template: string`
Local path to a custom template for declarations generating.
- Default: *[./src/\_css-template.d.ts](https://github.com/askirmas/postcss-d-ts/blob/master/src/_css-template.d.ts)*
```typescript
declare const identifiersMap: CssIdentifiersMap
export default identifiersMap
export type CssIdentifiersMap = {
"__identifier__": string|undefined
}
```
- Example: *[./\_\_func\_\_/template--custom\_path/template.d.ts](https://github.com/askirmas/postcss-d-ts/blob/master/__func__/template--custom_path/)*
```typescript
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.
```diff
// postcss.config.js
module.exports = {
plugins: {
"postcss-d-ts": {
+ identifierKeyword: "data"
}
}
}
```
```diff
// _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](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings): [./\_\_recipes\_\_/next\_9/postcss.config.json](https://github.com/askirmas/postcss-d-ts/blob/299955b1335037b759dd2a0960db9df2816bd326/__recipes__/next_9/postcss.config.json):
- https://askirmas.github.io/postcss-d-ts/schema.json
- *<u>./node_modules/postcss-d-ts/dist/schema.json</u>*
- For all config file replace `schema.json` with `postconfig.schema.json`
- TypeScript
```typescript
import { Options } from "postcss-d-ts/dist/options.types"
```
- JSDoc: [./\_\_recipes\_\_/next\_10/postcss.config.js](https://github.com/askirmas/postcss-d-ts/blob/master/__recipes__/next_10/postcss.config.js)
```javascript
/** @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](https://github.com/askirmas/postcss-d-ts/blob/f9f07f009a02db69d9332bdd029a95420ce1a6d9/__recipes__/create-react-app/package.json#L23) and another:
```json
// 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]: https://github.com/postcss/postcss
[postcss]: https://github.com/postcss/postcss
[`postcss`]: https://github.com/postcss/postcss-cli
[`postcss-cli`]: https://www.npmjs.com/package/postcss-cli
[`.d.ts`]: https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html