Skip to main content
Extension.js supports plain CSS plus Sass and Less preprocessors out of the box. 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-sass template screenshot Content script with Sass styling injected into web pages. 
npx extension@latest create my-extension --template=content-sass
Repository: extension-js/examples/content-sass

​
content-custom-font

content-custom-font template screenshot Content script demonstrating custom font loading through CSS. 
npx extension@latest create my-extension --template=content-custom-font
Repository: extension-js/examples/content-custom-font

​
CSS capabilities

CapabilityWhat it gives you
Multi-context stylingUse one authoring model for pages and content scripts
Sass/Less compilationCompile Sass/Less when dependencies are present
Context-aware outputEmit page CSS and content-script CSS to correct targets
dev update flowApply 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 fieldFile 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'

​
Output behavior by context

ContextOutput behavior
HTML/page contextsExtension.js bundles CSS with page entries (feature.css)
Content scriptsExtension.js emits CSS as content_scripts/[name].[contenthash:8].css assets
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.
  • 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