CSS Modules in NextJS - Deep Dive

Overview - CSS Modules

What is it?

CSS Modules is a way to write CSS that is scoped locally to a component. Instead of styles applying globally, each CSS class is unique to the component that uses it. This prevents style conflicts and makes styling easier to manage in large projects. In Next.js, CSS Modules work out of the box for styling components.

Why it matters

Without CSS Modules, CSS styles can clash and override each other, causing unexpected designs and bugs. This makes it hard to maintain and scale projects, especially when many developers work together. CSS Modules solve this by isolating styles, so components look and behave as intended without interference. This leads to more reliable and maintainable user interfaces.

Where it fits

Before learning CSS Modules, you should understand basic CSS and how styles apply globally. Knowing React or Next.js components helps because CSS Modules style those components specifically. After mastering CSS Modules, you can explore advanced styling techniques like styled-components or Tailwind CSS for more dynamic or utility-first styling.

Mental Model

Core Idea

CSS Modules make CSS classes unique to each component, preventing style conflicts by scoping styles locally.

Think of it like...

It's like giving each room in a house its own set of furniture with unique labels, so nothing gets mixed up or misplaced between rooms.

Component A ── uses ──> styles.module.css
  │
  ├─ className: button_abc123
  │
Component B ── uses ──> styles.module.css
  │
  ├─ className: button_def456

Each 'button' class is unique per component.

Build-Up - 6 Steps

1

Foundation

What Are CSS Modules

Concept: CSS Modules scope CSS by automatically creating unique class names.

Normally, CSS classes apply globally. CSS Modules change this by renaming classes behind the scenes to be unique. For example, a class named 'button' in a CSS Module might become 'button_xyz123' in the final HTML.

Result

Styles written in CSS Modules only affect the component that imports them, avoiding conflicts.

Understanding that CSS Modules rename classes automatically helps you see how they prevent style clashes.

2

Foundation

Using CSS Modules in Next.js

Concept: Next.js supports CSS Modules by naming files with .module.css and importing them in components.

Create a file like Button.module.css with styles. In your React component, import styles from './Button.module.css' and use them as className={styles.className}. Next.js handles the unique naming automatically.

Result

Your component renders with styles scoped only to it, no global leakage.

Knowing the file naming convention and import syntax is key to using CSS Modules in Next.js.

3

Intermediate

Dynamic Class Names with CSS Modules

🤔Before reading on: do you think you can combine multiple CSS Module classes easily with string concatenation? Commit to your answer.

Concept: You can combine multiple CSS Module classes using JavaScript expressions or helper libraries.

Because styles are objects, you combine classes like className={`${styles.primary} ${styles.large}`}. For complex cases, libraries like clsx help manage conditional classes cleanly.

Result

You can apply multiple or conditional styles safely without losing the unique scoping.

Understanding that CSS Modules export an object lets you use JavaScript to build class names dynamically.

4

Intermediate

Global Styles Within CSS Modules

🤔Before reading on: do you think CSS Modules can include global CSS rules? Commit to yes or no.

Concept: CSS Modules can include global styles using the :global selector to escape local scoping.

Inside a CSS Module, writing :global(.classname) { ... } applies styles globally. This is useful for third-party libraries or global resets while keeping most styles scoped.

Result

You can mix local and global styles in the same CSS Module file when needed.

Knowing how to escape local scope helps integrate CSS Modules with global CSS requirements.

5

Advanced

CSS Modules and CSS Variables

🤔Before reading on: do you think CSS variables defined in CSS Modules are scoped or global? Commit your guess.

Concept: CSS variables can be defined locally in CSS Modules or globally, affecting how they cascade and inherit.

Defining variables inside :global or :root makes them global. Defining inside a local class scopes them to that component. This affects how themes or dynamic styles propagate.

Result

You can control variable scope to create reusable themes or component-specific styles.

Understanding variable scope in CSS Modules unlocks powerful theming and style customization.

6

Expert

CSS Modules Internals and Performance

🤔Before reading on: do you think CSS Modules add runtime overhead in the browser? Commit yes or no.

Concept: CSS Modules work by build-time processing that generates unique class names, so no runtime overhead occurs in the browser.

Next.js compiles CSS Modules during build, replacing class names with unique hashes. The browser only sees final CSS and HTML with unique classes, so performance is like normal CSS. This also means no JavaScript is needed to apply styles.

Result

CSS Modules provide scoped styles without slowing down the app or adding runtime complexity.

Knowing CSS Modules are a build-time feature explains why they are efficient and safe for production.

Under the Hood

CSS Modules are processed during the build step. The CSS file is parsed, and each class name is transformed into a unique identifier by appending a hash based on the file and class name. The JavaScript import becomes an object mapping original class names to these unique names. When the component renders, it uses these unique class names, ensuring styles apply only locally.

Why designed this way?

