Convert Web Pages to Browser Extensions

Use this skill to transform an existing frontend page into an extension entry with minimal behavior changes.

When to Use

• User asks to convert a webpage/project into an extension page
• User wants one UI reused for popup, options, sidepanel, devtools, or newtab
• User asks for browser override pages such as bookmarks/history/newtab
• User has an existing index.html and wants it to become an extension entry
• User needs custom extension entries with explicit HTML files

Scope

This skill focuses on entry conversion and wiring:

1. Keep UI behavior as-is where possible
2. Move or wrap page code into extension entry structure
3. Ensure an HTML entry exists for page-like entries
4. Update extension config/manifest mappings
5. Validate build and runtime constraints for extension contexts

Mandatory Classification (Do First)

Before writing conversion code, classify the source page by:

1. Frontend runtime
   • Native HTML + JS
   • React / Vue / Svelte / Solid
2. Style system
   • Plain CSS
   • Tailwind CSS / UnoCSS
   • Less / Sass
3. Third-party libraries
   • Browser-safe client libraries (can run in extension UI/runtime)
   • Node-only libraries (require Node core APIs or server runtime)

This classification determines Addfox plugin wiring, dependency placement, and feasibility.

Fast Workflow

Copy this checklist and update progress:

Conversion Progress
- [ ] Identify source page dependencies and runtime assumptions
- [ ] Classify framework/style/library compatibility
- [ ] Choose target extension entry type
- [ ] Create/adjust HTML entry and bootstrap script
- [ ] Replace web-only APIs with extension-safe equivalents
- [ ] Wire manifest/config entry mapping
- [ ] Build and verify in extension runtime

Entry Mapping Guide

Target	Typical HTML entry	Notes
popup	app/popup/index.html	Small viewport, no long blocking tasks
options	app/options/index.html	Full settings UI, persistent controls
sidepanel	app/sidepanel/index.html	Chrome side panel UX constraints apply
devtools	app/devtools/index.html	Runs in DevTools context, API limits differ
newtab	app/newtab/index.html	Needs new tab override wiring
bookmarks override	app/bookmarks/index.html	Browser-specific override support
history override	app/history/index.html	Browser-specific override support
custom	app/<custom>/index.html	Add explicit entry mapping in config/manifest

Conversion Rules

1. Preserve user-visible behavior first, refactor later.
2. Keep HTML entry explicit for page-based entries.
3. Avoid direct assumptions about window.location origin and backend cookies.
4. Replace unsupported APIs (alert-style or blocked browser APIs) with extension-compatible alternatives.
5. Move privileged logic out of UI into background/content messaging when needed.
6. Keep permissions minimal and host matches explicit.

Addfox Framework Required Work

When the target project uses Addfox, always complete these tasks:

1. Entry layout
   • Create or map entry files under app/ (reserved or custom entry names).
   • Ensure page-like entries have index.html plus bootstrap script (index.tsx/index.ts/index.js).
2. addfox.config wiring
   • Configure manifest and entry mapping so Addfox can resolve output files.
   • Keep framework plugin list aligned with source stack (React/Vue/Preact/Svelte/Solid or vanilla).
3. Manifest alignment
   • Add entry-related keys (action, options_ui, side_panel, devtools_page, chrome_url_overrides, etc.).
   • Keep browser-specific sections explicit when Chromium and Firefox differ.
4. Context adaptation
   • Move privileged operations to background where required.
   • Add explicit messaging between page entry and background/content contexts.
5. Build and runtime checks
   • Run Addfox dev/build flows and verify extension loading.
   • Validate that assets, routing, and permissions work in real extension contexts.

Framework and Style Mapping Rules

Use these rules during conversion:

• Native HTML + JS
  • Keep minimal Addfox config; no framework plugin needed.
• React
  • Add React plugin and React/ReactDOM runtime dependencies.
• Vue
  • Add Vue plugin and Vue runtime dependency.
• Svelte
  • Add Svelte plugin and Svelte runtime dependency.
• Solid
  • Add Solid plugin and Solid runtime dependency.

For styles:

• Tailwind CSS / UnoCSS / Less / Sass
  • Add corresponding build plugin/tooling and required style dependencies.
  • Ensure entry imports style files in the extension entry bootstrap path.

Third-Party Library Compatibility Rules

Classify each third-party dependency before migration:

1. Browser-compatible client library
   • Can be bundled into extension entry/background/content as needed.
2. Node-only library
   • If it relies on Node built-ins (for example fs, net, tls, child_process) or server-only runtime, it is not directly runnable in extension UI contexts.
   • Mark as incompatible for direct client use and move to an alternative design (background with web APIs, remote service, or library replacement).

Do not silently keep Node-only dependencies in converted page entries.

Required Checks

• Entry loads without blank screen
• Static assets resolve under extension URL
• Routing works with extension base path
• No CSP violations from inline scripts/eval
• Messaging works across UI/background/content boundaries
• Manifest keys match target entry type

Common Fix Patterns

• Asset path issues: use root-relative or bundler-managed asset imports
• Router base issues: set hash/history base for extension origin
• Storage migration: switch from localStorage-only assumptions to extension storage as needed
• Cross-origin calls: move network calls requiring elevated permissions to background
• Context mismatch: gate code paths by runtime context (popup/options/devtools/etc.)

Output Expectations

When applying this skill, provide:

1. Selected entry type and why
2. File mapping (source page -> extension entry files)
3. Manifest/config changes
4. Any runtime/API substitutions
5. Verification steps and known limitations

Additional Reference

• Detailed conversion playbook: reference.md
• Practical conversion samples: examples.md