Skip to main content

Documentation Index

Fetch the complete documentation index at: https://extension.js.org/llms.txt

Use this file to discover all available pages before exploring further.

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