CSS Modules were created to solve the problem of global CSS conflicts without abandoning CSS itself. By transforming class names at build time, they avoid runtime overhead and keep CSS syntax familiar. Alternatives like inline styles or CSS-in-JS add runtime cost or complexity, so CSS Modules strike a balance between isolation and performance.

Source CSS Module File
  │
  ├─ styles.module.css (button)
  │
Build Process
  │
  ├─ Parse CSS
  ├─ Generate unique class names (button_xyz123)
  ├─ Export JS object { button: 'button_xyz123' }
  │
Component Usage
  │
  ├─ import styles
  ├─ className={styles.button} → 'button_xyz123'
  │
Browser
  │
  ├─ HTML uses unique class
  ├─ CSS applies scoped styles

Myth Busters - 4 Common Misconceptions

Quick: Do CSS Modules completely prevent all CSS conflicts in a project? Commit yes or no.

Common Belief: CSS Modules guarantee no CSS conflicts anywhere in the project.

Reality: CSS Modules only scope styles within the files that use them. Global styles or improperly used :global selectors can still cause conflicts.

Why it matters: Assuming total isolation can lead to unexpected style overrides and bugs when global CSS or third-party styles interfere.

Quick: Can you use CSS Modules with inline styles or styled-components interchangeably without issues? Commit yes or no.

Common Belief: CSS Modules, inline styles, and styled-components are interchangeable and behave the same.

Reality: They have different scopes, performance characteristics, and syntax. Mixing them without understanding can cause inconsistent styling and maintenance challenges.

Why it matters: Misusing different styling methods can confuse teams and cause bugs that are hard to trace.

Quick: Does CSS Modules add runtime JavaScript to manage styles in the browser? Commit yes or no.

Common Belief: CSS Modules require JavaScript at runtime to apply styles.

Reality: CSS Modules are processed at build time, so the browser only sees normal CSS with unique class names, no extra JS is needed.

Why it matters: Believing in runtime overhead might discourage using CSS Modules unnecessarily.

Quick: Are CSS Modules supported automatically in all React frameworks? Commit yes or no.

Common Belief: All React frameworks support CSS Modules out of the box.

Reality: Support varies. Next.js supports CSS Modules by default, but others may need configuration.

Why it matters: Assuming universal support can cause confusion and wasted time configuring projects.

Expert Zone

1

CSS Modules generate unique class names based on file path and content, so moving files can change class names and affect caching.

2

Using :global inside CSS Modules should be minimized because it breaks encapsulation and can cause subtle bugs.

3

Combining CSS Modules with CSS variables allows powerful theming but requires careful scope management to avoid conflicts.

When NOT to use

CSS Modules are not ideal when you need dynamic styling based on JavaScript logic or themes that change at runtime. In such cases, CSS-in-JS libraries like styled-components or emotion provide more flexibility. Also, for utility-first styling, Tailwind CSS is a better alternative.

Production Patterns

In production Next.js apps, CSS Modules are used for component-level styling to keep styles maintainable and isolated. Teams often combine CSS Modules with global CSS resets and utility classes. They also use build caching strategies to optimize CSS Module hash stability for faster deployments.

Connections

Shadow DOM

Both provide style encapsulation but at different layers; Shadow DOM isolates styles at the browser rendering level, CSS Modules at build time.

Understanding CSS Modules alongside Shadow DOM clarifies different approaches to style isolation and their tradeoffs.

Hash Functions

CSS Modules use hashing to generate unique class names from file and class names.

Knowing how hash functions work helps understand why CSS Modules produce stable but unique class names.

Modular Programming

CSS Modules apply the modular programming principle to styles by encapsulating CSS per component.

Seeing CSS Modules as modular programming helps appreciate their role in maintainable codebases.

Common Pitfalls

#1 Using global class names inside CSS Modules without :global causes styles not to apply.

Wrong approach:

.button { color: red; } /* expecting global style */

Correct approach:

:global(.button) { color: red; } /* applies globally */

Root cause:

Misunderstanding that CSS Modules scope all classes locally unless explicitly marked global.

#2 Concatenating CSS Module class names as strings without accessing the styles object causes no styles to apply.

Wrong approach:

className="button primary"

Correct approach:

className={`${styles.button} ${styles.primary}`}

Root cause:

Not realizing CSS Modules export an object with unique class names, not plain strings.

#3 Renaming CSS Module files without updating imports breaks styles.

Wrong approach:

Renaming Button.module.css to Button.css but still importing './Button.module.css'

Correct approach:

Rename file and update import to './Button.css' or keep naming consistent

Root cause:

Not understanding the importance of the .module.css naming convention for CSS Modules.

Key Takeaways

CSS Modules scope CSS locally by generating unique class names, preventing style conflicts.

Next.js supports CSS Modules natively by using the .module.css file naming and importing styles as objects.

You can combine multiple CSS Module classes dynamically using JavaScript expressions or helper libraries.

Global styles can be included inside CSS Modules using the :global selector but should be used sparingly.

CSS Modules are a build-time feature that add no runtime overhead, making them efficient and reliable for production.