How to use CSS Modules with Next.js?

CSS Modules provide a way to write modular, reusable, and scoped CSS by automatically generating unique class names. This is particularly beneficial for large-scale applications where class name conflicts can become an issue. Next.js, a popular React framework, has built-in support for CSS Modules, making it easy to get started without additional configuration. This article will guide you through the process of using CSS Modules with Next.js.

What are CSS Modules?

CSS Modules is an innovative approach to writing modular and reusable CSS styles in your web applications. Unlike traditional CSS, where styles are global and can potentially conflict with one another, CSS Modules encapsulates styles within a component, ensuring that styles are scoped and isolated from the rest of the application.

This modular approach to styling components brings several benefits, including:

• Eliminating naming conflicts: By automatically generating unique class names for each component, CSS Modules eliminates the risk of naming collisions, allowing you to use intuitive class names without worrying about overriding existing styles.

• Better code organization: With CSS Modules, you can co-locate your component's styles with its JavaScript code, making it easier to reason about and maintain your codebase.

• Improved performance: Since CSS Modules only includes the styles used by the rendered components, your application's CSS bundle size is optimized, leading to faster load times and better overall performance.

CSS Modules is a powerful tool that can streamline your styling workflow and enhance the maintainability of your Next.js applications.

Benefits of using CSS Modules in Next.js development

Next.js, a popular React framework for building server-rendered and static websites, provides built-in support for CSS Modules out of the box. By leveraging CSS Modules in your Next.js projects, you can enjoy several benefits:

1. Modular and Scalable Styling: As your application grows in complexity, CSS Modules can help you maintain a well-organized and scalable codebase by encapsulating styles within individual components.

2. Improved Developer Experience: With CSS Modules, you can write styles specific to a component without worrying about naming conflicts or unintended style overrides, leading to a more streamlined and efficient development process.

3. Better Collaboration: When working in a team environment, CSS Modules can facilitate better collaboration by reducing the risk of style conflicts and making it easier to reason about the styles applied to each component.

4. Optimized Performance: Next.js automatically code-splits and optimizes your CSS Modules, ensuring that only the necessary styles are loaded for each page, resulting in faster load times and improved performance.

Embracing CSS Modules in your Next.js development workflow, you can unlock a more maintainable, scalable, and performant styling solution for your web applications.

Setting Up a Next.js Project

First, ensure you have Node.js and npm (or Yarn) installed on your machine. To set up a new Next.js project, follow these steps:

1. Create a new Next.js app using the following command:

   npx create-next-app my-nextjs-app
   

   or with Yarn:

   yarn create next-app my-nextjs-app
   

2. Navigate to your project directory:

   cd my-nextjs-app
   

3. Start the development server:

   npm run dev
   

   or with Yarn:

   yarn dev
   

   Your Next.js application is now up and running at http://localhost:3000.

Creating CSS Modules

CSS Modules are simple CSS files with a .module.css extension. Let's create a CSS Module for styling a component.

