Configuration file type definitions

[Glinkis]

It would be awesome if we were able to get autocomplete working in the configuration file. Especially so with theme callbacks and plugins.

This should be possible to achieve by including typescript or jsdoc type definitions, and then doing something like:

/**
 * @type {import('tailwindcss').Config}
 */
const config = {
 // everything inside of here would get autocomplete
};

module.exports = config;

[adamwathan]

Would be open to a PR for this, not something I have experience with myself though. One thing to be careful of though is that you can have any keys you want in that file, because plugins can expect custom keys to exist, so I'm not sure how easy it's going to be to capture that flexibility in a type definition.

[LouizFC]

I was about to open the same issue. Glad there are more people interested in this.

@adamwathan in typescript you can define something like:

interface Dictionary {
  some: string;
  keys: string;
  /**
   * and with this you are saying: "this type can have any field 
   * as long as the key is a string and it also return a string"
   */
  [key: string]: string;
}

@Glinkis I don't know how to "wire" the type definition to the raw javascript file, but I can help write the definition file if wanted

[Glinkis]

@LouizFC

I don't know how to "wire" the type definition to the raw javascript file

Not quite sure what you mean by this. It should be enough to just create a types.d.ts-file, and link to it via the types field in package.json.

One can then simply do import('tailwindcss') in the JSDoc comment like I did above.

Would you like to create a branch for this, and link it here? That way we could potentially collaborate on the type file.

[LouizFC]

@Glinkis I will create it on the weekend, I already have some types from a experiment that I did on tailwind. The only thing I can't get right are the default values.

Just inlining all the default values on a e.g DefaultScreens, DefaultColors types should be enough, but it introduces the overhead of modifying two files if Tailwind devs want to change a default value (or introduce new ones).

If you know something that could help (like a tool that extracts default values from an existing object) that would solve this problem.

[Glinkis]

@LouizFC I started a bit over here, with a very basic setup.
I've granted you contribution privileges.

[jonaskuske]

FYI, this gets you fairly close:
(but only in JS projects, in TS projects type inference for dependencies is not possible)

/** @typedef { import('tailwindcss/defaultConfig') } DefaultConfig */
/** @typedef { import('tailwindcss/defaultTheme') } DefaultTheme */

/** @type { DefaultConfig & { theme: { extend: DefaultTheme } } } */
module.exports = {
  // you have autocomplete here, type "c" and it'll suggest "corePlugins"
}

It's not perfect (e.g. "purge" is reported as undefined[] instead of string[], some options are objects and some are functions...) but you do get nice autocomplete for most config and theme options and see all the available options without having to check the docs for their precise name. 👍🏻

[GaspardC]

@jonaskuske thanks seems great
how do we use this snippet to access the type then ? 😅

[GaspardC]

@jonaskuske thanks, exactly what I'm looking for

as you said I created a tailwind.config.js file with :

/** @typedef { import('tailwindcss/defaultConfig') } DefaultConfig */
/** @typedef { import('tailwindcss/defaultTheme') } DefaultTheme */
/** @typedef { DefaultConfig & { theme: { extend: DefaultTheme } } } TailwindConfig */

/** @type {TailwindConfig} */
module.exports = {
// corePlugins hints working here
}

then in my TS file:

import { TailwindConfig } from './tailwind.config'
const config: TailwindConfig = { test: 1 }
//don't have any errors or autocompletion hints here

Do you know what is wrong with my code ?

[jonaskuske]

@GaspardC Hmm, good question. I tested it in tailwind.config.js and in an index.ts I created next to it and it worked, but my project wasn't actually set up for TS, there was no tsconfig.json. So my guess would be that as soon as you add a tsconfig to your project, TS/VSCode handles interop between .ts and .js with JSDoc differently?

Alright, my mistake:
It only works in JS projects because they allow infering types of dependencies. And it even works for .ts files that are placed inside the JS project, which doesn't make sense to begin with but is unfortunately how I tested it and thus got my wrong conclusions. In TS projects (tsconfig.json exists), untyped dependencies need explicit types or end up as any, with no way around that it seems. So apparently you're out of luck here.

