Add TailwindCSS Support to Your Payload CMS Project | Tips & Tricks

Welcome to this comprehensive tutorial where we will dive into integrating Tailwind CSS into your existing Payload NextJS project. This guide is based on insights from Paul from Nuance.io, who created an excellent blog post on the topic. Whether you're a seasoned developer or just starting, this tutorial will provide you with the necessary steps to enhance your Payload CMS project with Tailwind CSS.

This article provides a detailed written step-by-step tutorial of our comprehensive video guide on integrating TailwindCSS with Payload CMS. For visual learners or those who prefer following along with video instruction, watch our complete walkthrough on YouTube at https://www.youtube.com/watch?v=RhoWLkIrMN0. The video covers the same content but offers additional context and real-time demonstrations of each step in the process, making it easier to troubleshoot any issues you might encounter along the way.

Table of Contents

• Why Tailwind CSS?
• Getting Started
• Step 3: Installing Tailwind CSS
• Step 9: Testing Dark Mode
• Common Issues & Troubleshooting
• Frequently Asked Questions
• Conclusion

Why Tailwind CSS?

Tailwind CSS is a utility-first CSS framework that allows developers to build custom designs without having to leave their HTML. It provides a set of classes that can be composed to create unique designs, making it a popular choice among developers for its flexibility and efficiency. By integrating Tailwind CSS into your Payload project, you can leverage its powerful utility classes to create stunning, responsive interfaces.

Getting Started

Before we begin, ensure that you have a working Payload NextJS project. If not, follow the setup instructions on the official Payload documentation. Once you have your project ready, we can start integrating Tailwind CSS.

Step 1: Create a Custom Component

First, let's create a custom component that utilizes Tailwind styles. This will help us visualize the changes as we integrate Tailwind CSS.

1. Create a new folder called components in your project directory.
2. Inside the components folder, create another folder named UI.
3. Within the UI folder, create a file called CustomBeforeDashboard.js.

In this file, we'll include the following code:

const CustomBeforeDashboard = () => {
    return (

Hey, this is a Tailwind component!

  );
};

export default CustomBeforeDashboard;

Step 2: Register the Custom Component

Now that we have our custom component, we need to register it in the Payload configuration file. Follow these steps:

1. Open the payload.config.js file in your project.
2. Under the admin section, add the following code:

admin: {
    components: {
        beforeDashboard: CustomBeforeDashboard,
    },
},

This allows Payload to recognize and render your custom component. Restart your server, and you should see the component appear at the top of your dashboard. However, as you might notice, the Tailwind styles are not applied yet.

Step 3: Installing Tailwind CSS

To apply Tailwind styles, we need to install several libraries. Open your terminal and run the following command:

npm install tailwindcss autoprefixer postcss postcss-loader

This command installs Tailwind CSS along with necessary dependencies like Autoprefixer, PostCSS, and the PostCSS loader. After installation, run the following command to initialize your Tailwind configuration:

npx tailwindcss init

Step 4: Configuring Tailwind

Next, we need to configure Tailwind CSS. Open the newly created tailwind.config.js file and adjust the settings as follows:

module.exports = {
    important: true,
    darkMode: 'class', // Enable dark mode
    content: ['./src/**/*.{js,jsx,ts,tsx}'],
    corePlugins: {
        preflight: false, // Disable preflight to avoid style conflicts
    },
    safelist: ['table'], // Safelist table class to avoid conflicts
};

Step 5: Creating Tailwind CSS File

Now, let's create a CSS file to import Tailwind's base styles. In the root folder of your project, create a new file named tailwind.css and add the following lines:

@tailwind components;
@tailwind utilities;

We will omit the base styles here to prevent conflicts with Payload's default styles.

Step 6: Configuring PostCSS

Next, create a postcss.config.js file in your root directory with the following content:

module.exports = {
    plugins: [
        require('tailwindcss'),
        require('autoprefixer'),
    ],
};

Step 7: Adjusting Webpack Configuration

To ensure that Tailwind CSS is compiled correctly, we need to modify the Webpack configuration in your payload.config.js file. Add the following code snippet:

webpack: (config) => {
    config.module.rules.push({
        test: /\.css$/,
        use: ['style-loader', 'css-loader', 'postcss-loader'],
    });
    return config;
},

This setup allows Webpack to process your Tailwind CSS file and apply the styles correctly.

Step 8: Running the Development Server

Now that everything is set up, it's time to start the development server. Run the following command:

npm run dev

Once the server is running, navigate to your dashboard. You should see your custom component with the Tailwind CSS styles applied!

Step 9: Testing Dark Mode

One of the great features of Tailwind CSS is its support for dark mode. To test this, simply add a data-theme attribute to your HTML element. For instance:

Now, when you refresh your dashboard, you should see the background color change accordingly.

Common Issues & Troubleshooting

When integrating Tailwind CSS with Payload, you may encounter some common issues. Here are a few tips to troubleshoot:

• Styles Not Applying: Ensure that your Tailwind configuration file includes the correct paths to your source files.
• Dark Mode Not Working: Double-check that the darkMode setting in your Tailwind configuration is set up correctly.
• Conflicting Styles: If you experience conflicts with Payload's default styles, consider disabling the preflight option in your Tailwind configuration.
  

Frequently Asked Questions

1. Can I use Tailwind CSS with other frameworks?

Yes, Tailwind CSS can be integrated with various frameworks such as React, Vue, Angular, and more. The setup process may vary slightly depending on the framework.

2. Is Tailwind CSS suitable for production?

Absolutely! Tailwind CSS is widely used in production environments. Just make sure to use PurgeCSS to remove unused styles in your production builds to optimize performance.

3. How can I customize Tailwind CSS?

Tailwind CSS is highly customizable. You can override default settings in your tailwind.config.js file, including colors, spacing, and more.

4. What if I encounter issues with Tailwind CSS?

If you face any issues, check the official Tailwind CSS documentation or the community forums for troubleshooting tips and solutions.

Conclusion

Integrating Tailwind CSS into your Payload NextJS project can significantly enhance your development experience and the quality of your application's UI. By following this step-by-step guide, you should be able to set up Tailwind CSS and start utilizing its powerful utility classes in no time. If you have any questions or need further assistance, feel free to leave a comment below!

For more tips and tricks, subscribe to our channel AllAboutPayload and check out the complete playlist for more insightful tutorials!