1. Inside the styles directory (or create it if it doesn't exist), create a new CSS Module file named Button.module.css:

   /* styles/Button.module.css */
   .button {
     background-color: #0070f3;
     border: none;
     color: white;
     padding: 10px 20px;
     font-size: 16px;
     border-radius: 5px;
     cursor: pointer;
     transition: background-color 0.3s ease;
   }
   
   .button:hover {
     background-color: #005bb5;
   }
   

Using CSS Modules in Components

Now, let's use the CSS Module in a React component.

1. Create a new component file named Button.js inside the components directory:

   // components/Button.js
   import styles from "../styles/Button.module.css";
   
   const Button = ({ children }) => {
     return <button className={styles.button}>{children}</button>;
   };
   
   export default Button;
   

2. Use the Button component in your pages/index.js:

   // pages/index.js
   import Head from "next/head";
   import Button from "../components/Button";
   
   export default function Home() {
     return (
       <div>
         <Head>
           <title>My Next.js App</title>
           <meta name="description" content="Generated by create next app" />
         </Head>
         <main>
           <h1>Welcome to My Next.js App</h1>
           <Button>Click Me</Button>
         </main>
       </div>
     );
   }
   

When you start your development server and visit http://localhost:3000, you should see your styled button.

Nested Selectors

CSS Modules support nesting, which helps to organize styles hierarchically.

/* styles/Card.module.css */
.card {
  padding: 20px;
  border: 1px solid #eaeaea;
  border-radius: 10px;
  transition: box-shadow 0.3s ease;

  &__header {
    font-size: 24px;
    margin-bottom: 10px;
  }

  &__body {
    font-size: 16px;
  }

  &:hover {
    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
  }
}

Use these nested selectors in your component:

// components/Card.js
import styles from "../styles/Card.module.css";

const Card = ({ header, body }) => {
  return (
    <div className={styles.card}>
      <div className={styles.card__header}>{header}</div>
      <div className={styles.card__body}>{body}</div>
    </div>
  );
};

export default Card;

Composition

CSS Modules allow you to compose classes from other modules or within the same module.

/* styles/Button.module.css */
.button {
  background-color: #0070f3;
  border: none;
  color: white;
  padding: 10px 20px;
  font-size: 16px;
  border-radius: 5px;
  cursor: pointer;
  transition: background-color 0.3s ease;
}

.buttonSecondary {
  composes: button;
  background-color: #eaeaea;
  color: #333;
}

Use the composed class in your component:

// components/SecondaryButton.js
import styles from "../styles/Button.module.css";

const SecondaryButton = ({ children }) => {
  return <button className={styles.buttonSecondary}>{children}</button>;
};

export default SecondaryButton;

Advanced CSS Modules Techniques with Next.js

Beyond the basics, CSS Modules offer several advanced techniques and best practices to further enhance the development process. Here are some additional tips and advanced features you can leverage when using CSS Modules with Next.js.

CSS Variables and Custom Properties

CSS Variables (Custom Properties) provide a way to define variables in your CSS files, which can be particularly useful for theming and maintaining consistency.

/* styles/variables.module.css */
:root {
  --primary-color: #0070f3;
  --secondary-color: #eaeaea;
  --font-size: 16px;
}

Use these variables in your CSS Modules:

/* styles/Button.module.css */
@import "./variables.module.css";

.button {
  background-color: var(--primary-color);
  border: none;
  color: white;
  padding: 10px 20px;
  font-size: var(--font-size);
  border-radius: 5px;
  cursor: pointer;
  transition: background-color 0.3s ease;
}

.buttonSecondary {
  background-color: var(--secondary-color);
  color: var(--primary-color);
}

Scoped Animations

You can define animations within your CSS Modules, ensuring they are scoped to the specific component.

/* styles/AnimatedButton.module.css */
@keyframes fadeIn {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

.animatedButton {
  animation: fadeIn 1s ease-in-out;
}

Use the animation in your component:

// components/AnimatedButton.js
import styles from "../styles/AnimatedButton.module.css";

const AnimatedButton = ({ children }) => {
  return <button className={styles.animatedButton}>{children}</button>;
};

export default AnimatedButton;

Dynamic Class Names

Sometimes you need to apply multiple class names conditionally. You can achieve this by using libraries like classnames.

First, install the classnames library:

npm install classnames

Then, use it in your component:

// components/Button.js
import classNames from "classnames";
import styles from "../styles/Button.module.css";

const Button = ({ children, isSecondary }) => {
  const buttonClass = classNames({
    [styles.button]: true,
    [styles.buttonSecondary]: isSecondary,
  });

  return <button className={buttonClass}>{children}</button>;
};

export default Button;

Using SCSS with CSS Modules

Next.js also supports SCSS Modules, allowing you to use Sass features such as variables, nesting, and mixins.

1. Install sass:

   npm install sass
   

2. Create an SCSS Module file with a .module.scss extension:

   /* styles/Button.module.scss */
   $primary-color: #0070f3;
   $secondary-color: #eaeaea;
   
   .button {
     background-color: $primary-color;
     border: none;
     color: white;
     padding: 10px 20px;
     font-size: 16px;
     border-radius: 5px;
     cursor: pointer;
     transition: background-color 0.3s ease;
   
     &:hover {
       background-color: darken($primary-color, 10%);
     }
   }
   
   .buttonSecondary {
     background-color: $secondary-color;
     color: $primary-color;
   }
   

3. Use the SCSS Module in your component:

   // components/Button.js
   import styles from "../styles/Button.module.scss";
   
   const Button = ({ children, isSecondary }) => {
     const buttonClass = isSecondary ? styles.buttonSecondary : styles.button;
     return <button className={buttonClass}>{children}</button>;
   };
   
   export default Button;
   

Server-Side Rendering and CSS Modules

Next.js handles server-side rendering (SSR) out of the box, and CSS Modules work seamlessly with SSR. When you build your Next.js application, CSS Modules are automatically included and optimized in the server-rendered HTML.

Consistent Naming Conventions

Adopt a consistent naming convention for your CSS class names. One common approach is the BEM (Block Element Modifier) methodology, which helps in writing clear and understandable class names.

/* styles/Card.module.css */
.card {
  &__header {
    font-size: 24px;
    margin-bottom: 10px;
  }

  &__body {
    font-size: 16px;
  }
}

Avoiding CSS Overuse

Be mindful not to overuse CSS Modules. Only use them when you need scoped styles. For global styles or themes, consider using global CSS or CSS-in-JS solutions.

/* styles/globals.css */
body {
  font-family: Arial, sans-serif;
  margin: 0;
  padding: 0;
}

Include this in your _app.js:

// pages/_app.js
import "../styles/globals.css";

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default MyApp;

Performance Optimization

To keep your application performant, ensure you:

1. Remove unused CSS.
2. Minimize the CSS payload.
3. Use tools like PurgeCSS to remove unused styles from your production build.

Theming with CSS Variables

Use CSS Variables to create a theming system. This allows for easy changes across the application by modifying just the variables.

/* styles/theme.module.css */
:root {
  --primary-color: #0070f3;
  --secondary-color: #eaeaea;
  --font-size: 16px;
}

Use these variables across your CSS Modules for a consistent design system.

Tips for optimizing CSS Modules for performance

While CSS Modules offers several benefits, it's essential to optimize their usage to ensure optimal performance in your Next.js applications. Here are some tips to help you optimize CSS Modules for better performance:

Code-splitting and lazy-loading: Next.js automatically code-splits and lazy-loads your CSS Modules, ensuring that only the necessary styles are loaded for each page. However, you can further optimize this process by splitting your application into smaller, logical chunks and leveraging dynamic imports for code-splitting.

Minification and optimization: During the production build process, Next.js automatically minifies and optimizes your CSS Modules, reducing the file size and improving load times. However, you can further optimize your CSS by removing unused styles, using shorthand properties, and leveraging CSS processing tools like PostCSS.

Critical CSS extraction: Next.js provides a built-in feature called "Critical CSS" that allows you to extract and inline the critical CSS required for rendering the initial viewport of a page. This technique can significantly improve the perceived performance by reducing the initial render-blocking CSS.

CSS Modules tree-shaking: Next.js automatically tree-shakes your CSS Modules, removing unused styles from the final bundle. To take full advantage of this feature, ensure that you're not importing entire CSS Modules files unnecessarily and only import the styles you need.

Caching and compression: Leverage browser caching and compression techniques to further improve the delivery of your CSS Modules. Next.js provides built-in support for HTTP/2 server push and Brotli compression, which can significantly improve the performance of your CSS delivery.

Following these optimization tips, you can ensure that your Next.js application leverages CSS Modules efficiently, delivering a fast and responsive user experience to your users.

Troubleshooting common issues with CSS Modules in Next.js

While CSS Modules can greatly simplify and streamline your styling workflow in Next.js, you may encounter some common issues during development or deployment. Here are some troubleshooting tips to help you resolve these issues:

Styles not being applied: If your styles are not being applied correctly, double-check your import statements and ensure that you're using the correct class names from the CSS Modules object.

Global styles not working: If you're having trouble with global styles defined using the :global selector, make sure that you're not inadvertently overriding them with other styles or that there are no specificity conflicts.

Styles not updating on hot module replacement (HMR): If your styles are not updating correctly when using HMR during development, try restarting the development server or clearing your browser cache.

Styles not being included in the production build: If your styles are not being included in the production build, ensure that you're not importing entire CSS Modules files unnecessarily. Next.js will automatically tree-shake unused styles, so only import the styles you need.

Naming conflicts with third-party libraries: In rare cases, you may encounter naming conflicts between your CSS Modules and third-party libraries that use a similar naming convention. In such cases, you can configure Next.js to use a different naming convention for CSS Modules by modifying the cssModules option in your next.config.js file.

Understanding and addressing these common issues, you can ensure a smooth development and deployment experience when working with CSS Modules in your Next.js projects.

Best practices for using CSS Modules in Next.js projects

To fully leverage the benefits of CSS Modules in your Next.js projects, it's essential to follow best practices and adopt a consistent coding style. Here are some recommended best practices for using CSS Modules in Next.js:

Consistent naming conventions: Establish and follow consistent naming conventions for your CSS Modules classes. This can help improve code readability and maintainability, especially when working in a team environment.

Modular and reusable styles: Strive to create modular and reusable styles that can be easily shared across multiple components. This can reduce code duplication and promote consistency throughout your application.

Separation of concerns: Maintain a clear separation of concerns between your component logic and its styling. Keep your CSS Modules focused on styling and avoid mixing in any non-styling-related logic.

Documentation and comments: Document your CSS Modules classes and provide clear comments to explain their purpose and usage. This can greatly improve the understandability of your codebase, especially for new team members or future contributors.

Leverage CSS preprocessors: While CSS Modules work with plain CSS, consider leveraging CSS preprocessors like Sass or Less to take advantage of features like variables, mixins, and nesting, which can enhance the maintainability and scalability of your styles.

Atomic design principles: Adopt atomic design principles when structuring your CSS Modules, breaking down your styles into smaller, reusable components that can be combined to create more complex UI elements.

Performance optimization: Regularly audit and optimize your CSS Modules for performance, following best practices such as code-splitting, minification, and tree-shaking to ensure optimal load times and rendering performance.

Adhering to these best practices, you can ensure that your Next.js projects leverage CSS Modules in a consistent, maintainable, and performant manner, enabling you to build scalable and high-quality web applications.

Frequently Asked Questions about How to use CSS Modules with Next.js?

import styles from "../styles/Button.module.css";

const Button = ({ children }) => {
  return <button className={styles.button}>{children}</button>;
};

export default Button;

npm install sass

/* styles/Button.module.scss */
.button {
  background-color: #0070f3;
  color: white;
}

import styles from "../styles/Button.module.scss";

const Button = ({ children }) => {
  return <button className={styles.button}>{children}</button>;
};

export default Button;

/* styles/variables.module.css */
:root {
  --primary-color: #0070f3;
  --secondary-color: #eaeaea;
}

.button {
  background-color: var(--primary-color);
}

npm install classnames

import classNames from "classnames";
import styles from "../styles/Button.module.css";

const Button = ({ isPrimary }) => {
  const buttonClass = classNames({
    [styles.button]: true,
    [styles.primaryButton]: isPrimary,
  });

  return <button className={buttonClass}>Click Me</button>;
};

export default Button;

/* styles/common.module.css */
.commonButton {
  padding: 10px 20px;
  border-radius: 5px;
}

/* styles/Button.module.css */
@import "./common.module.css";

.button {
  composes: commonButton;
  background-color: #0070f3;
  color: white;
}

Conclusion

CSS Modules is a powerful styling solution that can greatly enhance the development experience and maintainability of your Next.js projects. By encapsulating styles within components and eliminating naming conflicts, CSS Modules promotes modular and reusable styling practices.

Throughout this guide, we've explored the fundamentals of CSS Modules, their benefits in Next.js development, and best practices for setting up, using, and optimizing CSS Modules in your projects. We've also covered advanced techniques for organizing and managing CSS Modules, troubleshooting common issues, and ensuring optimal performance.

As you continue to build and scale your Next.js applications, embracing CSS Modules can help you maintain a well-structured and scalable codebase, facilitate better collaboration, and deliver a seamless and performant user experience. To take your Next.js development skills to the next level, consider enrolling in our comprehensive course on "Mastering Next.js for Modern Web Development." This course will provide you with in-depth knowledge and hands-on experience in building high-performance, server-rendered React applications using Next.js. From advanced routing and data fetching techniques to server-side rendering and static site generation, you'll gain the expertise to build robust and scalable web applications. Enroll now and unlock the full potential of Next.js!