Skip to content

Latest commit

 

History

History
187 lines (141 loc) · 5.95 KB

react.md

File metadata and controls

187 lines (141 loc) · 5.95 KB

Use Twin with "Vanilla" React + Emotion

🔥 View the React + Emotion + Tailwind Twin starter for usage examples

Getting started

1. Install the dependencies

# React and Babel
npm install --save react react-dom @babel/core @emotion/babel-plugin-jsx-pragmatic babel-plugin-macros
# Twin and Emotion
npm install --save twin.macro @emotion/core @emotion/styled
Yarn instructions
# React and Babel
yarn add react react-dom @babel/core @emotion/babel-plugin-jsx-pragmatic babel-plugin-macros
# Twin and Emotion
yarn add twin.macro @emotion/core @emotion/styled

2. Add the global styles

Projects using Twin also use the Tailwind preflight base styles to smooth over cross-browser inconsistencies.

Twin adds the preflight base styles with the GlobalStyles import which you can add in src/App.js:

// src/App.js
import React from 'react'
import { GlobalStyles } from 'twin.macro'

const App = () => (
  <>
    <GlobalStyles />
    {/* ... */}
  </>
)

export default App

GlobalStyles also includes some @keyframes so the animate-xxx classes have animations. But if you’re not using the animate classes then you can avoid adding the extra keyframes.

3. Add the recommended config

Twin’s recommended config can be added in a couple of different places.

a) In your package.json:

// package.json
"babelMacros": {
    "twin": {
      "config": "tailwind.config.js",
      "preset": "emotion",
      "debugProp": true,
      "debugPlugins": false,
      "debug": false,
    }
},

b) Or in a new file named babel-plugin-macros.config.js placed in your project root:

// babel-plugin-macros.config.js
module.exports = {
  twin: {
    config: 'tailwind.config.js',
    preset: 'emotion',
    debugProp: true,
    debugPlugins: false,
    debug: false,
  },
}

4. Enable babel macros and the jsx pragma

To use the tw and css props, emotion must first extend jsx with a jsx pragma.

a) Auto inject the pragma:

You can avoid adding the pragma yourself with the following babel config:

// In .babelrc
{
  "plugins": [
    "babel-plugin-macros",
    [
      "@emotion/babel-plugin-jsx-pragmatic",
      {
        "export": "jsx",
        "import": "__cssprop",
        "module": "@emotion/core"
      }
    ],
    ["babel-plugin-transform-react-jsx", { "pragma": "__cssprop" }]
  ]
}

Then you can import react like normal:

import React from 'react'
import tw from 'twin.macro'

const Input = () => <input tw="bg-black" />
// or
const Input = () => <input css={tw`bg-black`} />

b) Or add the jsx pragma manually:

// In .babelrc
{
  "plugins": [
    "babel-plugin-macros",
    "babel-plugin-transform-react-jsx"
  ]
}

Then when styling with the tw/css prop, add the two lines for the pragma at the top of your file. This will replace the react import:

/** @jsx jsx */
import { jsx } from '@emotion/core'
import tw from 'twin.macro'

const Input = () => <input tw="bg-black" />
// or
const Input = () => <input css={tw`bg-black`} />

Note: After build, if you’re seeing "process is not defined" then npm install and add "babel-plugin-transform-inline-environment-variables" to .babelrc

5. Add the types for css and styled (TypeScript only)

Twin comes with types for every import except the css and styled imports.

Add the remaining types →

Options

Name Type Default Description
config string "tailwind.config.js" The path to your Tailwind config
preset string "emotion" The css-in-js library behind the scenes - also supports 'styled-components' and 'goober'
hasSuggestions boolean true Display class suggestions when a class can't be found
debugPlugins boolean false Display generated class information in your terminal from your plugins
debugProp boolean false Add a prop to your elements in development so you can see the original tailwind classes, eg: <div data-tw="bg-black" />
debug boolean false Display information in your terminal about the Tailwind class conversions

If twin’s default styled and css imports need to be adjusted, you can do so with the following config:

{
  styled: { import: "default", from: "@emotion/styled" },
  css: { import: "css", from: "@emotion/core" }
}

Note: Make sure you remove the preset option as that value disables the styled + css options.

Next steps

Installation guides