Learn the contracts that matter when you author real extension features. Understand whatDocumentation Index
Fetch the complete documentation index at: https://extension.js.org/llms.txt
Use this file to discover all available pages before exploring further.
manifest.json controls and which entrypoints Extension.js rewrites. Then decide which behaviors you can safely automate and which constraints still apply.
Start by need
| Need | Read this first |
|---|---|
| Understand how a single manifest becomes browser-specific output | manifest.json |
| Decide which permissions your feature actually needs | Permissions and host permissions |
| Send data between popup, content scripts, and background | Messaging |
| Persist settings or cache runtime data | Storage |
| Build page-integrated behavior | Content scripts |
| Build event-driven extension-wide logic | Background scripts / service worker |
| Expose packaged assets to pages safely | Web-accessible resources |
| Keep output paths predictable | Predictable path resolution |
What this section covers
- Authoring contracts that are easy to miss from CLI docs alone.
- Runtime behavior driven by your source files that affects how your extension loads and reloads.
- Browser-extension architecture concerns that still matter after bundling, such as permissions, messaging, storage, and the separation between background, content script, and page contexts.
- Practical guidance whether you work manually or with AI coding agents.
Important mental model
Extension.js helps with compilation, path normalization, manifest rewriting, and development ergonomics. It does not remove the underlying browser-extension boundaries:- Content scripts still run with page-context constraints.
- Background service workers still have lifecycle limitations.
- Web-accessible resources still need explicit exposure.
- Permissions still determine what the extension can do.
- Messaging and storage still need explicit design.
Good reading order for a new feature
- Start with manifest.json to understand the extension surface you are declaring.
- Read the feature-specific page, such as content scripts or background.
- Add supporting pieces: permissions, messaging, storage, and web-accessible resources.
- Validate path assumptions in Predictable path resolution.
- Review dev update behavior before changing entrypoints during active watch mode.
Next steps
- Start with manifest.json.
- Build page integrations with Content scripts.
- Review runtime boundaries in Security checklist.