CSS, Sass, and Less in browser extensions

Extension.js supports plain CSS plus Sass and Less preprocessors with no setup. It routes styles differently for page contexts (popup, options, side panel) and content-script contexts. Page styles ship as linked assets. Extension.js injects content-script styles into the web page’s document so they apply to the active tab.

Template examples

`content-sass`

Content script with Sass styling injected into web pages.

npx extension@latest create my-extension --template=content-sass

pnpx extension@latest create my-extension --template=content-sass

yarn dlx extension@latest create my-extension --template=content-sass

bunx extension@latest create my-extension --template=content-sass

deno run -A npm:extension@latest create my-extension --template=content-sass

Repository: extension-js/examples/content-sass

`content-custom-font`

Content script demonstrating custom font loading through CSS.

npx extension@latest create my-extension --template=content-custom-font

pnpx extension@latest create my-extension --template=content-custom-font

yarn dlx extension@latest create my-extension --template=content-custom-font

bunx extension@latest create my-extension --template=content-custom-font

deno run -A npm:extension@latest create my-extension --template=content-custom-font

Repository: extension-js/examples/content-custom-font

CSS capabilities

Capability	What it gives you
Multi-context styling	Use one authoring model for pages and content scripts
Sass/Less compilation	Compile Sass/Less when dependencies are present
Context-aware output	Emit page CSS and content-script CSS to correct targets
Dev update flow	Apply style updates through hot module replacement (HMR)/remount when supported

Where to reference CSS

manifest.json (content_scripts[].css)
HTML files (<link rel="stylesheet" href="...">)
Script imports (import "./styles.css", including Sass/Less when enabled)

CSS support

Manifest CSS entries:

Manifest field	File type expected
`content_scripts.css`	`.css`, `.scss`, `.sass`, `.less`

Example: CSS in `manifest.json`

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "css": ["./styles/content.css"],
      "js": ["./scripts/content.ts"]
    }
  ]
}

Example: CSS in extension page scripts

import "./styles/popup.scss";

Web fonts in a content script

A content script that renders into a shadow root cannot load a webfont through CSS alone. Two platform rules get in the way, and both are silent. A @font-face inside a shadow root never applies. Font faces resolve against the document’s font set, not the shadow tree, so Chrome ignores the rule and falls back without an error. Measured on the content-custom-font template before it was fixed: document.fonts was empty, zero font requests fired, and text set in "Momo Signature", cursive measured the same width as bare cursive. A root-absolute url() in an injected stylesheet resolves against the host page. url(/fonts/Momo.woff2) inside a stylesheet injected into example.com requests https://example.com/fonts/Momo.woff2, not the extension’s copy. Register the face on the page’s own font set instead, from a URL that names the extension, and remove it when the content script tears down:

export default function initial() {
  const rootDiv = document.createElement("div");
  document.body.appendChild(rootDiv);
  const shadowRoot = rootDiv.attachShadow({ mode: "open" });

  const customFace = new FontFace(
    "Momo Signature",
    `url("${chrome.runtime.getURL("fonts/MomoSignature-Regular.woff2")}")`,
  );

  customFace
    .load()
    .then((face) => document.fonts.add(face))
    .catch(() => {
      // Ignore
    });

  return () => {
    document.fonts.delete(customFace);
    rootDiv.remove();
  };
}

The font file must be reachable from the page, so declare it in web_accessible_resources:

{
  "web_accessible_resources": [
    {
      "resources": ["fonts/*.woff2"],
      "matches": ["<all_urls>"]
    }
  ]
}

Once the face is on document.fonts, the shadow tree can use it by name in an ordinary font-family rule. The working version lives in content-custom-font.

Output behavior by context

Context	Output behavior
HTML/page contexts	Extension.js bundles CSS with page entries (`feature.css`)
Content scripts	Extension.js emits CSS as `content_scripts/[name].css` assets and rewrites the manifest to match

Extension.js splits contexts automatically based on which entrypoint imports the CSS.

Development behavior

Content script CSS imports participate in the content-script HMR/remount flow.
Extension.js adds a dev helper script to CSS-only content script entries so it can propagate updates.
Page CSS follows normal page HMR pipeline behavior.
Structural manifest/content-script changes can still require full extension reload or restart.

Modules and preprocessors

CSS Modules work best in extension page contexts.
Extension.js enables Sass/Less support when you install the related dependencies.
If a project references .scss/.less files but the preprocessor is not installed, the build warns and copies the source through uncompiled instead of failing. Browsers treat that uncompiled source as broken CSS and render those surfaces unstyled, so install the preprocessor to get real compilation.
Extension.js runs PostCSS automatically when it detects a PostCSS configuration in your project, or when you configure it explicitly.

Best practices

Keep content-script styles intentionally scoped to reduce host-page collisions.
Prefer component-local module styles for extension page UIs.
Keep preprocessor and PostCSS configurations explicit to avoid unintended changes to your build setup over time.
Validate CSS paths referenced by manifest fields in continuous integration (CI).

Next steps

Understand update outcomes in dev update behavior.
Learn more about CSS Modules.
Learn more about PostCSS integration.

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

CSS, Sass, and Less in browser extensions

Template examples

`content-sass`

`content-custom-font`

CSS capabilities

Where to reference CSS

CSS support

Example: CSS in `manifest.json`

Example: CSS in extension page scripts

Web fonts in a content script

Output behavior by context

Development behavior

Modules and preprocessors

Best practices

Next steps

Video walkthrough

​Template examples

​content-sass

​content-custom-font

​CSS capabilities

​Where to reference CSS

​CSS support

​Example: CSS in manifest.json

​Example: CSS in extension page scripts

​Web fonts in a content script

​Output behavior by context

​Development behavior

​Modules and preprocessors

​Best practices

​Next steps

​Video walkthrough

Template examples

`content-sass`

`content-custom-font`

CSS capabilities

Where to reference CSS

CSS support

Example: CSS in `manifest.json`

Example: CSS in extension page scripts

Web fonts in a content script

Output behavior by context

Development behavior

Modules and preprocessors

Best practices

Next steps

Video walkthrough