2nd/10_Wiki/Topics/Frontend/CSS Modules.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-css-modules	CSS Modules	10_Wiki/Topics	verified	self	CSS Module Locally-Scoped CSS	none	A	0.9	applied	css frontend scoping build-tool		2026-05-10	pending	language framework css webpack/vite

CSS Modules

매 한 줄

"매 class 가 file-locally scoped". CSS Modules 매 build-time transform 으로 매 class name 을 unique hash 로 rewriting — 매 global namespace pollution 의 elimination + component-level encapsulation 의 enable. 매 2026 현재 Vite/Webpack/Next.js 매 native support, 매 CSS-in-JS runtime cost 의 alternative 로 주류.

매 핵심

매 작동 원리

• Button.module.css 매 import 시 매 bundler 가 매 class 를 Button_primary__a3fG2 로 rename.
• 매 import 결과 매 object — { primary: 'Button_primary__a3fG2' }.
• 매 component 매 styles.primary 로 reference — 매 collision-free.

매 vs alternatives

• vs global CSS: 매 scoping 자동, 매 BEM 매 manual convention 의 replacement.
• vs CSS-in-JS: 매 zero runtime, 매 build-time only — 매 bundle size + perf 우위.
• vs Tailwind: 매 component-local custom design 매 적합, Tailwind 매 utility-first.

매 응용

1. Component library (Button, Input) 매 encapsulated styling.
2. Next.js 매 default-supported pattern — *.module.css 매 convention.
3. Design system 매 token + component 매 layered structure.

💻 패턴

Basic usage

/* Button.module.css */
.primary {
  background: #0070f3;
  color: white;
  padding: 8px 16px;
  border-radius: 4px;
}

.disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

// Button.tsx
import styles from './Button.module.css';

export function Button({ disabled, children }: Props) {
  return (
    <button
      className={`${styles.primary} ${disabled ? styles.disabled : ''}`}
      disabled={disabled}
    >
      {children}
    </button>
  );
}

Composition (composes)

/* base.module.css */
.button {
  font: inherit;
  cursor: pointer;
}

/* Button.module.css */
.primary {
  composes: button from './base.module.css';
  background: #0070f3;
}

clsx 와 conditional classes

import clsx from 'clsx';
import styles from './Card.module.css';

export function Card({ variant, active }: Props) {
  return (
    <div className={clsx(styles.card, styles[variant], active && styles.active)}>
      ...
    </div>
  );
}

TypeScript typed module

// Button.module.css.d.ts (auto-generated by typescript-plugin-css-modules)
declare const styles: {
  readonly primary: string;
  readonly disabled: string;
};
export default styles;

:global escape hatch

/* Layout.module.css */
.root :global(.markdown) h1 {
  /* unscoped — for third-party HTML */
  font-size: 2rem;
}

Vite config

// vite.config.ts
export default {
  css: {
    modules: {
      localsConvention: 'camelCaseOnly',
      generateScopedName: '[name]__[local]__[hash:base64:5]',
    },
  },
};

매 결정 기준

상황	Approach
Component-scoped styling, zero runtime	CSS Modules
Dynamic styles (props-driven)	CSS-in-JS (vanilla-extract, styled-components)
Utility-first, rapid prototyping	Tailwind
Server Components 매 styling	CSS Modules (Tailwind 도 OK)

기본값: Next.js / Vite 매 component-level styling 의 first choice 로 CSS Modules.

🔗 Graph

• 부모: CSS · Build Tool
• 변형: CSS-in-JS · Tailwind CSS · BEM
• 응용: Next.js · Vite · React
• Adjacent: Vanilla-Extract · PostCSS

🤖 LLM 활용

언제: component encapsulation 매 필요, runtime cost 의 회피, TypeScript-friendly typing. 언제 X: 매 dynamic theming 매 heavy (variant explosion), 매 design token 매 runtime mutation 매 필요 — vanilla-extract / CSS variables.

❌ 안티패턴

• :global 매 남용: 매 scoping benefit 의 nullification.
• String concatenation 매 raw: 매 clsx 의 사용 — 매 readability + falsy handling.
• styles['kebab-case'] access 매 unnecessarily: 매 localsConvention: 'camelCaseOnly' 매 설정.
• Module 1개 매 100+ classes: 매 split — 매 component-per-module.

🧪 검증 / 중복

• Verified (Next.js docs 2026, Vite CSS Modules guide).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — CSS Modules build-time scoping + composition + Vite/Next 통합