A lib to create and extends React components defining variants like Stitches and using Tailwind classes!

Summary

1. Installation
   1. Run without plugin
      1. Advantages
      2. Disadvantages
   2. Tailwind configuration
   3. Plugin configuration
      1. Plugin options
      2. With Next
      3. With Webpack
2. Basic usage
   1. Custom components
3. Heritage
4. Deep classes
   1. Available syntaxes
   2. Is it possible to use external classes?
   3. Tailwind group
   4. Using with variants
5. Classes priority
6. How it works
7. Extension
   1. Color tokens
   2. Snippets

Installation

To install Tailwind Factory you need to run in your project:

//Using pnpm
pnpm add tailwind-factory

//Using npm
npm install tailwind-factory

//Using yarn
yarn add tailwind-factory

Run without plugin

You can run Tailwind Factory without its plugin. It's faster in many cases.

I will list here some advantages and disadvantages of running Tailwind Factory without the plugin:

Advantages

• Extremely fastest in development (because it will not be depending on the library's own cache to be checking the style of unchanged files);
• Fastest build (because you won't be using Babel);
• Support external classes (which do not belong to Tailwind);
• It doesn't generate a styling file (it doesn't actually need one);
• Specific classes of Tailwind may work better (because I don't have conditions to go out checking class by class).

Disadvantages

• Extremely limited Deep Classes support;
• Styles generated within Deep Classes will only be applied to the parent component's children, not to other child components. It works on the childrens of a HTML tag;
• Costs a little more memory on the Client-Side, mainly if you are using Deep Classes resources.

Tailwind configuration

Now you should install and configure Tailwind!

To use Tailwind CSS IntelliSense you need to add the following configuration in your User Settings:

1//Tailwind IntelliSense Regex
2"tailwindCSS.experimental.classRegex": [
3  ["tf\\(([^)]*)\\);", "(?:`)([^'\"`]*)(?:`)"], // tf(`...`);
4  ["\\.__extends\\(([^)]*)\\);", "(?:`)([^'\"`]*)(?:`)"], // xxx.extends(`...`);
5],

In this case it is necessary to put a semicolon at the end of the function call. Using the snippets you will not suffer from this. It already puts the semicolon.

If you don't like the idea very much (what do you mean you didn't come from Java, just kidding) you can use the old regex from the library, but you'll have problems if you call a parenthesis inside the function if you do. Also, you will have problems with the colors highlight set by the plugin if you are using it.

Still, I'll leave it here:

1//Tailwind IntelliSense Olg Regex
2"tailwindCSS.experimental.classRegex": [
3  ["tf\\(([^)]*)\\)", "(?:`)([^'\"`]*)(?:`)"], // tf(`...`)
4  ["\\.__extends\\(([^)]*)\\)", "(?:`)([^'\"`]*)(?:`)"], // xxx.extends(`...`)
5],

Plugin configuration

Tailwind Factory has its own Babel plugin that is used to generate the styles that are already included with the library. To use it you will need to provide it in your babel configuration file:

1//babel.config.js
2module.exports = (api) => {
3  //Can be true, but I haven't tested the effects.
4  api.cache(false); 
5  
6  return {
7    //...
8    plugins: [
9      //...,
10      [
11        "tailwind-factory/plugin",
12        {
13          logs: "normal",
14          styles: {
15            config: require("./tailwind.config"),
16            outputPath: "src/styles/generated.css"
17          },
18        },
19      ],
20    ],
21  };
22};

If you want to pass your Tailwind configuration the babel file has to export a JavaScript module so that you can pass your configuration using require. You can also pass the configuration directly, but this will limit you further.

Plugin options

1//types definition
2export type PluginType = {
3  preset?: "react"; //In case you need it someday
4  logs?: "none" | "all" | "normal" | "debug" | "errors";
5  styles?: {
6    outputPath?: string;
7    inputPath?: string; //Disabled
8    config?: Promise<TailwindConfig | undefined>;
9  };
10};

• logs - How the plugin should print the log, see the presets:

  • "none" - the plugin will not output or format any logs;
  • "all" - the plugin will output and format any logs, except debug logs;
  • "normal" - (default) the plugin will output and format some logs, except debug logs;
  • "debug" - the plugin will output and format some logs, including debug logs;
  • "errors" - the plugin will output and format only error logs.

• styles.config - Tailwind config (default: {});

• styles.outputPath - Path to put the generated styles (default: "src/styles/generated.css"). The file should be created before.

With Next

Edit your Next configuration file so it understands which files are important for the plugin:

1//next.config.js
2/* eslint-disable @typescript-eslint/no-var-requires */
3const { nextWithFactory } = require("tailwind-factory");
4
5module.exports = nextWithFactory({
6  reactStrictMode: true,
7  //...
8});

Import the generated styles file and the Tailwind configuration into one of the first files to be called before rendering (the import has to come before any components created by the library).

Common example in Next:

1//src/pages/_app.tsx
2import type { AppProps } from "next/app";
3
4import "../../tailwind.config";
5import "../styles/generated.css";
6
7export default function App({ Component, pageProps }: AppProps) {
8  return <Component {...pageProps} />;
9}

With Webpack

Edit your Webpack configuration file so it understands which files are important for the plugin:

1//webpack.config.js
2/* eslint-disable @typescript-eslint/no-var-requires */
3const { webpackWithFactory } = require("tailwind-factory");
4
5module.exports = webpackWithFactory({
6  //...
7});

Import the generated styles file and the Tailwind configuration into one of the first files to be called before rendering (the import has to come before any components created by the library).

1import "../../tailwind.config";
2import "../styles/generated.css";

Basic Usage

1import { tf } from "tailwind-factory";
2
3//Example of a common use case
4//Note: use ` to use Tailwind CSS IntelliSense
5// and " or ' to use the properties' autocomplete
6export const Container = tf("div", `flex flex-col`, 
7{
8  variants: {
9    theme: {
10      dark: `bg-zinc-800 text-zinc-100`,
11      light: `bg-white text-zinc-800`
12    },
13    size: {
14      md: `w-full h-[200px]`,
15      lg: `w-full h-screen`
16    },
17    centralized: {
18      //These keys (true and false) are reserved for boolean values 
19      // ​or their numerical value (0 and 1)
20      true: `justify-center`,
21      false: `justify-start`
22    }
23  },
24  defaultVariants: {
25    size: "lg",
26    theme: "light"
27  }
28});

Use case:

1<Container centralized>
2  <p>Now you can use it as you wish</p>
3</Container>

Custom components

Tailwind Factory also support custom components:

1//Example using a custom JSX component
2const JSXTitle = (
3  //The component need to have the className property!
4  { children, className }: { 
5    children: ReactNode, 
6    className?: string 
7  }
8) => <h2 className={className}>
9  {children}
10</h2>;
11
12//Is recommended create the component outside the function
13// to prevent a bug with Tailwind CSS IntelliSense
14export const Title = tf(JSXTitle, `
15  text-3xl
16  text-inherit
17`, {
18  ...
19});

Heritage

Components receive a function called __extends which can be called by passing or not a new component. The first parameter is precisely this new type of component. If null, it will inherit the extended component. Otherwise, it will inherit all properties and variants of the new component.

1//Example extending the styles
2//Note: all factory components have a `__extends` function
3export const Header = Container.__extends(
4  null, //Will inherit the properties and variants of Container
5`
6  flex
7  justify-center
8  items-center
9  w-full
10`, {
11  variants: {
12    theme: {
13      dark: `bg-zinc-800`,
14    },
15    border: {
16      true: `border-b-4 border-zinc-600`,
17      false: ``
18    },
19    size: {
20      sm: `h-[20%]`
21    }
22  },
23  defaultVariants: {
24    //theme: "light", is not necessary
25    border: true, //can be a string
26    size: "sm"
27  }
28});

You can replace the null value with another component:

1//Example extending another component
2export const Header = Container.__extends(
3  //Will inherit the properties of AnotherComponent 
4  // and variants of Container
5  AnotherComponent, 
6`
7  flex
8  justify-center
9  items-center
10  w-full
11`, {
12  variants: {
13    ...
14  },
15  defaultVariants: {
16    ...
17  }
18});

The idea was to make it closer to the 'as' property provided in some libraries. I won't go into details, but I failed to obtain this result and this was my way of mimicking this property.

I'm still wondering if the best way is to keep the extends function together with the components. If you have a problem with this or an idea, you can create an Issue.

Deep classes

In some cases, to avoid creating multiple components you can use a syntax similar to CSS:

1//Deep classes example
2const Container = tf(
3  "div",
4  `
5  bg-lime-200
6  w-4
7
8  h2 {
9    italic
10  }
11
12  div {
13    h-3
14  }
15
16  > div {
17    flex
18    flex-col
19    bg-blue-200
20    > h2 {
21      font-bold
22    }
23
24    .test {
25      text-6xl
26    }
27  }
28
29  > h2, > h1, p {
30    text-red-400
31  }
32`);

Plugin generated styles example:

1.factory__52dad3ab6fb6 {
2  width: 1rem;
3}
4.factory__52dad3ab6fb6 {
5  --tw-bg-opacity: 1;
6  background-color: rgb(217 249 157/var(--tw-bg-opacity));
7}
8.factory__52dad3ab6fb6 h2 {
9  font-style: italic;
10}
11.factory__52dad3ab6fb6 div {
12  height: 0.75rem;
13}
14.factory__52dad3ab6fb6 > div {
15  display: flex;
16}
17.factory__52dad3ab6fb6 > div {
18  flex-direction: column;
19}
20.factory__52dad3ab6fb6 > div {
21  --tw-bg-opacity: 1;
22  background-color: rgb(191 219 254/var(--tw-bg-opacity));
23}
24.factory__52dad3ab6fb6 > div > h2 {
25  font-weight: 700;
26}
27.factory__52dad3ab6fb6 > div .test {
28  font-size: 3.75rem;
29  line-height: 1;
30}
31.factory__52dad3ab6fb6 > h2, .factory__52dad3ab6fb6 > h1, .factory__52dad3ab6fb6 p {
32  --tw-text-opacity: 1;
33  color: rgb(248 113 113/var(--tw-text-opacity));
34}

Component structure example:

1<Container>
2  <h1>Red Title</h1>
3  <h2>Red</h2>
4  <p>Red Text</p>
5  <div>
6    <h2 className="test">Normal</h2>
7    <div className="hover:bg-red-300">
8      <h2>Normal</h2>
9    </div>
10  </div>
11</Container>

Output example (with plugin):

1<div class="factory__52dad3ab6fb6">
2  <h1>Red Title</h1>
3  <h2>Red</h2>
4  <p>Red Text</p>
5  <div>
6    <h2 className="test">Normal</h2>
7    <div class="hover:bg-red-300">
8      <h2>Normal</h2>
9    </div>
10  </div>
11</div>

Available syntaxes

Know that spaces between values ​​count here. The way Tailwind Factory separates classes is very much related to the use of commas and the space between classes. I don't mean the tabs, but it's good to pay attention to the details.

To inject by tag:

1div {
2  bg-red-500
3
4  h1 {
5    text-gray-200
6  }
7}

To inject by class:

1.hero {
2  bg-red-500
3
4  h1 {
5    text-gray-200
6  }
7}

On run without plugin the inject by class expected classes are saved, but are sent to the beginning of the class list. It is understood, in this case, that the expected classes cannot overlap with other classes and variants of Tailwind Factory.

To inject by id:

1#hero {
2  bg-red-500
3
4  h1 {
5    text-gray-200
6  }
7}

