Development & Build

Inspector Lab is a monorepo built with Plasmo and organized around the core extension in apps/extension. This page covers local development, the build process, and contribution guidelines.

Requirements

Node.jsversionrequired

20 or higher

pnpmpackage managerrequired

9 or higher

Quick Start

Clone the repository

git clone https://github.com/luangjokaj/inspector-lab.git
cd inspector-lab

Install dependencies

pnpm install

Start the dev server

pnpm dev

This runs Plasmo in watch mode across all packages and reloads the extension as you edit.

Load the extension locally

Open chrome://extensions in Chrome or a Chromium-based browser
Enable Developer mode (toggle in the top right)
Click Load unpacked
Select apps/extension/build/chrome-mv3-dev

The dev build will reload automatically as you make changes. Use this workflow to test changes before submitting to the Web Store.

Project Structure

apps
- extension
  - src
  - build
  - package.json
docs
package.json
pnpm-workspace.yaml

Available Commands

All commands run from the root of the monorepo:

Command	Purpose
`pnpm dev`	Start development mode with watch and auto-reload across all packages
`pnpm build`	Build the extension for production in `apps/extension/build/chrome-mv3-prod`
`pnpm typecheck`	Run TypeScript type checking across all packages
`pnpm lint`	Lint code with ESLint
`pnpm format`	Format all code with Prettier
`pnpm format:check`	Check code formatting without writing changes

Building for Production

Run type checking

pnpm typecheck

Ensures all TypeScript is valid before building.

Build the extension

pnpm build

Outputs to apps/extension/build/chrome-mv3-prod.

Verify code quality

pnpm lint
pnpm format:check

Ensures lint and formatting standards are met.

Before Opening a Pull Request

All of the following checks must pass:

pnpm typecheck
pnpm lint
pnpm build
pnpm format:check

Keep changes focused — each PR should address a single concern or feature
Match the existing code style — Prettier and ESLint are enforced
Write descriptive commit messages — help reviewers and future maintainers understand your intent
For larger changes, open an issue first to discuss the approach

Extension Architecture

The extension is built with:

Plasmo — Manifest V3 bundler and framework for Chrome extensions
React 19 — UI library for the inspector interface
Cherry UI + styled-components — component library and CSS-in-JS styling in Shadow DOM
TypeScript — for type safety across the codebase

Key modules live in apps/extension/src:

popup/ — Extension popup UI (entry point from the browser toolbar)
content/ — Content scripts injected into web pages
background/ — Service worker (background script) for extension lifecycle and messaging
injected/ — UI panels (Elements, Console, Network, etc.) rendered in an isolated Shadow DOM
manifest.config.ts — Plasmo manifest configuration

For a deeper technical overview, see the Architecture Overview page.

Development Tips

Hot Reload

The dev server watches for changes in source files and automatically reloads the extension. If you modify manifest permissions or background scripts, you may need to manually reload the extension from chrome://extensions.

Console and Debugging

Open the extension popup, then right-click and select Inspect popup to debug the popup UI
For content scripts, open DevTools on any page where Inspector Lab is running and check the Console tab
Service worker logs appear in the extension details under Service worker on chrome://extensions

Testing on iPad

To test on iPad with Orion by Kagi:

Install from the Chrome Web Store directly on the iPad, or create a local build and follow the step-by-step guide in Installation & Setup for Orion-specific sideloading.

Dependencies

Core Dependencies

react^19.2.8

UI framework for the inspector interface

react-dom^19.2.8

React DOM rendering and portal support

plasmo^0.90.5

Manifest V3 extension bundler and development server

cherry-styled-components^0.2.15

Cherry UI component library

styled-components^6.5.0

CSS-in-JS styling solution

Dev Dependencies

typescript^7.0.2

Type checking and compilation

@types/chrome^0.2.5

Chrome API type definitions

prettier^3.9.6

Code formatter

eslintlatest

Code linter

Updating dependencies should be done carefully — test the build and extension behavior after version bumps.

Extension Permissions

The extension requests permissions as defined in apps/extension/package.json:

Permission	Purpose
`activeTab`	Temporary access to the current tab when the popup opens (no standing permission)
`cookies`	Read and write cookies in the Storage panel
`scripting`	Inject content scripts into web pages
`storage`	Persist extension state (theme, open tabs)
`webRequest`	Capture network traffic in the Network panel

Optional host permissions (http://*/*, https://*/*) allow full-page inspection; on restricted sites and chrome:// pages, the inspector falls back gracefully.

The extension launches with a user gesture (clicking the popup icon) and temporary activeTab access — it does not request standing permission to every site. This is a privacy-first design constraint.

Sideloading for Testing

Before releasing to the Web Store, test your changes by sideloading the dev build locally:

Run pnpm dev from the repository root
Open chrome://extensions and enable Developer mode
Click Load unpacked and select apps/extension/build/chrome-mv3-dev
Edit any source file; the extension will rebuild and reload automatically
Test the updated extension on any web page by clicking the Inspector Lab icon

This workflow lets you verify all changes work correctly before submitting to the store. When ready to release, run pnpm build to create the production-optimized build in apps/extension/build/chrome-mv3-prod.

Troubleshooting

Issue	Solution
Changes don't appear after editing	Ensure `pnpm dev` is running. If you modified the manifest, manually reload the extension from `chrome://extensions`
TypeScript errors on build	Run `pnpm typecheck` to see all type errors, then fix them before building
Extension doesn't load unpacked	Check that you're pointing to the correct build folder (`chrome-mv3-dev` or `chrome-mv3-prod`), and that it contains a `manifest.json`
Inspector panel doesn't appear	Open the extension popup on any web page. If it still doesn't work, check the background service worker logs on `chrome://extensions`
Lint or format errors block the build	Run `pnpm lint --fix` and `pnpm format` to auto-correct most issues, then run the checks again

Contributing

We welcome issues and pull requests. Please:

Open an issue for larger changes before investing time in implementation
Keep commits focused and well-described
Run the full test suite (pnpm typecheck, pnpm lint, pnpm build, pnpm format:check) before submitting
Match the existing code style (enforced by Prettier and ESLint)

For more details, see the Contributing section in the main README.

License

Architecture Overview

Learn how Inspector Lab is structured at a high level.

Message Protocol

Understand how the extension communicates internally.