Add TypeScript types for the tailwind.config.js file (#7891)

* add generate-types script

This script will generate the full list of core plugins, which will
allow you to get code completion for the `corePlugins` section.

It will also generate all the colors (and deprecated colors) which is
used in multiple places in the config.

* add types for the `tailwind.config.js` config file

* annotate stubs with a JSDoc pointing to the types

* add types to package.json

- Updated the files to make sure that the types are being published
- Add a `types` section in the `package.json`, otherwise your editor by
  default will look for the `DefinitelyTyped` types which got me really
  confused for a second.
- Added some scripts to make sure that the generation of types happens
  when needed (before tests and before building). This way you never
  ever have to think about generating them when working on Tailwind CSS
  internals.

* re-export types top-level

Having a `colors.d.ts` next to the `colors.js` file allows us to type
the `colors.js` file and your editor will pickup the types from
`colors.d.ts`.

* also publish generated types

* update changelog

* enable TypeScript only when using `init --types` for now

* update tests to verify that `--types` works

CHANGELOG.md

@@ -36,6 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support customizing class name when using `darkMode: 'class'` ([#5800](https://github.com/tailwindlabs/tailwindcss/pull/5800))
 - Add `--poll` option to the CLI ([#7725](https://github.com/tailwindlabs/tailwindcss/pull/7725))
 - Add new `border-spacing` utilities ([#7102](https://github.com/tailwindlabs/tailwindcss/pull/7102))
+- Add TypeScript types for the `tailwind.config.js` file ([#7891](https://github.com/tailwindlabs/tailwindcss/pull/7891))
 
 ## [3.0.23] - 2022-02-16
 

colors.d.ts

@@ -0,0 +1,3 @@
+import type { DefaultColors } from './types/generated/colors'
+declare const colors: DefaultColors
+export = colors

defaultConfig.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from './types/config'
+declare const config: Config
+export = config

defaultTheme.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from './types/config'
+declare const theme: Config['theme']
+export = theme

integrations/tailwindcss-cli/tests/cli.test.js

@@ -319,6 +319,46 @@ describe('Init command', () => {
     // multiple keys in `theme` exists. However it loads `tailwindcss/colors`
     // which doesn't exists in this context.
     expect((await readOutputFile('../full.config.js')).split('\n').length).toBeGreaterThan(50)
+
+    expect(await readOutputFile('../full.config.js')).not.toContain(
+      `/** @type {import('tailwindcss/types').Config} */`
+    )
+  })
+
+  test('--types', async () => {
+    cleanupFile('simple.config.js')
+
+    let { combined } = await $(`${EXECUTABLE} init simple.config.js --types`)
+
+    expect(combined).toMatchInlineSnapshot(`
+      "
+      Created Tailwind CSS config file: simple.config.js
+      "
+    `)
+
+    expect(await readOutputFile('../simple.config.js')).toContain(
+      `/** @type {import('tailwindcss/types').Config} */`
+    )
+  })
+
+  test('--full --types', async () => {
+    cleanupFile('full.config.js')
+
+    let { combined } = await $(`${EXECUTABLE} init full.config.js --full --types`)
+
+    expect(combined).toMatchInlineSnapshot(`
+      "
+      Created Tailwind CSS config file: full.config.js
+      "
+    `)
+
+    // Not a clean way to test this. We could require the file and verify that
+    // multiple keys in `theme` exists. However it loads `tailwindcss/colors`
+    // which doesn't exists in this context.
+    expect((await readOutputFile('../full.config.js')).split('\n').length).toBeGreaterThan(50)
+    expect(await readOutputFile('../full.config.js')).toContain(
+      `/** @type {import('tailwindcss/types').Config} */`
+    )
   })
 
   test('--postcss', async () => {
@@ -351,6 +391,7 @@ describe('Init command', () => {
         Options:
            -f, --full               Initialize a full \`tailwind.config.js\` file
            -p, --postcss            Initialize a \`postcss.config.js\` file
+               --types              Add TypeScript types for the \`tailwind.config.js\` file
            -h, --help               Display usage information
       `)
     )

package.json

@@ -4,7 +4,7 @@
   "description": "A utility-first CSS framework for rapidly building custom user interfaces.",
   "license": "MIT",
   "main": "lib/index.js",
-  "style": "dist/tailwind.css",
+  "types": "types/index.d.ts",
   "repository": "https://github.com/tailwindlabs/tailwindcss.git",
   "bugs": "https://github.com/tailwindlabs/tailwindcss/issues",
   "homepage": "https://tailwindcss.com",
@@ -13,18 +13,20 @@
     "tailwindcss": "lib/cli.js"
   },
   "scripts": {
-    "preswcify": "npm run generate:plugin-list && rimraf lib",
+    "preswcify": "npm run generate && rimraf lib",
     "swcify": "swc src --out-dir lib --copy-files",
     "postswcify": "esbuild lib/cli-peer-dependencies.js --bundle --platform=node --outfile=peers/index.js",
     "rebuild-fixtures": "npm run swcify && node -r @swc/register scripts/rebuildFixtures.js",
     "prepublishOnly": "npm install --force && npm run swcify",
     "style": "eslint .",
-    "pretest": "npm run generate:plugin-list",
+    "pretest": "npm run generate",
     "test": "jest",
     "test:integrations": "npm run test --prefix ./integrations",
     "install:integrations": "node scripts/install-integrations.js",
     "posttest": "npm run style",
-    "generate:plugin-list": "node -r @swc/register scripts/create-plugin-list.js"
+    "generate:plugin-list": "node -r @swc/register scripts/create-plugin-list.js",
+    "generate:types": "node -r @swc/register scripts/generate-types.js",
+    "generate": "npm run generate:plugin-list && npm run generate:types"
   },
   "files": [
     "src/*",
@@ -34,6 +36,8 @@
     "scripts/*.js",
     "stubs/*.stub.js",
     "nesting/*",
+    "types/**/*",
+    "*.d.ts",
     "*.css",
     "*.js"
   ],

plugin.d.ts

@@ -0,0 +1,6 @@
+import type { Config, PluginCreator } from './types/config'
+declare function createPlugin(
+  plugin: PluginCreator,
+  config?: Config
+): { handler: PluginCreator; config?: Config }
+export = createPlugin

scripts/generate-types.js

@@ -0,0 +1,52 @@
+import prettier from 'prettier'
+import { corePlugins } from '../src/corePlugins'
+import colors from '../src/public/colors'
+import fs from 'fs'
+import path from 'path'
+
+fs.writeFileSync(
+  path.join(process.cwd(), 'types', 'generated', 'corePluginList.d.ts'),
+  `export type CorePluginList = ${Object.keys(corePlugins)
+    .map((p) => `'${p}'`)
+    .join(' | ')}`
+)
+
+let colorsWithoutDeprecatedColors = Object.fromEntries(
+  Object.entries(Object.getOwnPropertyDescriptors(colors))
+    .filter(([_, { value }]) => {
+      return typeof value !== 'undefined'
+    })
+    .map(([name, definition]) => [name, definition.value])
+)
+
+let deprecatedColors = Object.entries(Object.getOwnPropertyDescriptors(colors))
+  .filter(([_, { value }]) => {
+    return typeof value === 'undefined'
+  })
+  .map(([name, definition]) => {
+    let warn = console.warn
+    let messages = []
+    console.warn = (...args) => messages.push(args.pop())
+    definition.get()
+    console.warn = warn
+    let message = messages.join(' ').trim()
+    let newColor = message.match(/renamed to `(.*)`/)[1]
+    return `/** @deprecated ${message} */${name}: DefaultColors['${newColor}'],`
+  })
+  .join('\n')
+
+fs.writeFileSync(
+  path.join(process.cwd(), 'types', 'generated', 'colors.d.ts'),
+  prettier.format(
+    `export interface DefaultColors { ${JSON.stringify(colorsWithoutDeprecatedColors).slice(
+      1,
+      -1
+    )}\n${deprecatedColors}\n}`,
+    {
+      semi: false,
+      singleQuote: true,
+      printWidth: 100,
+      parser: 'typescript',
+    }
+  )
+)

src/cli.js

@@ -151,6 +151,10 @@ let commands = {
     args: {
       '--full': { type: Boolean, description: 'Initialize a full `tailwind.config.js` file' },
       '--postcss': { type: Boolean, description: 'Initialize a `postcss.config.js` file' },
+      '--types': {
+        type: Boolean,
+        description: 'Add TypeScript types for the `tailwind.config.js` file',
+      },
       '-f': '--full',
       '-p': '--postcss',
     },
@@ -209,7 +213,7 @@ if (
   help({
     usage: [
       'tailwindcss [--input input.css] [--output output.css] [--watch] [options...]',
-      'tailwindcss init [--full] [--postcss] [options...]',
+      'tailwindcss init [--full] [--postcss] [--types] [options...]',
     ],
     commands: Object.keys(commands)
       .filter((command) => command !== 'build')
@@ -336,6 +340,13 @@ function init() {
       'utf8'
     )
 
+    if (args['--types']) {
+      let typesHeading = "/** @type {import('tailwindcss/types').Config} */"
+      stubFile =
+        stubFile.replace(`module.exports = `, `${typesHeading}\nconst config = `) +
+        '\nmodule.exports = config'
+    }
+
     // Change colors import
     stubFile = stubFile.replace('../colors', 'tailwindcss/colors')
 

types.d.ts

@@ -0,0 +1 @@
+export type { Config } from './types/config'

types/config.d.ts

@@ -0,0 +1,322 @@
+import type { CorePluginList } from './generated/CorePluginList'
+import type { DefaultColors } from './generated/colors'
+
+// Helpers
+type Expand<T> = T extends object
+  ? T extends infer O
+    ? { [K in keyof O]: Expand<O[K]> }
+    : never
+  : T
+type KeyValuePair<K extends keyof any = string, V = string> = Record<K, V>
+interface RecursiveKeyValuePair<K extends keyof any = string, V = string> {
+  [key: string]: V | RecursiveKeyValuePair<K, V>
+}
+type ResolvableTo<T> = T | ((utils: PluginUtils) => T)
+
+interface PluginUtils {
+  colors: DefaultColors
+  theme(path: string, defaultValue: unknown): keyof ThemeConfig
+  breakpoints<I = Record<string, unknown>, O = I>(arg: I): O
+  rgb(arg: string): (arg: Partial<{ opacityVariable: string; opacityValue: number }>) => string
+  hsl(arg: string): (arg: Partial<{ opacityVariable: string; opacityValue: number }>) => string
+}
+
+// Content related config
+type FilePath = string
+type RawFile = { raw: string; extension?: string }
+type ExtractorFn = (content: string) => string[]
+type TransformerFn = (content: string) => string
+type ContentConfig =
+  | (FilePath | RawFile)[]
+  | {
+      files: (FilePath | RawFile)[]
+      extract?: ExtractorFn | { [extension: string]: ExtractorFn }
+      transform?: TransformerFn | { [extension: string]: TransformerFn }
+    }
+
+// Important related config
+type ImportantConfig = boolean | string
+
+// Prefix related config
+type PrefixConfig = string
+
+// Separator related config
+type SeparatorConfig = string
+
+// Safelist related config
+type SafelistConfig =
+  | string[]
+  | {
+      pattern: RegExp
+      variants: string[]
+    }[]
+
+// Presets related config
+type PresetsConfig = Config[]
+
+// Future related config
+type FutureConfigValues = never // Replace with 'future-feature-1' | 'future-feature-2'
+type FutureConfig = Expand<'all' | Partial<Record<FutureConfigValues, boolean>>> | []
+
+// Experimental related config
+type ExperimentalConfigValues = 'optimizeUniversalDefaults' // Replace with 'experimental-feature-1' | 'experimental-feature-2'
+type ExperimentalConfig = Expand<'all' | Partial<Record<ExperimentalConfigValues, boolean>>> | []
+
+// DarkMode related config
+type DarkModeConfig =
+  /** Use the `media` query strategy. */
+  | 'media'
+  /** Use the `class` stategy, which requires a `.dark` class on the `html`. */
+  | 'class'
+  /** Use the `class` stategy with a custom class instead of `.dark`. */
+  | ['class', string]
+
+// Theme related config
+interface ThemeConfig {
+  extend: Partial<Omit<ThemeConfig, 'extend'>>
+
+  /** Responsiveness */
+  screens: ResolvableTo<KeyValuePair>
+
+  /** Reusable base configs */
+  colors: ResolvableTo<RecursiveKeyValuePair>
+  spacing: ResolvableTo<KeyValuePair>
+
+  /** Components */
+  container: ResolvableTo<
+    Partial<{
+      screens:
+        | string[] /** List of breakpoints. E.g.: '400px', '500px' */
+        /** Named breakpoints. E.g.: { sm: '400px' } */
+        | Record<string | number, string>
+        /** Name breakpoints with explicit min and max values. E.g.: { sm: { min: '300px', max: '400px' } } */
+        | Record<string, { min: string; max: string }>
+      center: boolean
+      padding: string | Record<string, string>
+    }>
+  >
+
+  /** Utilities */
+  inset: ThemeConfig['spacing']
+  zIndex: ResolvableTo<KeyValuePair>
+  order: ResolvableTo<KeyValuePair>
+  gridColumn: ResolvableTo<KeyValuePair>
+  gridColumnStart: ResolvableTo<KeyValuePair>
+  gridColumnEnd: ResolvableTo<KeyValuePair>
+  gridRow: ResolvableTo<KeyValuePair>
+  gridRowStart: ResolvableTo<KeyValuePair>
+  gridRowEnd: ResolvableTo<KeyValuePair>
+  margin: ThemeConfig['spacing']
+  aspectRatio: ResolvableTo<KeyValuePair>
+  height: ThemeConfig['spacing']
+  maxHeight: ThemeConfig['spacing']
+  minHeight: ResolvableTo<KeyValuePair>
+  width: ThemeConfig['spacing']
+  maxWidth: ResolvableTo<KeyValuePair>
+  minWidth: ResolvableTo<KeyValuePair>
+  flex: ResolvableTo<KeyValuePair>
+  flexShrink: ResolvableTo<KeyValuePair>
+  flexGrow: ResolvableTo<KeyValuePair>
+  flexBasis: ThemeConfig['spacing']
+  borderSpacing: ThemeConfig['spacing']
+  transformOrigin: ResolvableTo<KeyValuePair>
+  translate: ThemeConfig['spacing']
+  rotate: ResolvableTo<KeyValuePair>
+  skew: ResolvableTo<KeyValuePair>
+  scale: ResolvableTo<KeyValuePair>
+  animation: ResolvableTo<KeyValuePair>
+  keyframes: ResolvableTo<KeyValuePair<string, KeyValuePair<string, KeyValuePair>>>
+  cursor: ResolvableTo<KeyValuePair>
+  scrollMargin: ThemeConfig['spacing']
+  scrollPadding: ThemeConfig['spacing']
+  listStyleType: ResolvableTo<KeyValuePair>
+  columns: ResolvableTo<KeyValuePair>
+  gridAutoColumns: ResolvableTo<KeyValuePair>
+  gridAutoRows: ResolvableTo<KeyValuePair>
+  gridTemplateColumns: ResolvableTo<KeyValuePair>
+  gridTemplateRows: ResolvableTo<KeyValuePair>
+  gap: ThemeConfig['spacing']
+  space: ThemeConfig['spacing']
+  divideWidth: ThemeConfig['borderWidth']
+  divideColor: ThemeConfig['borderColor']
+  divideOpacity: ThemeConfig['borderOpacity']
+  borderRadius: ResolvableTo<KeyValuePair>
+  borderWidth: ResolvableTo<KeyValuePair>
+  borderColor: ThemeConfig['colors']
+  borderOpacity: ThemeConfig['opacity']
+  backgroundColor: ThemeConfig['colors']
+  backgroundOpacity: ThemeConfig['opacity']
+  backgroundImage: ResolvableTo<KeyValuePair>
+  gradientColorStops: ThemeConfig['colors']
+  backgroundSize: ResolvableTo<KeyValuePair>
+  backgroundPosition: ResolvableTo<KeyValuePair>
+  fill: ThemeConfig['colors']
+  stroke: ThemeConfig['colors']
+  strokeWidth: ResolvableTo<KeyValuePair>
+  objectPosition: ResolvableTo<KeyValuePair>
+  padding: ThemeConfig['spacing']
+  textIndent: ThemeConfig['spacing']
+  fontFamily: ResolvableTo<KeyValuePair<string, string[]>>
+  fontSize: ResolvableTo<
+    | KeyValuePair<string, string>
+    | KeyValuePair<string, [fontSize: string, lineHeight: string]>
+    | KeyValuePair<
+        string,
+        [
+          fontSize: string,
+          configuration: Partial<{
+            lineHeight: string
+            letterSpacing: string
+          }>
+        ]
+      >
+  >
+  fontWeight: ResolvableTo<KeyValuePair>
+  lineHeight: ResolvableTo<KeyValuePair>
+  letterSpacing: ResolvableTo<KeyValuePair>
+  textColor: ThemeConfig['colors']
+  textOpacity: ThemeConfig['opacity']
+  textDecorationColor: ThemeConfig['colors']
+  textDecorationThickness: ResolvableTo<KeyValuePair>
+  textUnderlineOffset: ResolvableTo<KeyValuePair>
+  placeholderColor: ThemeConfig['colors']
+  placeholderOpacity: ThemeConfig['opacity']
+  caretColor: ThemeConfig['colors']
+  accentColor: ThemeConfig['colors']
+  opacity: ResolvableTo<KeyValuePair>
+  boxShadow: ResolvableTo<KeyValuePair>
+  boxShadowColor: ThemeConfig['colors']
+  outlineWidth: ResolvableTo<KeyValuePair>
+  outlineOffset: ResolvableTo<KeyValuePair>
+  outlineColor: ThemeConfig['colors']
+  ringWidth: ResolvableTo<KeyValuePair>
+  ringColor: ThemeConfig['colors']
+  ringOpacity: ThemeConfig['opacity']
+  ringOffsetWidth: ResolvableTo<KeyValuePair>
+  ringOffsetColor: ThemeConfig['colors']
+  blur: ResolvableTo<KeyValuePair>
+  brightness: ResolvableTo<KeyValuePair>
+  contrast: ResolvableTo<KeyValuePair>
+  dropShadow: ResolvableTo<KeyValuePair>
+  grayscale: ResolvableTo<KeyValuePair>
+  hueRotate: ResolvableTo<KeyValuePair>
+  invert: ResolvableTo<KeyValuePair>
+  saturate: ResolvableTo<KeyValuePair>
+  sepia: ResolvableTo<KeyValuePair>
+  backdropBlur: ThemeConfig['blur']
+  backdropBrightness: ThemeConfig['brightness']
+  backdropContrast: ThemeConfig['contrast']
+  backdropGrayscale: ThemeConfig['grayscale']
+  backdropHueRotate: ThemeConfig['hueRotate']
+  backdropInvert: ThemeConfig['invert']
+  backdropOpacity: ThemeConfig['opacity']
+  backdropSaturate: ThemeConfig['saturate']
+  backdropSepia: ThemeConfig['sepia']
+  transitionProperty: ResolvableTo<KeyValuePair>
+  transitionTimingFunction: ResolvableTo<KeyValuePair>
+  transitionDelay: ResolvableTo<KeyValuePair>
+  transitionDuration: ResolvableTo<KeyValuePair>
+  willChange: ResolvableTo<KeyValuePair>
+  content: ResolvableTo<KeyValuePair>
+}
+
+// Core plugins related config
+type CorePluginsConfig = CorePluginList[] | Expand<Partial<Record<CorePluginList, boolean>>>
+
+// Plugins related config
+type ValueType =
+  | 'any'
+  | 'color'
+  | 'url'
+  | 'image'
+  | 'length'
+  | 'percentage'
+  | 'position'
+  | 'lookup'
+  | 'generic-name'
+  | 'family-name'
+  | 'number'
+  | 'line-width'
+  | 'absolute-size'
+  | 'relative-size'
+  | 'shadow'
+export interface PluginAPI {
+  /** for registering new static utility styles */
+  addUtilities(
+    utilities: RecursiveKeyValuePair | RecursiveKeyValuePair[],
+    options?: Partial<{
+      respectPrefix: boolean
+      respectImportant: boolean
+    }>
+  ): void
+  /** for registering new dynamic utility styles */
+  matchUtilities<T>(
+    utilities: KeyValuePair<string, (value: T) => RecursiveKeyValuePair>,
+    options?: Partial<{
+      respectPrefix: boolean
+      respectImportant: boolean
+      type: ValueType | ValueType[]
+      values: KeyValuePair<string, T>
+      supportsNegativeValues: boolean
+    }>
+  ): void
+  /** for registering new static component styles */
+  addComponents(
+    components: RecursiveKeyValuePair | RecursiveKeyValuePair[],
+    options?: Partial<{
+      respectPrefix: boolean
+      respectImportant: boolean
+    }>
+  ): void
+  /** for registering new dynamic component styles */
+  matchComponents<T>(
+    components: KeyValuePair<string, (value: T) => RecursiveKeyValuePair>,
+    options?: Partial<{
+      respectPrefix: boolean
+      respectImportant: boolean
+      type: ValueType | ValueType[]
+      values: KeyValuePair<string, T>
+      supportsNegativeValues: boolean
+    }>
+  ): void
+  /** for registering new base styles */
+  addBase(base: RecursiveKeyValuePair | RecursiveKeyValuePair[]): void
+  /** for registering custom variants */
+  addVariant(name: string, definition: string | string[] | (() => string) | (() => string)[]): void
+  /** for looking up values in the user’s theme configuration */
+  theme: <TDefaultValue = Config['theme']>(
+    path?: string,
+    defaultValue?: TDefaultValue
+  ) => TDefaultValue
+  /** for looking up values in the user’s Tailwind configuration */
+  config: <TDefaultValue = Config>(path?: string, defaultValue?: TDefaultValue) => TDefaultValue
+  /** for checking if a core plugin is enabled */
+  corePlugins(path: string): boolean
+  /** for manually escaping strings meant to be used in class names */
+  e: (className: string) => string
+}
+export type PluginCreator = (api: PluginAPI) => void
+export type PluginsConfig = (PluginCreator | { handler: PluginCreator; config?: Config })[]
+
+// Top level config related
+interface RequiredConfig {
+  content: ContentConfig
+}
+
+interface OptionalConfig {
+  important: ImportantConfig
+  prefix: PrefixConfig
+  separator: SeparatorConfig
+  safelist: SafelistConfig
+  presets: PresetsConfig
+  future: FutureConfig
+  experimental: ExperimentalConfig
+  darkMode: DarkModeConfig
+  theme: ThemeConfig
+  corePlugins: CorePluginsConfig
+  plugins: PluginsConfig
+  /** Custom */
+  [key: string]: any
+}
+
+export type Config = RequiredConfig & Partial<OptionalConfig>

types/generated/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

types/index.d.ts

@@ -0,0 +1 @@
+declare namespace tailwindcss {}