tailwindjs

> Tailwind as Typescript/Javascript functions for code completion and type safety.

Table of contents

- Introduction
- Getting started
- Usage
- API reference
- Contributing

Introduction

TailwindJS is a Javascript/Typescript library that exposes TailwindCSS classes as Javascript objects.

$3

TailwindJS exposes:

- All TailwindCSS utilities as simple constants, e.g. h_10 => h-10
- All TailwindCSS modifiers as functions, e.g. dark(bg_stone_900) => dark:bg-stone-900

Additionally TailwindJS provides:

- Arbitraries - e.g. h_arb("30rem")
- Helpers - e.g. negative values (neg), class name joiner (classNames).

$3

- Runtime checking of Javascript objects to quickly identify typos and errors
- Build-time checking of Typescript (and Javascript if you use a build tool)
- Auto-suggestion and auto-completion features in your IDE (e.g. Intellisense in VS Code)
- Composability with modifiers/helpers without direct string manipulation

Getting started

$3

NPM:

``bash
npm install @jonathanconway/tailwindjs
`

Yarn:

`bash
yarn add @jonathanconway/tailwindjs
`

$3

If you use TailwindJS with a build system such as Webpack, NextJS or React, you'll need to set up class detection. This is so Tailwind knows the list of classes your app code uses and can include them in the build.

TailwindJS provides a special utility function to help with this: scanTailwindJSClasses. If you call this function from your tailwind.config.js file, providing a code path and an optional output path and filename, TailwindJS will scan your code, generate the list, and save it to an output file. You then simply need to add this file to the content array in your TailwindCSS config object.

Here's the full set of steps:

1. Ensure TailwindJS and TailwindCSS are installed in your project as dependencies.
2. Open tailwind.config.js in your editor/IDE.
3. Add the following import to the top: import { scanTailwindJSClasses } from "@jonathanconway/tailwindjs";
4. Add the following call after the imports but before the config object: scanTailwindJSClasses(`${__dirname}/src);
5. Add the following line to the content array in the config object: "./src/tailwind-js-classes.json"

At the end your tailwind.config.js file should look something like this:

``javascript
import { scanTailwindJSClasses } from "@jonathanconway/tailwindjs/build";
import type { Config } from "tailwindcss";

scanTailwindJSClasses(${__dirname}/src);

module.exports = {
darkMode: "selector",
content: ["./src/*/.{js,ts,jsx,tsx,mdx}", "./src/tailwind-js-classes.json"],
};
`

Usage

$3

You can use TailwindJS utilities by referencing them directly.

For example, in a React TSX or JSX file, you can have code like this:

`tsx
import { cn, rounded, bg_stone_500, text_sm } from "@jonathanconway/tailwindjs";

export function Button({ children }) {
return (
{children}
);
}
`

This will produce markup like the following:

`html
Ok
`

$3

You can use Tailwind modifiers by calling them as functions.

For example, in a React TSX or JSX file, you can have code like this:

`tsx
import {
cn,
dark,
text_stone_950,
text_stone_50,
} from "@jonathanconway/tailwindjs";

export function Text({ children }) {
return (
{children}
);
}
`

This will produce markup like the following:

`html
Ok
`

Note: TailwindJS does not yet support any non-TailwindJS arguments, apart from string literals, being passed to modifiers. So we recommend only passing TailwindJS utilities or modifiers, or string literals, as arguments to TailwindJS modifiers. Part of the reason for this is that TailwindJS class detection can only recognise TailwindJS utilities and functions.

$3

You can use Tailwind arbitrary values by calling them as functions, similar to modifiers.

For example, in a React TSX or JSX file, you can have code like this:

`tsx
import { cn, size_arb } from "@jonathanconway/tailwindjs";

export function Footnote({ children }) {
return {children};
}
`

This will produce markup like the following:

`html
Ok
`

API reference

`bash
npm install
`

To build the project as an importable library, run the following:

`bash
npm run build
`

To re-generate utilities and modifiers, which are scanned from the TailwindCSS website, run the following:

`bash
npm run build-tailwindcss-pages
npm run build-lib
npm run build
`

If you make any changes, to re-build the generated part of the docs, run the following:

`bash
npm run build-docs
npm run build
``

$3

Currently TailwindJS is in Beta. Versions are formatted as 0.0._n_ where _n_ is incremented on each publish.

At some point I plan to move the versions to align with TailwindCSS versions for major and minor (e.g. 3.4) and increment the patch for fixes / minor tweaks (e.g. 1, 2, 3...).

$3

Jonathan Conway (conwy.co)

Contributions of any kind are welcome!