Docs
Blog
Docs
Blog

Sass / Sass modules

Use Sass to scale extension styling with variables, nesting, and modules while keeping a single build workflow.

Extension.js supports .scss and .sass, plus module variants (.module.scss, .module.sass) through the Rspack-based style pipeline.

When Sass is a good fit

  • Your design system already relies on Sass variables and mixins.
  • You need modular styles for component-driven extension UIs.
  • You want parity with existing Sass workflows in web applications.

Template examples

new-sass

new-sass template screenshot

Start a new-tab extension with Sass support already configured.

npm
pnpm
yarn
npx extension@latest create my-extension --template=new-sass

Repository: extension-js/examples/new-sass

Usage with an existing extension

You can integrate Sass with an existing Extension.js project by installing the necessary dependencies and configuring your files.

Installation

Install the required dependencies:

npm
yarn
pnpm
bun
npm install -D sass sass-loader

Example usage in an HTML file

In extension pages (popup/options/new tab), import Sass from your entry script:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>New Extension</title>
    <script src="./main.ts"></script>
  </head>
  <body>
    <h1 class="title">Hello, Extension.</h1>
  </body>
</html>
import "./styles/globals.scss";

console.log("Sass loaded");

Sass modules

Sass Modules allow you to scope styles locally, just like CSS Modules. You can use .module.scss or .module.sass to activate Sass Modules, which prevent naming conflicts in your stylesheets.

content-sass-modules

content-sass-modules template screenshot

Use Sass Modules in content scripts when you need scoped styling for injected UI.

npm
pnpm
yarn
npx extension@latest create my-extension --template=content-sass-modules

Repository: extension-js/examples/content-sass-modules

Using Sass modules in an existing extension

To enable Sass Modules, rename your Sass file to include .module.scss or .module.sass. This will automatically scope the styles to your component.

- button.scss
+ button.module.scss

Example usage

After renaming your Sass file, import it into your script:

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

const element = document.createElement("h1");
element.className = styles.primaryColor;
element.innerText = "Hello, Extension!";
document.body.appendChild(element);

In the Sass file:

/* styles/button.module.scss */

$primary-color: #64ff00;

:export {
  primaryColor: $primary-color;
}

React/Preact example usage

Import the Sass module into your React or Preact component, and use the scoped class names:

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

export default function MyComponent() {
  return <h1 className={styles.primaryColor}>Hello, Extension!</h1>;
}

Vue example usage

In Vue SFCs, prefer module styles with lang="scss":

<template>
  <h1 :class="$style.primaryColor">Hello, Extension!</h1>
</template>

<style lang="scss" module>
@import "./styles/button.module.scss";
</style>

Svelte example usage

In Svelte, import Sass module mappings and apply classes:

<script>
  import styles from "./styles/button.module.scss";
</script>

<h1 class={styles.primaryColor}>Hello, Extension!</h1>

Behavior notes

  • In extension pages, .module.scss and .module.sass export class maps for JS/TS imports.
  • In content scripts, Sass is emitted as CSS assets for injection rather than module export maps.
  • If Sass tooling is missing, Extension.js may install optional dependencies and ask for a restart.

Next steps

Video walkthrough

Video demo soon: sass styling workflow

ON THIS PAGE