Add TypeScript types for the tailwind.config.js file

[RobinMalfait]

This PR will add types for the tailwind.config.js file. It also adds types for common tools we expose like:

• require('tailwindcss/colors')
• require('tailwindcss/defaultConfig')
• require('tailwindcss/defaultTheme')
• require('tailwindcss/plugin')

Currently, this is an opt-in feature. When you generate a new tailwind config you can add a --types flag to also add types to your tailwind.config.js file.

If you already have a tailwind.config.js file, then you should be able to convert it like this:

// Before
module.exports = {
  // ...
}

// After
/** @type {import('tailwindcss/types').Config} */
const config = {
  // ...
}

module.exports = config

Note: we separated the config & the module.exports line, this is because in some editors (even vscode) you will get module related code completion if you just did /** @type {...} */module.exports = ....

Here are a few screenshots of what those types get you:

[sasial-dev]

Will this also include support for ESM/imports?

[adamwathan]

Will this also include support for ESM/imports?

This just adds type declarations so people get autocompletions in the config file in their editor, not support for tailwind.config.ts files or anything. We’re exploring that as well but it’s proving a bit painful because the wider ecosystem doesn’t support that stuff that well. For example you can’t use an ESM PostCSS config anywhere we’ve tested, which means you still need some common JS config files even if we support ESM for Tailwind. Next.js doesn’t let you use a postcss.config.js file at all currently if your project is type: “module”, and the next.config.js file doesn’t support TypeScript even though Next otherwise does support TypeScript. So even if we added support for that stuff you’d still have a bunch of problems with tons of other tools you need to use alongside Tailwind, which makes it harder to see as a really big win. Exploring it though 👍🏻

[innocenzi]

How about adding a defineConfig function export?

// index.js
module.exports.defineConfig = (config) => config

// types.d.ts
export function defineConfig(config: Config): Config

So we can have this tailwind.config.js:

// @ts-check
const { defineConfig } = require('tailwindcss')

module.exports = defineConfig({
  content: [],
  presets: [],
  darkMode: 'media', // or 'class'
  plugins: [],
})

I think this is a really nice pattern for typed configuration objects, to avoid the JSDOC syntax.

[RobinMalfait]

We can do that in the future if we need to, but for now I don't see a lot of benefits. We still have to import something and still have to annotate something. Thanks for the suggestion though 👍

[innocenzi]

This just adds type declarations so people get autocompletions in the config file in their editor, not support for tailwind.config.ts files or anything. We’re exploring that as well but it’s proving a bit painful because the wider ecosystem doesn’t support that stuff that well. For example you can’t use an ESM PostCSS config anywhere we’ve tested, which means you still need some common JS config files even if we support ESM for Tailwind. Next.js doesn’t let you use a postcss.config.js file at all currently if your project is type: “module”, and the next.config.js file doesn’t support TypeScript even though Next otherwise does support TypeScript. So even if we added support for that stuff you’d still have a bunch of problems with tons of other tools you need to use alongside Tailwind, which makes it harder to see as a really big win. Exploring it though 👍🏻

Hey @adamwathan, have you explored the "transpile config file" route? I think it's way easier to add ESM/TS support this way right now, precisely for the reasons you mentioned.

If Tailwind takes care of that config file transpilation, other tooling don't have anything to do about it right?