@twind/typescript-plugin

TypeScript language service plugin that adds IntelliSense for Twind

If you are using VS Code as your editor – you can try our new Twind Intellisense for VS Code extension:

Install via the Visual Studio Code Marketplace →

• Features
• Installation
• Usage
• Configuration
• Contribute
• License

Features

• IntelliSense for twind variants and classes within
  • tw and apply
  • JSX attributes (tw, class, and className)
  • style and styled (like @twind/react or @twind/solid)
• Quick Info about
  • generated CSS
  • used theme value
  • the px value for rem values
• Color preview
• Support for grouping of variants and classes
• Warnings on
  • unknown classes
  • unknown theme values
  • unknown variants

Installation

npm install --save-dev typescript @twind/typescript-plugin

Usage

This plugin requires TypeScript 4.1 or later. It can provide intellisense in both JavaScript and TypeScript files within any editor that uses TypeScript to power their language features. This includes VS Code, Sublime with the TypeScript plugin, Atom with the TypeScript plugin, Visual Studio, and others.

If you have a custom twind configuration you need to extract that into an own file. Create a twind.config.{ts,js,cjs,mjs} in the root , src, config, or public folder. Then import it for use with setup. Here is example using a custom plugin:

import { forms, formInput } from '@twind/forms'

/** @type {import('twind').Configuration} */
export default {
  plugins: { forms, 'form-input': formInput}
}

// Augment the twind module to add addtional completions
declare module 'twind' {
  interface Plugins {
    // forms should have been detected from setup – not need to add it
    // forms: ''

    // We want to add sm and lg modifiers to the form-input
    'form-input':
      | ''    // plain form-input
      | 'sm' // form-input-sm
      | 'lg' // form-input-lg
  }
}

If no twind.config.{ts,js,cjs,mjs} exists and a tailwind.config.{ts,js,cjs,mjs} is found, the compatible values from the tailwind config will be used.

Add a plugins section to your tsconfig.json or jsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@twind/typescript-plugin"
      }
    ]
  }
}

See Configuration below for details options.

With VS Code

Currently you must manually install the plugin along side TypeScript in your workspace.

Finally, run the Select TypeScript version command in VS Code to switch to use the workspace version of TypeScript for VS Code's JavaScript and TypeScript language support. You can find more information about managing typescript versions in the VS Code documentation.

By default VS Code will not trigger completions when editing "string" content, for example within JSX attribute values. Updating the editor.quickSuggestions setting may improve your experience, particularly when editing Tailwind classes within JSX:

{
  "editor.suggest.showStatusBar": true,
  "editor.quickSuggestions": {
    "strings": true
  }
}

With Sublime

This plugin works with the Sublime TypeScript plugin.

And configure Sublime to use the workspace version of TypeScript by setting the typescript_tsdk setting in Sublime:

{
  "typescript_tsdk": "/path/to/the/project/node_modules/typescript/lib"
}

With Atom

This plugin works with the Atom TypeScript plugin.

To get sytnax highlighting for styled strings in Atom, consider installing the language-babel extension.

With Visual Studio

This plugin works Visual Studio 2017 using the TypeScript 2.5+ SDK.

Then reload your project to make sure the plugin has been loaded properly. Note that jsconfig.json projects are currently not supported in VS.

Configuration

Tags

This plugin adds IntelliSense to any template literal tagged with tw or apply:

import { tw } from 'twind'

tw`
  sm:hover:(
    bg-black
    text-white
  )
  md:(bg-white hover:text-black)
`

You can enable IntelliSense for other tag names by configuring "tags":

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@twind/typescript-plugin",
        "tags": ["tw", "cx"]
      }
    ]
  }
}

Now strings tagged with either tw and cx will have IntelliSense.

Attributes

This plugin adds IntelliSense to JSX tw, class, and className attributes:

<span
  className="text-purple-400"
  tw={`
    sm:hover:(
      bg-black
      text-white
    )
    md:(bg-white hover:text-black)
  `}
>...</span>
`

You can enable IntelliSense for other attributes by configuring "attributes":

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@twind/typescript-plugin",
        "attributes": ["tw"]
      }
    ]
  }
}

Now only the tw attribute will have IntelliSense.

Styles

This plugin adds IntelliSense to style and styled (like @twind/react or @twind/solid)

// Same for style({... })
const Button = styled("button", {
  base: `
    appearance-none border-none bg-transparent
    rounded-full px-2.5
  `,

  variants: {
    variant: {
      gray: `
        bg-gray-500
        hover:bg-gray-600
      `,
      primary: `
        text-white bg-purple-500
        hover:bg-purple-600
      `,
    },

    outlined: {
      true: `bg-transparent ring-1`,
    },
  },

  matches: [
    {
      variant: "gray",
      outlined: true,
      use: `ring-gray-500`,
    },
  }
})

You can enable IntelliSense for other style like functions by configuring "styles":

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@twind/typescript-plugin",
        "styles": ["styled", "stitched"]
      }
    ]
  }
}

Now the styled and stitched functions will have IntelliSense.

Debug

Allows to enabling/disabling additional debug information shown in hover and completion popups (default: false).

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@twind/typescript-plugin",
        "debug": true
      }
    ]
  }
}

Now the debug information is shown.

Enable

Allows to enabling/disabling the plugin (default: true).

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@twind/typescript-plugin",
        "debug": false
      }
    ]
  }
}

Now the plugin is disabled.

Contribute

Thanks for being willing to contribute!

This project is free and open-source, so if you think this project can help you or anyone else, you may star it on GitHub. Feel free to open an issue if you have any idea, question, or you've found a bug.

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

We are following the Conventional Commits convention.

Develop

Ensure you run at least Node v14.

Clone the repository and cd into the project directory.

Run yarn install && yarn build.

• yarn test: Run test suite including linting
• yarn format: Ensure consistent code style
• yarn build: Build the package
• yarn release: To publish the package

Manual testing the Language service plugin

You can check manually language service plugin features with our example project.

yarn build
cd dist
yarn link
cd project-fixtures/react-apollo-prj
yarn install
yarn link @twind/typescript-plugin
code . # Or launch editor/IDE what you like

Of course, you can use other editor which communicates with tsserver.

To see typescript debug logs start your editor with TSS_LOG="-logToFile true -file /path/to/tss.log -level verbose".

License

MIT