CSS Modules support in Astro - Step-by-Step Execution

Concept Flow - CSS Modules support

Write CSS Module file

↓

Import CSS Module in Astro component

↓

Use imported styles as object keys

↓

Astro compiles and scopes styles

↓

Render HTML with scoped class names

↓

Browser applies styles only to this component

This flow shows how CSS Modules are written, imported, used in Astro components, compiled with scoped class names, and applied only to that component.

Execution Sample

Astro

/* styles.module.css */
.title {
  color: blue;
}

---
---
<script>
import styles from './styles.module.css';
</script>

<h1 class={styles.title}>Hello Astro</h1>

This Astro component imports a CSS Module and applies a scoped class to an h1 element.

Execution Table

Step	Action	Input/Code	Result/Output
1	Read CSS Module file	.title { color: blue; }	CSS class '.title' defined
2	Import CSS Module	import styles from './styles.module.css';	styles = { title: 'styles_title__abc123' }
3	Use styles.title in class attribute	<h1 class={styles.title}>	h1 class='styles_title__abc123'
4	Astro compiles component	Compile Astro + CSS Module	Scoped CSS applied with unique class name
5	Render HTML in browser	<h1 class='styles_title__abc123'>Hello Astro</h1>	Text styled with blue color
6	Browser applies styles	CSS targets '.styles_title__abc123'	h1 text appears blue
7	End	No more steps	Component styled with scoped CSS

💡 All steps complete; CSS Module styles scoped and applied to component.

Variable Tracker

Variable	Start	After Step 2	After Step 3	Final
styles	undefined	{ title: 'styles_title__abc123' }	{ title: 'styles_title__abc123' }	{ title: 'styles_title__abc123' }
h1.class	undefined	undefined	'styles_title__abc123'	'styles_title__abc123'

Key Moments - 2 Insights

Why does the class name in the HTML look different from the CSS file?

Because CSS Modules rename class names to unique scoped names (like 'styles_title__abc123') to avoid conflicts, as shown in execution_table step 2 and 3.

Can I use normal CSS class names directly without importing?

No, with CSS Modules you must import the styles object and use its keys to get the scoped class names, as shown in step 2 and 3.

Visual Quiz - 3 Questions

Look at the execution table, what is the value of 'styles.title' after step 2?

A 'title'

B 'styles_title__abc123'

C '.title'

D undefined

💡 Hint

Check the 'Result/Output' column in step 2 of the execution_table.

At which step does the HTML element get the scoped class name applied?

A Step 5

B Step 1

C Step 3

D Step 7

💡 Hint

Look for when the h1 class attribute is set in the execution_table.

If you change the CSS class name in the module file from '.title' to '.header', what must you also change in the Astro component?

A Change 'styles.title' to 'styles.header'

B No changes needed

C Change import path

D Change HTML tag from h1 to header

💡 Hint

Refer to how styles keys correspond to CSS class names in variable_tracker and execution_table step 2.

Concept Snapshot

CSS Modules support in Astro:
- Write CSS in a .module.css file
- Import styles object in Astro component
- Use styles.className for scoped classes
- Astro compiles with unique class names
- Styles apply only to this component
- Prevents global CSS conflicts

Full Transcript

This visual execution shows how CSS Modules work in Astro. First, you write CSS in a file ending with .module.css. Then you import this CSS as an object in your Astro component. Each CSS class becomes a key in this object with a unique scoped name. When you use styles.className in your HTML, Astro replaces it with the scoped class name. The browser then applies these styles only to this component, avoiding conflicts with other styles. The execution table traces each step from reading the CSS file, importing styles, applying classes, compiling, and rendering. Variable tracking shows how the styles object and class attributes change. Key moments clarify why class names look different and why you must import styles. The quiz tests understanding of these steps and changes needed if CSS class names change.

Practice

1. What is the main benefit of using CSS Modules in Astro components?

easy

A. They keep styles local to components, avoiding conflicts.

B. They automatically minify CSS for faster loading.

C. They allow inline styles directly in HTML tags.

D. They enable global styles to override component styles.

Solution

1. Step 1: Understand CSS Modules purpose

   CSS Modules scope styles locally to components to prevent style conflicts.

2. Step 2: Compare options

   Only They keep styles local to components, avoiding conflicts. correctly describes this main benefit; others describe unrelated features.

3. Final Answer:

   They keep styles local to components, avoiding conflicts. -> Option A

4. Quick Check:

   CSS Modules = Local styles [OK]

