> ## 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 implementation guide and runtime model

> Build browser extension features with the Extension.js runtime model. Covers manifest contracts, entrypoints, special folders, and browser constraints.

Learn the contracts that matter when you author real extension features. Understand what `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](/docs/implementation-guide/manifest-json)                                       |
| Decide which permissions your feature actually needs             | [Permissions and host permissions](/docs/implementation-guide/permissions-and-host-permissions) |
| Send data between popup, content scripts, and background         | [Messaging](/docs/implementation-guide/messaging)                                               |
| Persist settings or cache runtime data                           | [Storage](/docs/implementation-guide/storage)                                                   |
| Build page-integrated behavior                                   | [Content scripts](/docs/implementation-guide/content-scripts)                                   |
| Build event-driven extension-wide logic                          | [Background scripts / service worker](/docs/implementation-guide/background)                    |
| Expose packaged assets to pages safely                           | [Web-accessible resources](/docs/implementation-guide/web-accessible-resources)                 |
| Keep output paths predictable                                    | [Predictable path resolution](/docs/features/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

1. Start with [manifest.json](/docs/implementation-guide/manifest-json) to understand the extension surface you are declaring.
2. Read the feature-specific page, such as [content scripts](/docs/implementation-guide/content-scripts) or [background](/docs/implementation-guide/background).
3. Add supporting pieces: [permissions](/docs/implementation-guide/permissions-and-host-permissions), [messaging](/docs/implementation-guide/messaging), [storage](/docs/implementation-guide/storage), and [web-accessible resources](/docs/implementation-guide/web-accessible-resources).
4. Validate path assumptions in [Predictable path resolution](/docs/features/path-resolution).
5. Review [dev update behavior](/docs/workflows/dev-update-behavior) before changing entrypoints during active watch mode.

## Next steps

* Start with [manifest.json](/docs/implementation-guide/manifest-json).
* Build page integrations with [Content scripts](/docs/implementation-guide/content-scripts).
* Review runtime boundaries in [Security checklist](/docs/workflows/security-checklist).