[v4] How I updated my v3 plugin to v4

[jthayworth]

This has been a pretty hot topic for plugin creators since the release of v4. So I just wanted to put something on here about how I migrated a v3 plugin to v4 without the need of @plugin directive in hopes that it might help some of you that have the same needs I did. This very well could not be the best way to do it, but it works for me.

File Structure

lib/
├── base.css
├── components/
│   ├── component_1.css
│   ├── component_2.css
│   └── component_3.css
├── theme.css
├── utilities.css
├── index.css
└── build.js

index.css

This is the entry point for the plugin. The utilities.components.base and utilities.components.modifier will ensure your css is applied in the correct order for your components. I can't find it now, but someone commented this was their strategy in an issue/discussion here.

@layer utilities.components.base, utilities.components.modifier;
@import "tailwindcss";
@import "./theme.css";
@import "./base.css";
@import "./utilities.css";
/* Import your components here */
@import "./components/component_1.css";
...

theme.css

This is where any custom theme variables/overrides lives. It is also where any custom variants go (ie: darkMode: class equivelant).

@theme {
  --color-custom: #1f50a1;
}

@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

base.css

This is where the base layer is extended to include styles based on html elements and not classes.

@layer base {
  body {
    background-color: #ffffff;
    color: #222222;

    @variant dark {
      background-color: #262626;
      color: #fafafa;
    }
  }
}

utilities.css

Any utility that components will either reference or generic utilities that aren't components.

@utility focused {
  &:focus-visible {
    @apply outline-solid outline-2 outline-offset-0 outline-custom dark:outline-gray-50;
  }
}

component.css

This is where you can declare your component styles that can reference any previously declared utility.

@utility btn {
  @layer utilities.components.base {
    /* declare shared styles here */
  }
}

@utility btn-primary {
  @layer utilities.components.modifier {
    /* declare btn-primary specific styles here */
  }
}

Package Configuration

This is kind of ripped directly from the tailwindcss code and how that package.json is setup.

build.js

This file just copies the contents of the lib folder to the folder you want it to go to. In the example below it is just copying the files to the root directory of the package.

import fs from 'node:fs'

function build() {
  fs.cpSync('./components', './components', { recursive: true, force: true });
  fs.copyFileSync('./base.css', './base.css');
  fs.copyFileSync('./theme.css', './theme.css');
  fs.copyFileSync('./utilities.css', './utilities.css');
  fs.copyFileSync('./index.css', './index.css');
}

package.json

{
  "name": "@demo/plugin",
  "type": "module",
  "main": "./index.css",
  "files": [
    "components",
    "base.css",
    "theme.css",
    "utilities.css",
    "index.css"
  ],
  "exports": {
    ".": {
      "style": "./index.css"
    },
    "./package.json": "./package.json",
    "./index.css": "./index.css",
    "./index": "./index.css"
  },
  "scripts": {
    "build": "node build.js"
  }
  ...
}

Consuming Package

Once the user installs the package all they have to do is add import it in their entry css file.

@import "tailwindcss";
@import "@demo/plugin";