Add Tailwind CSS to an Existing Next.js Project

If you have an existing Next.js project using plain CSeS or CSS modules, you may decide to add Tailwind CSS at some point. During recent years, Tailwind CSS has become increasingly popular for its simplicity and ease-of-use.

The good news is Tailwind can inter-op with plain CSS and CSS modules quite easily without affecting your existing work. At the same time, this makes it easy to adopt gradually, even in big projects with lots of custom styling already.

Adding Tailwind CSS to the Project

To add Tailwind to an existing Next.js project, you can follow these steps.

1. Install Tailwind Package

Install the tailwindcss package with yarn or npm by running

yarn add tailwindcss

2. Add (or Update) postcss.config.js

If you don’t already have a postcss.config.js file in your project’s root, create one with the following contents:

// postcss.config.js

module.exports = {
  "plugins": [
    ["tailwindcss", {}]
  ]
}

If you do already have a postcss.config.js file, just add the tailwindcss plugin to the list of plugins like above.

3. Add Tailwind Config File

Create a tailwind.config.js or tailwind.config.ts file in your project’s root with the following contents:

// tailwind.config.ts
// This example is using TypeScript instead of plain JavaScript

import type { Config } from "tailwindcss";

const config: Config = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
 
    // Or if using `src` directory:
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

export default config;

Or if you prefer plain JavaScript:

// tailwind.config.js
// This is for JavaScript

module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
 
    // Or if using `src` directory:
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

4. Add Tailwind Directives to globals.css File

Your Next.js project should already have a globals.css file or equivalent. Add the Tailwind directives at the top of it:

/* globals.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

/* rest of css code */

5. Test it Out!

Start your dev server with yarn run dev and test out some Tailwind CSS in your React code. You can do something like the following:

// index.tsx

export default function Home() {
  return (
    <div className="text-green-400 font-bold underline">
      Hello world!
    </div>
  )
}

You should see some green text, underlined in bold!

Inter-oping Tailwind CSS with Existing CSS & CSS Modules

If you’re already using regular CSS or CSS modules in your project, thankfully you can use Tailwind CSS class names with existing class names.

CSS modules just output a class name, so we can use our CSS module classes in addition to the Tailwind classes.

Using Tailwind Classes with CSS Modules

CSS modules just outputs unique class names. Because of this, we can use existing CSS module classes with Tailwind CSS by using template literals:

// index.tsx
import styles from '@/styles/pages/Home.module.css'

export default function Home() {
  return (
    <div className={`${styles.styled_text} text-green-400 font-bold underline`}>
      Hello world!
    </div>
  )
}

This will combine our rules from our existing CSS modules with the Tailwind classes we’ve added.

Optional: Disabling Opinionated Default Tailwind Styling Decisions

When you install Tailwind, it makes some opinionated default styling decisions on some elements to normalize the look across browsers. This is fine for new projects, but if you’ve been using CSS modules up until this point, it may mess up some of your existing styling.

To disable this behaviour, you can add the option preflight: false under the corePlugins option in your Tailwind config file, like so:

// tailwind.config.ts
// This example is using TypeScript instead of plain JavaScript

import type { Config } from "tailwindcss";

const config: Config = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
  corePlugins: {
    preflight: false
  }
}

export default config;

This will disable the default normalization styling decisions Tailwind makes, such as making all headers normal-sized text and not bold.

Remarks

• This guide was adapted from the official Tailwind guide to go more in depth, and assumes the use of newer standards such as TypeScript.
• Some guides mention installing postcss and autoprefixer packages in addition to Tailwind, but this isn’t necessary since Next.js comes with PostCSS support built-in.