Setting Up @/lib/utils for ShadCN UI Components

Introduction

When using ShadCN UI components in your React or Next.js project, you might encounter an error like:

Module not found: Can't resolve '@/lib/utils'

This error occurs because ShadCN UI components rely on a utility function, cn, for conditional class name merging. This guide explains how to correctly set up the @/lib/utils path and the cn function to resolve this issue.

What Is the cn Function?

The cn function combines class names conditionally and resolves conflicts using the clsx and tailwind-merge libraries. It is commonly used in Tailwind CSS projects to simplify class name management.

Steps to Set Up @/lib/utils

Step 1: Create the Utils File

1. Add a lib Folder: Create a lib folder inside your src directory (or project root if src doesn’t exist).

   src/lib/utils.ts
   

2. Install Dependencies: Install clsx and tailwind-merge:

   npm install clsx tailwind-merge
   

3. Add the cn Function: In utils.ts, add the following code:

   import { clsx, ClassValue } from 'clsx'
   import { twMerge } from 'tailwind-merge'
   
   export function cn(...inputs: ClassValue[]) {
     return twMerge(clsx(inputs))
   }
   

Step 2: Configure Path Alias

If your project uses a path alias for @/lib/utils, ensure it is configured in your tsconfig.json or jsconfig.json file:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Step 3: Update Imports

Update your imports in the ShadCN UI components to use the alias:

import { cn } from '@/lib/utils'

Verifying the Setup

1. Test a Component: Use a ShadCN component (e.g., Dropdown) in your project and ensure it compiles without errors:

   import { cn } from "@/lib/utils";
   import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@radix-ui/react-dropdown-menu";
   
   const Example = () => (
     <DropdownMenu>
       <DropdownMenuTrigger className={cn("btn-primary")}>
         Open Menu
       </DropdownMenuTrigger>
       <DropdownMenuContent>
         <DropdownMenuItem>Item 1</DropdownMenuItem>
         <DropdownMenuItem>Item 2</DropdownMenuItem>
       </DropdownMenuContent>
     </DropdownMenu>
   );
   
   export default Example;
   

2. Run Your Project: Start your development server and ensure the component renders correctly:

   npm run dev
   

Troubleshooting

Error: "Cannot find module @/lib/utils"

• Cause: The alias is not correctly configured.
• Fix: Ensure the paths configuration in tsconfig.json or jsconfig.json matches your directory structure.

Error: "clsx is not installed"

• Cause: Missing dependencies.
• Fix: Run npm install clsx tailwind-merge.

Using Without Tailwind CSS

If you are not using Tailwind CSS, you can omit tailwind-merge and use only clsx for class name merging:

import { clsx, ClassValue } from 'clsx'

export function cn(...inputs: ClassValue[]) {
  return clsx(inputs)
}

Conclusion

By following these steps, you can resolve the @/lib/utils error and ensure smooth integration of ShadCN UI components in your project. The cn utility function simplifies class name management and is essential for working with these components effectively.