Hint: Remember CSS Modules isolate styles to components [OK]

Common Mistakes:

• Thinking CSS Modules minify CSS automatically
• Confusing CSS Modules with inline styles
• Assuming CSS Modules create global styles

2. Which is the correct way to import a CSS Module file named styles.module.css in an Astro component?

easy

A. import './styles.module.css';

B. import styles from './styles.css';

C. const styles = require('./styles.module.css');

D. import styles from './styles.module.css';

Solution

1. Step 1: Identify correct import syntax for CSS Modules

   CSS Modules require importing the CSS file as an object, typically with import styles from './filename.module.css';.

2. Step 2: Check file extension and import style

   import styles from './styles.module.css'; uses the correct file extension and import syntax. import './styles.module.css'; imports without assigning, C uses CommonJS which is not standard in Astro, and D imports a non-module CSS file.

3. Final Answer:

   import styles from './styles.module.css'; -> Option D

4. Quick Check:

   Import CSS Modules as objects with .module.css [OK]

Hint: Use import with .module.css and assign to a variable [OK]

Common Mistakes:

• Forgetting to assign import to a variable
• Using require instead of import
• Importing non-module CSS files as modules

3. Given the CSS Module import import styles from './button.module.css'; and the CSS file containing .primary { color: blue; }, what will be the rendered class attribute for <button class={styles.primary}>Click</button>?

medium

A. class="button_primary__abc123"

B. class="primary"

C. class="styles.primary"

D. class="undefined"

Solution

1. Step 1: Understand CSS Modules class naming

   CSS Modules transform class names to unique strings like button_primary__abc123 to avoid conflicts.

2. Step 2: Analyze the rendered class attribute

   Using styles.primary applies the transformed unique class name, not the original 'primary'. So the class attribute will be a unique hashed string.

3. Final Answer:

   class="button_primary__abc123" -> Option A

4. Quick Check:

   CSS Modules generate unique class names [OK]

Hint: CSS Modules rename classes to unique strings [OK]

Common Mistakes:

• Expecting original class name without transformation
• Using the variable name as class string
• Getting undefined if import is wrong

4. What is wrong with this Astro component code using CSS Modules?

import styles from './card.module.css';

export default function Card() {
  return <div class="styles.card">Content</div>;
}

medium

A. The component must be a class, not a function.

B. The class attribute should use curly braces, not quotes.

C. The import statement is missing the .module.css extension.

D. CSS Modules cannot be used in Astro components.

Solution

1. Step 1: Check how class names are applied with CSS Modules

   CSS Modules require using curly braces to insert the imported class object value, e.g., class={styles.card}.

2. Step 2: Identify the error in the code

   The code uses quotes around "styles.card", which treats it as a string literal, not the variable. This causes the class to be literally 'styles.card' instead of the hashed class.

3. Final Answer:

   The class attribute should use curly braces, not quotes. -> Option B

4. Quick Check:

   Use curly braces to apply CSS Module classes [OK]

Hint: Use {styles.className} not "styles.className" for CSS Modules [OK]

Common Mistakes:

• Using quotes instead of curly braces for class binding
• Forgetting .module.css in import
• Thinking Astro requires class components

5. How can you apply multiple CSS Module classes styles.primary and styles.rounded to a single element in an Astro component?

hard

A. <div class={styles.primary, styles.rounded}>Content</div>

B. <div class="styles.primary styles.rounded">Content</div>

C. <div class={`${styles.primary} ${styles.rounded}`}>Content</div>

D. <div class={styles.primary + styles.rounded}>Content</div>

Solution

1. Step 1: Understand combining multiple CSS Module classes

   To apply multiple classes, you join their values as strings separated by spaces, typically using template literals or string concatenation.

2. Step 2: Analyze each option

   <div class={`${styles.primary} ${styles.rounded}`}>Content</div> correctly uses template literals to combine classes with a space. <div class="styles.primary styles.rounded">Content</div> treats class names as literal strings, not variables. <div class={styles.primary + styles.rounded}>Content</div> concatenates without space, merging class names incorrectly. <div class={styles.primary, styles.rounded}>Content</div> uses comma which is invalid syntax.

3. Final Answer:

   <div class={`${styles.primary} ${styles.rounded}`}>Content</div> -> Option C

4. Quick Check:

   Join CSS Module classes with space in template literals [OK]

Hint: Use template literals with spaces to combine CSS Module classes [OK]

Common Mistakes:

• Using quotes instead of variables for class names
• Concatenating without spaces
• Using commas inside class attribute