What are the best practices for structuring a large Manifest V3 browser extension?

[RanaKafilAnwar]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

Verification Help & Guidance

Hi everyone,

I'm building a fairly large Manifest V3 browser extension with multiple features, including a popup, options page, background service worker, content scripts, and shared utilities.

As the project grows, I'm finding it harder to keep the codebase organized and maintainable.

I'm curious how experienced developers structure large MV3 projects.

Some questions I have:

• How do you organize shared code between the service worker, popup, and content scripts?
• Do you keep everything in a single repository or split shared logic into separate packages?
• How do you manage messaging between different extension contexts?
• Are there any project structures or patterns that have worked well for you?

I'd appreciate any examples or recommendations from production projects.

Thanks!

[ZaheerAhmedkhan65]

For larger MV3 projects, I usually separate the extension into feature-based folders instead of page-based folders.

For example:

src/
  background/
  content/
  popup/
  options/
  shared/
    utils/
    storage/
    messaging/
    types/

A few practices that have helped:

• Keep shared business logic in a shared folder so it can be reused by all extension contexts.
• Create a small messaging wrapper instead of calling chrome.runtime.sendMessage() everywhere.
• Centralize storage access in one module to avoid duplicated keys and logic.
• Keep the service worker as lightweight as possible and move reusable code into shared modules.
• Use TypeScript path aliases to simplify imports in larger projects.

If the project becomes reusable across multiple extensions, extracting shared code into a separate package or monorepo can also work well.

The exact structure depends on the project's size, but keeping contexts isolated and sharing only common logic has made my MV3 projects much easier to maintain.

Also don't forget to checkout https://github.com/ZaheerAhmedkhan65/mv3-forge