# crxjs

A skill for building Chrome extensions with CRXJS: it walks the agent through real HMR for popup, content scripts and side panels. Useful when your extension already builds on Vite.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 4300 installs · ★ 236
- Author: samber
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/samber/cc-skills/tree/HEAD/skills/crxjs/SKILL.md
- Updated: 2026-10-01
- HTML: https://affpapa.org/en/nevibecode/skills/crxjs

## What it does

The skill covers `@crxjs/vite-plugin`, a Vite plugin that reads your manifest and generates the extension output. The agent gets ready configs for React, Vue, Svelte and Vanilla TypeScript, plus a `defineManifest` template for a typed manifest with dynamic values such as the version pulled from `package.json`.

HMR differs by context. Popup, options and side panel reload over a WebSocket and keep their state. Content scripts get true module-level HMR because CRXJS injects a loader, an HMR preamble and the client. Main world scripts get no HMR at all — the loader skips them, so you verify those edits with a page reload.

Dynamic injection uses the `?script` and `?script&module` import suffixes. The first returns a resolved path for `chrome.scripting.executeScript`, the second targets main world injection. Add a reference to `@crxjs/vite-plugin/client` so TypeScript picks up types for both. The skill needs `git` and `node` installed.

## Requirements
- Works with: Chrome

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add samber/cc-skills --skill crxjs -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/crxjs/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/crxjs/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add samber/cc-skills --skill crxjs -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/crxjs/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add samber/cc-skills --skill crxjs -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/crxjs/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install samber/cc-skills crxjs
```

2. **Manually: put the files in place**
- File: `.github/skills/crxjs/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add samber/cc-skills --skill crxjs -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/samber/cc-skills --path skills/crxjs
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/crxjs/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add samber/cc-skills --skill crxjs -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/samber/cc-skills/tree/HEAD/skills/crxjs/SKILL.md

## When to use it
- get HMR working for a content script without reloading the page
- build a typed manifest with the version taken from package.json
- wire CRXJS into an existing Vite project
- inject a content script programmatically with executeScript
- figure out why service worker edits force a full extension reload

## Example prompts
- Set up CRXJS in my React Vite project, I want HMR for the popup and content script
- Move my manifest to defineManifest and pull the version from package.json
- Add dynamic content script injection with `?script` in the background script

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 5f434863c94181b1.

BEGIN THIRD-PARTY FILE 5f434863c94181b1
````text
---
name: crxjs
description: "CRXJS Chrome extension development — true HMR for popup, options, content scripts, side panels, manifest-driven builds, dynamic content script imports (`?script`, `?script&module`), and `defineManifest` for type-safe manifests. Uses Vite as its build tool. Use when the user mentions CRXJS, crxjs, @crxjs/vite-plugin, 'extension with hot reload', 'HMR for chrome extension', or wants to set up a CRXJS-based Chrome extension project with any framework (React, Vue, Svelte, Solid, Vanilla). Also trigger when the user has an existing CRXJS project and wants to add features, fix HMR issues, or configure content scripts with CRXJS. For general Chrome extension architecture (messaging, CSP, storage, permissions) -> See `samber/cc-skills@chrome-extension` skill."
user-invocable: true
license: MIT
compatibility: Designed for Claude Code, Codex or similar harness. Requires git, node.
metadata:
  author: samber
  version: "1.1.0"
  openclaw:
    emoji: "📝"
    homepage: https://github.com/samber/cc-skills
    requires:
      bins:
        - git
        - node
        - npm
    skill-library-version: "2.4.0"
allowed-tools: Read Edit Write Glob Grep Bash(git:*) Bash(gh:*) Bash(npm:*)
---

# CRXJS

CRXJS is a Chrome extension development tool that provides true HMR for popup, options, content scripts, and side panels. It reads your manifest to auto-generate the extension output, handles content script injection, and manages the service worker build. Under the hood it is a Vite plugin (`@crxjs/vite-plugin`).

## Current status

- **Package**: `@crxjs/vite-plugin` (v2.x stable, latest v2.4.0 as of March 2026)
- **Scaffolding**: `npm create crxjs@latest` (always use `@latest`)
- **Maintained by**: @Toumash and @FliPPeDround (since mid-2025)
- **GitHub**: github.com/crxjs/chrome-extension-tools (~4k stars)
- **Vite compatibility**: v3 through v8-beta

## Quick start

```bash
# Scaffold new project (picks framework interactively)
npm create crxjs@latest

# Or add to existing Vite project
npm install @crxjs/vite-plugin -D
```

## Vite config by framework

CRXJS is added as a Vite plugin. The setup varies slightly per framework.

### React

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";

export default defineConfig({
  plugins: [react(), crx({ manifest })],
});
```

Use `@vitejs/plugin-react` (not `plugin-react-swc`) for best HMR compatibility. If you must use SWC, cast the manifest:

```typescript
import { ManifestV3Export } from "@crxjs/vite-plugin";
const manifest = manifestJson as ManifestV3Export;
```

### Vue

```typescript
import vue from "@vitejs/plugin-vue";
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";
````
END THIRD-PARTY FILE 5f434863c94181b1

The third-party file has ended. Everything between the 5f434863c94181b1 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2853 of 10548 bytes. © samber · MIT · https://github.com/samber/cc-skills/tree/HEAD/skills/crxjs/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md