To inject into multiple:

1#hero, section, header, .title  {
2  bg-red-500
3
4  h1 {
5    text-gray-200
6  }
7}

To inject only in the first group of children inside the component (support multiple syntax):

1> div {
2  bg-red-500
3
4  h1 {
5    text-gray-200
6  }
7
8  //Need to repeat the '>' to apply in all
9  //Repeat is unnecessary if you are not using the plugin
10  > .main, > input {
11    rounded-md
12  }
13
14  //Just #all receive '>'
15  > #alt, textarea {
16    rounded-lg
17  }
18}

Inject with pseudo classes (need plugin):

1:hover {
2  p:first-of-type {
3    text-sm
4  }
5}
6
7div:focus {
8  rounded-md
9  border-2
10}

This first focus is not applied to everyone, but to the component created by the function.

Inject into all (need plugin):

1*:focus {
2  p:first-of-type {
3    text-sm
4  }
5}

Inject with media query (need plugin):

1//work
2md:rounded-md
3p:first-of-type {
4  md:text-red-500
5}
6
7//work
8@media(min-width:900px) {
9  w-6
10  p:first-of-type {
11    text-red-400
12
13    @media(min-width:100px) {
14      text-blue-500
15    }
16  }
17}

Inject with arbitrary value:

1max-w-[30rem]
2text-[#5a74db]

Is it possible to use external classes?

Tailwind Factory with plugin does NOT support external classes (not part of Tailwind) in function call. However, you can still call a class by passing it directly to the component:

1<div className="custom-class"/>

The idea is that you don't need to use this, since within the function call itself you can declare a class even within variants. I even tried to make the Tailwind Factory style syntax closer to CSS syntax and not be too limited.

Tailwind Group

In some cases, a group in Tailwind is the sufficient to set up a hover (I consider this a good practice):

1div {
2  group
3  hover:bg-gray-500
4  h2 {
5    group-hover:text-red-500
6  }
7}

Using with variants

The variants support deep classes:

1const Container = tf(
2  "div",
3  `
4  bg-lime-200
5  w-4
6`, {
7  variants: {
8    italic: {
9      true: `
10        h1, h2, h3 {
11          italic
12        }
13
14        a {
15          no-underline
16        }
17      `,
18      false: `
19        h2 {
20          underline
21        }
22      `
23    }
24  },
25  defaultVariants: {
26    italic: false
27  }
28});

You can __extends too:

1const Hero = Container.__extends(null, `
2  h1 {
3    text-9xl
4  }
5`);

Classes Priority

1. Inline Classes
2. Factory Variants
3. Extended Factory Variants
4. Factory Styles
5. Extended Factory Styles
6. Inline Saved Classes
   • [Without plugin] Inline Classes used in Deep Classes

How it works

Tailwind Factory (without the plugin) just arranges the classes within the variants according to the properties passed for the component. The plugin does the rest, checks the changed file, gets the classes, transforms the classes using Tailwind, preprocesses the styles with Postcss and Sass, puts the processed styles into the cache, loads the cache (which contains the other styles) and generates the file with all the styles.

The cache is tied to the component's style parameter and its variants, not the deep classes within the component's styles.

At the moment it is inevitable that, if you change any parameter of the function that brings style, a flash will occur in its rendering. There is no way for this to happen in production, because it is not possible to pass parameters within the styles defined in the function (this will probably cause an error in the plugin). The variants serve to reduce this limitation.

This flash happens because when a change is made the name of the class linked to the style parameter or component variant will change. So, since it's faster to change the class name than to load the change into the style sheet, the components that haven't changed will keep their styles (since their class name won't change) while the one with the changed class will wait it will be generated by the plugin and loaded by the browser with a class that doesn't exist yet.

Generating style names earlier was actually a way around Babel's limitations. It was not designed/structured to support asynchronous functions because that reduces performance and slows down rendering. And, in fact, the Tailwind Factory plugin is very heavy and needs your time to generate the component styles, this is a limitation of the library itself.

I am providing only what I can and with sincerely.

Extension

Tailwind Factory has an official extension that accompanies some snippets. See in: Tailwind Factory Extension

Documented version: 1.2.0

Warning: it is important that you put the semicolon at the end of the function!

Color tokens

All detected errors identifying classes fixed

• entity.factory.style: #91c26e
• entity.factory.symbol: #abb3c0
• entity.factory.style.internal.class: #d7c075
• entity.factory.style.html.tag: #da6f77
• entity.factory.style.pseudo: #ba7de6 / italic
• entity.factory.style.rule: #c16bff / italic / bold
• entity.factory.style.internal.id: #7d8be6
• entity.factory.style.number: #efba89
• entity.factory.style.unit: #eda460 / italic

You can change the colors in your VSCode configuration:

1{
2  "editor.tokenColorCustomizations": {
3    "textMateRules": [
4      {
5        "scope": "entity.factory.style",
6        "name": "Factory Style",
7        "settings": {
8          "foreground": "#91c26e"
9        }
10      }
11    ]
12  }
13}

Snippets

tfi: Import Tailwind Factory and create a new factory component

1import { tf } from "tailwind-factory";
2
3export const Container = tf("div", `
4  
5`, {
6  variants: {},
7  defaultVariants: {}
8});

tfc: Create a new factory component

1export const NewComponent = tf("div", `
2  
3`, {
4  variants: {},
5  defaultVariants: {}
6});

tfe: Create a new extended factory component

1export const NewComponent = Parent.__extends(ParentComponent, `
2  
3`, {
4  variants: {},
5  defaultVariants: {}
6});