thien-do / typed.tw

Brings types to TailwindCSS via TypeScript.

Heads-up! This project is archived. Please see https://github.com/stitchesjs/stitches for a good alternative

---

Typed Tailwind · typed.tw

Typed Tailwind brings types to Tailwind CSS by generating TypeScript classes (example) whose methods let you use the utility classes generated from your Tailwind config:

Try it live at typed.tw!

Jump to: Why · Usage · Examples · FAQ · Credits · License

Why

I wanted to combine the 2 great things in Front End engineering nowadays: static typing and functional CSS. Turn out, they get along very well. The constraint and predictability of utilities classes makes them ideal candidates to be statically typed as methods of a TypeScript class.

Is it more than just code completion? Yes. Code completion is just suggestion. Static typing enforces the correctness of your code styling, so you can do things like defining better API, automated code refactoring, and errors (like using undefined colors) can be caught at compile time.

Usage

1. Go to typed.tw (or typed-tailwind.com if you can't access .tw domain) and paste your Tailwind configuration into the first panel.
2. Save the generated file in the second panel to your codebase.
3. Import the Tw function from that file and use its (chain-able) methods:

// In practice, the file should be imported using absolute path
import { Tw } from "./tw";

const Foo = () => (
  <p className={Tw().textBlue().fontBold().$()}>
    Bold, blue text
  </p>
);

Example usages:

• https://github.com/dvkndn/typed.tw/search?l=TSX&q=Tw%28%29
• https://github.com/dvkndn/otf.show/search?l=TSX&q=Tw%28%29

Compile time usage with Webpack

Above is a run time usage. It allows you to easily add Typed Tailwind to many projects and build systems (e.g. it works with CRA without ejecting). However, it has some problems:

• The bundled JS is bigger because it includes the whole generated TypeScript class that reflects all possible values from your Tailwind configuration, even if you don't use them.
• It's a little bit slower for users because class names are looked up and concatenated at run time.
• Other tools like PurgeCSS cannot process the code out of the box.

Therefore, we have a typed-tailwind-loader to apply all Tw()...$() calls at compile time (as a part of your webpack build process, to be exact). This eliminates all 3 issues above.

• Learn more at the package folder.
• See a working example at examples/webpack.

Examples

• With Webpack: Please see the examples/webpack folder.
• With CRA: The typed.tw web app actually uses CRA itself. Its source code is in the web folder. Please see its style definition and a sample usage.
• With Next.js: The otf.show web app is a real-life open source project that uses Typed Tailwind and Next.js. Please see its style definition and a sample usage.

FAQ

• Where to put the generated file?
• Does it work without TypeScript?
• Does it work with PurgeCSS?
• Does it work with custom plugins?
• Does it work with custom classes?
• Is there any performance issue?
• The generated code style doesn't match ours. Can I reformat it?

Where to put the generated file?

The file should be imported from many places in your codebase so place it where you can take advantage of absolute imports. For example, if you are using CRA and your baseUrl is the src folder then you can place the file at src/tw/index.ts.

import { Tw } from "tw";

Does it work without TypeScript?

Yes. You can always compile the generated file to JS, optionally with a declaration file:

tsc --declaration style.ts

This way, you still get full code completion, just no compile time type checking.

Does it work with PurgeCSS?

Yes. Please see Compile time usage with Webpack section. If you can't follow that, try remove unused values to reduce the bundled size.

Does it work with custom plugins?

It's not officially supported yet but could work if your plugins are defined as inline anonymous functions (like in the docs). Also see: Does it work with custom classes.

Does it work with custom classes?

Yes. The result is simply a source file, so feel free to modify it anyway you want:

// style.ts

class Tailwind {
  /* ... */
  
  // Add your custom ones:
  textShadow(): Tailwind { return this.add("text-shadow"); }
}

Is there any performance issue?

Out of the box, maybe, because styling are applied at run-time, on render to be specific. However, you can use it at compile time to eliminate all of these issues.

If you can't modify your build config, or if you don't use webpack, it helps a little bit by moving the calls out of the renders. The work is still done at run time, but just once at start-up instead of every render.

const styles = Tw().fontBold().textBlue().$();

const Foo = () => <p className={styles} />;

The generated code style doesn't match ours. Can I reformat it?

Yes. The generated code should be checked into your source control so you can (and should) format it with your code formatter. In other words, just judge it as your own source code.

Credits

• @nhducit and @trungfinity for their help in the implementation design.
• anduin.design/style/ for the inspiration.

Alternatives

• re-tailwind Tailwind CSS in ReasonML

License

MIT

typed.tw's Issues

Crash when having transition property

Need to update the library so it works with latest version..

Change font in demo image on readme.md

As title, the s character is ...

Separate Tailwind config converting logic from web app

Currently the code to convert a Tailwind config to tw.ts lies somewhere within the code of web application https://typed-tailwind.com/ . Since web app is only an interface to use the core converting, I suggest to separate the converting code into another place (e.g. lib/convert-tw.ts).

With this separation, tests can be written to test only the Tailwind config converting logic. Or develop other interfaces on top of it (e.g. cli).

Whole and rational numbers result in the same method name

Duplicate method names are generated for classes like md:w-2/4 and md:w-24. The method for both is mdW24.

Generate classes at compile time

Currently classes (and the instances of Style) are generated at run time. Performance-wise, it could be better if we can do it at compile time (and technically it's possible to do so).

Could be something like a Babel plugin or a Webpack loader.

Bug: negative with variant usage

The tool works with "-m4" but not "focus:-m4" because it checks class.startsWith("-"). Should have a better check

Add error boundary

Currently whole page is blank. The easy way to "fix" is just to clear local storage

Simplify method chain

The current API calls are like this:

Would it be better to have something simpler.

Tw().bgfff.lt960FlexNone.lt960WFull.$()

The implementation could be done with Proxy.

Use with PurgeCSS

Either with:

• A custom extractor that understands Tw()...$() (https://www.purgecss.com/extractors), or:
• A webpack loader that execute Tw()...$() at compile time so we get normal JS files with string-based class names

Parse config with custom logic defined outside of module export

Test case: https://gist.github.com/dvkndn/ab434cae1ee42528723f05159172f69f

As far as I remember it's because typed.tw only parses the part inside module.export.. which is so wrong..

Consider providing a cli for local generation

I set up a quick script to avoid using the web service:

#!/usr/bin/env node
const { getSource } = require("typed-tailwind-convert");

const stdin = process.openStdin();

function convert() {
  stdin.setEncoding("utf8");
  stdin.on("data", data => {
    getSource(data)
      .then(console.log)
      .catch(console.error);
  });
}

convert();

Usage:

./convert < tailwind.config.js > src/tw.ts

Maybe it would be handy to include something like this to typed-tailwind-convert?

Usage with CLI