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
    deno
    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