How to Use the Module-Manager to Disable Unused Extension Pages or Modules

The module-manager CLI automatically modifies your Chrome extension's manifest to disable or recover pages, then rebuilds the workspace to keep bundles synchronized.

The module-manager package in jonghakseo/chrome-extension-boilerplate-react-vite provides a purpose-built tool for managing optional extension features without manual manifest editing. By manipulating the chrome-extension/manifest.ts file and regenerating the workspace, this utility ensures that disabled modules do not appear in your production build while remaining recoverable for future use.

Module-Manager Architecture

The tool operates through a six-stage pipeline defined in packages/module-manager/lib/base/run-module-manager.ts. Understanding this flow helps predict how changes affect your extension structure.

Manifest Loading and Parsing

The manager first imports the compiled manifest object and reads the original TypeScript source as a string. This dual approach allows the tool to both validate current configuration and perform precise string replacements when updating the file.

CLI Argument Processing

The processCLIArgs function in packages/module-manager/lib/base/cli-args-processor.ts normalizes flags like -d (delete), -r (recover), --de (delete-exclude), and --re (recover-exclude) into a structured {action, targets} object. When no arguments are provided, the function returns null to trigger interactive prompts.

Feature Modification

Depending on the action, the manager invokes either deleteFeature or recoverFeature from the processing layer. These functions reference the static MODULE_CONFIG map in packages/module-manager/lib/const.ts to determine which manifest keys correspond to each module (e.g., action.default_popup for the popup page or background.service_worker for the background script).

Workspace Synchronization

After rewriting the manifest file, the manager executes pnpm i and pnpm -F chrome-extension lint:fix via execSync. This reinstalls dependencies and lints the modified manifest to ensure generated bundles like content/all.iife.js reflect the updated configuration.

Disabling Modules via CLI

Use the -d or --de flags to remove manifest entries for specific extension pages or scripts.

Disable Specific Pages

Pass target names directly to remove them from the manifest:

pnpm run module-manager -d popup side-panel

This command triggers deleteFeature for each target, which strips the corresponding keys from the manifest object. The source files in src/pages/popup/ remain untouched; only the runtime reference disappears.

Disable Everything Except Specific Modules

Use the delete-exclude flag to keep only the modules you need:

pnpm run module-manager --de content background

The excludeValuesFromBaseArray helper calculates the difference between DEFAULT_CHOICES and your specified exceptions, generating a deletion list containing all other modules. This effectively creates a minimal extension build containing only content scripts and the background worker.

Interactive Selection Mode

Run the command without flags to use the guided interface:

pnpm run module-manager

When processCLIArgs returns null, the script presents the MANAGER_ACTION_PROMPT_CONFIG to choose between delete and recover actions. Selecting delete then displays available modules filtered from DEFAULT_CHOICES based on your current manifest state.

Recovering Disabled Modules

Restore previously removed manifest entries using the recovery flags.

Restore Specific Modules

Use the -r flag to re-inject manifest keys for disabled features:

pnpm run module-manager -r options

The recoverFeature function (symmetrical to deleteFeature in packages/module-manager/lib/processing/recover-feature.ts) retrieves the module's configuration from MODULE_CONFIG and restores the appropriate manifest properties. Source files must exist in the repository for the recovery to succeed; the manager only modifies manifest references.

Key Source Files and Functions

• packages/module-manager/lib/base/run-module-manager.ts: Core orchestration logic that loads the manifest, executes actions, and triggers workspace reinstallation.
• packages/module-manager/lib/base/cli-args-processor.ts: Contains processCLIArgs for parsing flags and excludeValuesFromBaseArray for handling exclude modes.
• packages/module-manager/lib/processing/delete-feature.ts: Implements the deletion workflow through deleteFeature and the internal deleteModule helper.
• packages/module-manager/lib/const.ts: Defines MODULE_CONFIG mapping module names to manifest key fragments and DEFAULT_CHOICES listing all available options.

Summary

• The module-manager CLI controls which extension pages appear in the final build by modifying manifest.ts entries without deleting source code.
• Use -d to disable specific modules or --de to disable everything except specified modules.
• Recovery via -r restores manifest keys based on the static MODULE_CONFIG map.
• The tool automatically reinstalls dependencies and lints code after manifest modifications to ensure bundle consistency.
• All configuration logic resides in packages/module-manager/lib/const.ts, making it straightforward to add custom modules to the management system.

Frequently Asked Questions

What happens to my source files when I disable a module?

The module-manager only removes manifest entries; it does not delete files from src/pages/ or elsewhere. Your source code remains intact but becomes unreachable at runtime because the extension manifest no longer references those entry points.

How does the delete-exclude mode work technically?

When you pass --de content background, the processCLIArgs function identifies this as a delete-exclude operation. It calls excludeValuesFromBaseArray with DEFAULT_CHOICES as the base array and your provided values as exclusions, returning a target list containing every module except content scripts and background. These remaining modules then proceed through the standard deletion pipeline.

Why does the manager run pnpm install after modifying the manifest?

The manifest modification changes which entry points Vite expects to find when bundling. Running pnpm i ensures that workspace dependencies align with the new module configuration, while lint:fix corrects any formatting issues introduced during the string replacement of the manifest file content.

Can I add custom modules to the module-manager system?

Yes. Add your module name to DEFAULT_CHOICES in packages/module-manager/lib/const.ts and define its manifest key mappings in MODULE_CONFIG. The manager will automatically include your custom module in interactive prompts and CLI argument processing without requiring changes to the core logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}