[phamhongphuc]

With @nuxt/typescript-runtime + @nuxtjs/tailwindcss, it's possible to use tailwind.config.ts as the config file.
Although there are some bugs with hot-reload, that's not a problem for me.
The problem is we don't have the type definitions. It's hard to write plugins or get autocomplete in the config file.

[dolanmiu]

I have created high quality type definitions for tailwind:

DefinitelyTyped/DefinitelyTyped#50921

It will be downloadable by doing npm i @types/tailwindcss once this is merged!

Enjoy!

[FedericoBiccheddu]

Thank you so much.

[florianrusch]

Same as on the comment below, I would recommend to install the types as a dev dependency. So it should be npm i -D @types/tailwindcss

(Sorry for duplicate – I just want to make sure I reach all users which are looking for this)

[FedericoBiccheddu]

Tailwindcss types are now published!

[sergeyzwezdin]

Any plans to update to v3?

[idan]

For posterity:

1. npm i @types/tailwindcss
2. Add the following line at the top of tailwind.config.js, right above the module.exports = { line:

/** @type {import("@types/tailwindcss/tailwind-config").TailwindConfig } */

Enjoy types and autocompletion!

[florianrusch]

I would recommend to install the types as a dev dependency. So it should be npm i -D @types/tailwindcss

[mshamaseen]

That didn't work for me first, then I added "allowJs": true in the compilerOptions in the tsconfig and now it is working.

[jjdive]

I tried @idan 's suggestion in my Vue3 + TS project but it didn't work.

After trying a few other things, what finally did the trick was creating a tailwind.config.d.ts file with:

export { TailwindConfig } from '@types/tailwindcss/tailwind-config'

Then in the .vue file where i dynamically generate a color palette component for Storybook:

import {
  TailwindColorGroup, // This one is used in the component's logic to cast a color group
  TailwindConfig,
} from 'tailwindcss/tailwind-config'
import resolveConfig from 'tailwindcss/resolveConfig'
import tailwindConfig from '/@/../tailwind.config'

const {
  theme: { colors },
} = resolveConfig((tailwindConfig as unknown) as TailwindConfig)

Hope this helps someone else facing the same issue.

[ohuu]

Having real trouble with this in vue 3 using vite. I've tried @idan's suggestion and @jjdive's but neither worked. Has anyone managed to do this with vue 3 and vite?

[lightyen]

I wrote my own types for myself. https://github.com/lightyen/tailwind-types

[dolanmiu]

Simply use this from NPM:

https://www.npmjs.com/package/@types/tailwindcss

[brc-dd]

Honestly, the type definitions used here are far better than those present on DefinitelyTyped (@types/tailwindcss).

[mate-h]

For anyone looking for v3 alpha type deinitions:
https://github.com/mate-h/play.tailwindcss.com/blob/master/src/monaco/types-v3.d.ts

[iamandrewluca]

npm i -D @types/tailwindcss

tailwind.config.js

/** @type {import('tailwindcss/tailwind-config').TailwindConfig} */
module.exports = {
  // ...
}

[max-programming]

Thanks a lot!

[mshamaseen]

Am I the only one having trouble with this type? TS2339: Property 'white' does not exist on type 'TailwindThemeColors'. this error is chasing me everywhere!

[raph90]

Stuck on this right now, the only way I can see to solve it is to change the type definitions

[DylanVann]

We've improved @types/tailwindcss to be more flexible in terms of what TailwindConfig allows. So if anyone had trouble with the @type approach before it might be worth trying again. See here: DefinitelyTyped/DefinitelyTyped#56654 (comment)

I did make an attempt at adding a TailwindClass<UserConfig> type, which would use type level programming to create a type for any valid class string based on the type of a config. I was kind of having to reverse engineer how Tailwind works. Some of the conversion of the logic to types would be easier if the JS for Tailwind was more declarative, or written in a way that had types in mind.

I decided to call it quits because of that difficulty. If there's ever any interest in converting Tailwind to TypeScript and adding ResolvedConfig<UserConfig> and TailwindClass<UserConfig> types I could possibly help.

[mate-h]

Solid effort! I think you are right though it needs to be authored with typescript in mind!

[sergeyzwezdin]

@adamwathan do you have any plans to integrate TS types into tailwind as a 1st class? DefinitelyTyped is great, but 1st class support is much better.

[PooSham]

Is there an issue (feature request) or PR on this topic? I can't find any, maybe we should open one? I would love to have type definitions maintained by the Tailwind team and being able to use the .ts extension for the config file instead of relying on jsdoc hacks.

[hanneswidrig]

Considering vite uses a .ts config file first-class, would be great if we can move in that direction for tailwindcss.

[raph90]

does anyone know how to get this working with resolveConfig?
This is what I'm doing -

import resolveConfig from 'tailwindcss/resolveConfig'
import tailwindConfig from '../../../tailwind.config.js'

const fullConfig = resolveConfig(tailwindConfig)
const blue = fullConfig.theme.colors.blue

But I get Property 'blue' does not exist on type 'TailwindThemeColors'. Property 'blue' does not exist on type '(getters: { theme: any; negative: any; colors: any; breakpoints: any; }) => TailwindValuesColor'.

Even though I have

/** @type {import('tailwindcss/tailwind-config').TailwindConfig} */
module.exports = {
...

[andykenward]

See #8920 (comment) for a workaround until #8924 is released.

[misha-otto]

The problem remains in version 3.1.8

Our workaround:

export const tailwindConfig = resolveTailwindConfig(rawTailwindConfig) as any

[xxRockOnxx]

I addressed this in this PR: #9784
there doesn't seem to be any other way in Typescript.
related SO question I found about typing object literal: https://stackoverflow.com/a/74375879/10975709

[vdawg-git]

Anyone found a solution to this?

[AdisonCavani]

I created this ugly looking "work-around":

import tailwindConfig from "../tailwind.config.js";
import resolveConfig from "tailwindcss/resolveConfig";

const cfg = resolveConfig(tailwindConfig).theme!;

type NonNullableConfig = {
  [K in keyof typeof cfg]-?: NonNullable<(typeof cfg)[K]>;
};

export const twindConfig = cfg as NonNullableConfig;

type ColorIndex = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
export type ColorRecordType = Record<ColorIndex, string>;

If I want to access my colors:

const white = twindConfig.colors.white as string;
const blue600 = (twindConfig.colors.blue as ColorRecordType)[600];

[binaryartifex]

So for anyone pulling their hair out over fully inferred custom tailwind configs, try using typescripts satisfies keyword instead of directly declaring the type of your exported config as Config. For context this solution is within an NX monorepo. I have a root level tailwind-workspace-preset.ts that all relevent application level tailwind configs inherit from (as a preset). But id also like the ability to use my config directly when required.

Root config within the workspace that all other tailwind configs inherit

// tailwind-workspace-config.ts
import type { Config } from "tailwindcss/types/config";

const config = {
  content: [],
  theme: {
    extend: {
      colors: {
        foo: "#ffffff",
      },
    },
  },
} satisfies Config;

export default config;

Exporting the theme within a library called 'ui' in the libs/web/common folder.

// libs/web/common/ui/src/lib/theme.ts
import resolveConfig from "tailwindcss/resolveConfig";
// eslint-disable-next-line @nx/enforce-module-boundaries
import config from "../../../../../../../tailwind-workspace-preset";

export const theme = resolveConfig(config).theme;

export const fooColor = theme.colors.foo; // <-- typescript is inferring my custom color and all default colors

Now go back to your tailwind config (root config?) and declare the type as const config: Config = ... and you'll see TS is now unable to infer your custom type. satisfies for the win. Hope someone finds this useful.

[YassienW]

This is it!

[T-Damer]

For types in my tailwind.config.js I do:

/** @type {import('tailwindcss/defaultConfig')} */