Enable ESM and TS based config files

[RobinMalfait]

This PR adds support for loading and scaffolding ESM and TypeScript config files.

ESM and TS syntax support

Prior to this PR, your tailwind.config.js file had to be in CommonJS format. This was surprising to people using "type": "module" in their projects, and made it more difficult to do things like extract your theme tokens into a separate module that you could import into your tailwind.config.js as well as into your application code to maintain a single source of truth.

To make this work, we need to transpile ESM and TS config files on the fly (using jiti), since Tailwind itself isn't published in native ESM and of course there's no native TS support in Node.js. This means there is a performance penalty to using ESM and TS config files, which we're mitigating as much as possible by using Sucrase as the parser instead of Babel. The penalty on my machine is about ~10ms (~50ms using Babel) for one-off builds and the initial build in watch mode, and basically not measurable for incremental builds.

CLI improvements

This PR also adds --esm and --ts flags to the tailwindcss init CLI command to generate your config file using your preferred syntax:

npx tailwindcss init --esm

When running the init command with no flags, Tailwind will guess which syntax to use based on the "type" field in your package.json.

When using the --postcss flag, the generated postcss.config.js file will use the same syntax as your tailwind.config.js file, whether inferred or specified explicitly on the command line.

---

@natemoo-re and @innocenzi have been credited as co-authors for their efforts in earlier PRs:

• Add support for TypeScript configuration files #7327
• Adds support for ESM tailwind.config.js files #3544

[innocenzi]

Super happy we finally have this, great job guys ❤️

Tested with two medium projects:

• Both with @tailwindcss/forms and a few other external plugins
• Both greatly customized
• One that uses two configs through @config

Everything works perfectly fine, migration is easy. Super nice.

I've noticed zIndex has type issues. I had the following:

zIndex: {
	'sticky-on-scroll': 20,
	'chat-bubble': 30,
	'navbar': 30,
	'navbar-dropdown': 25,
	'dialog-base': 35,
	'dialog-panel': 36,
	'notification': 50,
},

But I had to make the values strings instead of numbers. Using @type {import('tailwindcss').Config} did not catch that before.

The only thing I miss is a defineConfig util instead of having to add satisfies Config at the end of the exported object, which is subjectively less pretty. But it's minor.

Thank you for this! ❤️

[woss]

hi, has this been released? i'm trying to get the TS and ESM js config to work but it doesn't.

[RobinMalfait]

@woss no not yet, it will be soon though!

If you want to know what's released and what isn't you can always take a look at the CHANGELOG.md file.

That said, you can already play with it using the insiders version: npm install tailwindcss@insiders.

[karlhorky]

This looks great, thanks for this @RobinMalfait 🙌

Since the current version number is 3.2.7, I guess this will be probably released in a new minor (tailwindcss@3.3.0)?

[joshmanders]

Thank you @RobinMalfait this is a long awaited feature I've been waiting for! Happy early birthday to me!

[klib19]

Thank you all for this feature! This is exactly what I needed for my project, I appreciate all the hard work!

One thing that is unclear to me and isn't addressed in the documentation, is how do I import the Tailwind colors into my ESM config file? None of these work

const colors = require('tailwindcss/colors')
import colors from "tailwindcss/colors";
import colors from "tailwindcss/colors.js";

[seb-jean]

Hello,

How to add defaultTheme, plugin, etc with TS.

Like this?

const defaultTheme = require('tailwindcss/defaultTheme');
const plugin = require('tailwindcss/plugin');

[karlhorky]

The more common style is import in TypeScript:

import defaultTheme from 'tailwindcss/defaultTheme';
import plugin from 'tailwindcss/plugin';

Often your editor / IDE can do this conversion for you like Convert 'require' to 'import' in VS Code (either use the lightbulb or hover over the three dots -> Quick Fixes -> "Convert 'require' to 'import'")

[RobinMalfait]

@klib19 while I wouldn't recommend to mix everything. All three of those should just work:

If you are experiencing issues then I would recommend to open an issue with a minimal reproduction repo attached that shows the issue.

---

@seb-jean as @karlhorky mentioned, you would use the import syntax in this case 👍

[seb-jean]

thanks @RobinMalfait