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

Author: RobinMalfait

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'