crxjs
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.
- Installs
- 4.4K
- Last 24h
- +98
- Trending rank
- #2018
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/samber/cc-skills --skill crxjs- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads crxjs automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
# 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
// 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:
import { ManifestV3Export } from "@crxjs/vite-plugin";
const manifest = manifestJson as ManifestV3Export;
Vue
import vue from "@vitejs/plugin-vue";
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";
export default defineConfig({
plugins: [vue(), crx({ manifest })],
});
Svelte
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";
export default defineConfig({
plugins: [svelte(), crx({ manifest })],
});
Vanilla TypeScript
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";
export default defineConfig({
plugins: [crx({ manifest })],
});
defineManifest — type-safe dynamic manifest
Instead of a static JSON file, use CRXJS's defineManifest for dynamic values and full TypeScript autocompletion:
// manifest.ts
import { defineManifest } from "@crxjs/vite-plugin";
import pkg from "./package.json";
export default defineManifest((config) => ({
manifest_version: 3,
name: config.command === "serve" ? `[DEV] ${pkg.name}` : pkg.name,
version: pkg.version,
description: pkg.description,
permissions: ["storage", "activeTab", "scripting"],
action: {
default_popup: "src/popup/index.html",
default_icon: {
"16": "public/icons/icon16.png",
"48": "public/icons/icon48.png",
},
},
background: {
service_worker: "src/background/index.ts",
type: "module",
},
content_scripts: [
{
matches: ["https://*/*"],
js: ["src/content/index.ts"],
css: ["src/content/styles.css"],
},
],
options_page: "src/options/index.html",
side_panel: { default_path: "src/sidepanel/index.html" },
icons: {
"16": "public/icons/icon16.png",
"48": "public/icons/icon48.png",
"128": "public/icons/icon128.png",
},
}));
Import in vite.config.ts:
import manifest from "./manifest";
// ... crx({ manifest })
Type declarations
Add to a src/vite-env.d.ts or src/crxjs.d.ts:
/// <reference types="@crxjs/vite-plugin/client" />
This enables types for ?script and ?script&module imports.
HMR behavior by context
| Context | HMR | How it works |
|---|---|---|
| Popup | Full HMR | WebSocket-based, state preserved |
| Options page | Full HMR | Same as popup |
| Side panel | Full HMR | Same as popup |
| Content script (manifest) | True HMR | CRXJS injects loader + HMR client |
| Content script (dynamic) | True HMR | Via ?script import |
| Service worker | Auto-reload | Changes trigger full extension reload |
| Main world scripts | No HMR | Skipped by CRXJS loader |
Content script HMR works because CRXJS generates a loader script that imports an HMR preamble, the HMR client, and your actual script — enabling real module-level HMR without full page reload. This is CRXJS's main differentiator.
Dynamic content script imports
For content scripts injected programmatically (not in manifest), CRXJS provides special import suffixes:
// background.ts — ?script gives you a resolved path for executeScript
import contentScript from "./content?script";
chrome.action.onClicked.addListener(async (tab) => {
await chrome.scripting.executeScript({
target: { tabId: tab.id! },
files: [contentScript],
});
});
For main world injection (no HMR):
import mainWorldScript from "./inject?script&module";
await chrome.scripting.executeScript({
target: { tabId },
world: "MAIN",
files: [mainWorldScript],
});
CRXJS plugin options
crx({
manifest,
browser: "chrome", // 'chrome' | 'firefox'
contentScripts: {
injectCss: true, // auto-inject CSS for content scripts
hmrTimeout: 5000, // HMR connection timeout (ms)
},
});
Development workflow
# Start dev server (outputs to dist/ with HMR)
npm run dev
# 1. Open chrome://extensions
# 2. Enable "Developer mode"
# 3. Click "Load unpacked"
# 4. Select the dist/ directory
# 5. Edit code — popup/content scripts update instantly via HMR
# 6. Service worker changes trigger automatic extension reload
After loading once, subsequent npm run dev sessions reconnect automatically. No need to re-load the extension unless manifest.json changes.
Production build
npm run build # outputs to dist/
The dist/ directory is ready to zip and upload to Chrome Web Store:
cd dist && zip -r ../extension.zip .
Disable Vite's module preload to avoid CWS rejection of inline scripts:
build: {
modulePreload: false;
}
Known issues and workarounds
Tailwind CSS HMR in content scripts
New Tailwind classes may not trigger CSS updates in content scripts. Workaround: restart dev server after adding new utility classes. Improved in v2.4.0 but not fully resolved. Ensure injectCss: true in config.
WebSocket connection errors (ws://localhost:undefined/)
Cause: port mismatch between dev server and HMR config. Fix: explicitly set both to the same value:
server: {
port: 5173,
strictPort: true,
hmr: { port: 5173 },
}
"Manifest version 2 is deprecated" warning
If you see this, your manifest is being interpreted as MV2. Fix: ensure "manifest_version": 3 is set.
Content scripts not injecting on file:// URLs
Chrome requires the user to enable "Allow access to file URLs" in the extension settings at chrome://extensions. CRXJS cannot change this.
HMR stops working after Chrome update
CRXJS's HMR relies on injecting a content script that connects to the dev server's WebSocket. Chrome security updates occasionally break this. Fix: update to the latest CRXJS version, which tracks Chrome changes.
CRXJS vs alternatives
| Feature | CRXJS | WXT | Plasmo |
|---|---|---|---|
| Content script HMR | True HMR | File-based reload | Partial |
| Framework support | Any Vite framework | Any | React-focused |
| Abstraction level | Thin (Vite plugin) | Full framework | Full framework |
| Messaging helpers | None (use chrome.* directly) | Built-in | Built-in |
| Storage wrappers | None | Built-in | Built-in |
| Cross-browser | Chrome + Firefox | Chrome + Firefox + Safari | Chrome + Firefox |
| File-based routing | No | Yes | Yes |
| Learning curve | Low (know Vite, know CRXJS) | Medium | Medium |
Choose CRXJS when: you want minimal abstraction over raw Chrome APIs and value content script HMR above all. CRXJS stays out of the way — no magic routing, no wrapper APIs, just your code with HMR.
Choose WXT when: you want conventions, built-in utilities, and cross-browser support.
Choose Plasmo when: you're React-focused and want the highest-level abstraction.
Project structure (recommended)
my-extension/
├── src/
│ ├── background/
│ │ └── index.ts
│ ├── content/
│ │ ├── index.ts
│ │ └── styles.css
│ ├── popup/
│ │ ├── index.html <- CRXJS resolves HTML entry points
│ │ ├── App.tsx
│ │ └── main.tsx
│ ├── options/
│ │ ├── index.html
│ │ └── main.tsx
│ ├── sidepanel/
│ │ ├── index.html
│ │ └── main.tsx
│ └── shared/
│ ├── messages.ts
│ └── storage.ts
├── public/
│ └── icons/
├── manifest.ts <- or manifest.json
├── vite.config.ts
├── tsconfig.json
└── package.json
CRXJS resolves HTML files referenced in the manifest automatically. Your popup.html can use standard <script type="module" src="./main.tsx"> and it works.
If you encounter a bug or unexpected behavior in CRXJS, open an issue at github.com/crxjs/chrome-extension-tools/issues.
FAQ
What does the crxjs skill do?
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.
How do I install crxjs?
Run npx skills add https://github.com/samber/cc-skills --skill crxjs in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/crxjs/ (personal) or .claude/skills/crxjs/ (project).
Which AI agents can use crxjs?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is crxjs safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains crxjs?
It is published by samber in samber/cc-skills. It has 4,391 recorded installs.
More from samber/cc-skills
copywriting-hooks
samber/cc-skills
Writes opening hooks and post titles for long-form articles in EN or FR — blog posts, Substack/Medium/dev.to, LinkedIn long-form, newsletters, essays. Trigger whenever the user asks for a hook, opening, lede, intro, first sentence/paragraph, opener, accroche, attaque, phrase d'accroche, or première phrase — including punching up a flat intro or draft opening — or for a post title, titre d'article, or headline. Do NOT trigger for social posts (LinkedIn feed, Twitter/X, TikTok, Bluesky), READMEs, taglines, email subjects, ad copy, landing-page headlines, press releases, SEO meta, or body rewrites. Do NOT use for end-of-article CTAs — use samber/cc-skills@copywriting-cta instead.
linkedin-ghostwriting
samber/cc-skills
B2B LinkedIn ghostwriting — hooks, post structures, and copywriting frameworks for conversion-focused posts. Use when the user wants to write LinkedIn content, create ghostwritten posts, ghostwrite for a founder or executive, or develop a B2B social strategy. Apply when the user shares a story, result, or insight and wants it turned into a post. Do NOT use for newsletter or Substack issues — use samber/cc-skills@substack-ghostwriting instead.
copywriting-tone-of-voice-creator
samber/cc-skills
Builds a brand tone of voice guide (TONE.md) — voice attributes with do's/don'ts, NN/g positioning, tone modulation matrix, lexicon, channel rules — for downstream content skills to consume. Also ports an existing TONE.md to a new channel (blog → LinkedIn, web → Twitter/X, in-product UI). Covers B2B SaaS, B2C/D2C, NGO, public sector, consulting, industrial, product-led, personal, and volunteering brands. Apply when the user wants to define or refresh a brand voice, port it to a new channel, or set up a content factory. Not for writing individual posts, articles, emails, or UI strings — use the dedicated writing skills. Not for SOUL.md, PROSE.md (samber/cc-skills@copywriting-prose-creator), or DESIGN.md.
frontend-design-deslop
samber/cc-skills
Designs distinctive, non-generic UI — typography, OKLCH color, design tokens (DESIGN.md), layout, components, motion, dark mode, accessibility — for landing pages, SaaS apps, dashboards, ecommerce, decks, docs, portfolios, avoiding the AI-slop / Claude-esque default look. Use whenever building or styling any web frontend, app, dashboard, landing page, deck, or artifact, or when the user says "make it not look like AI", "de-slopify", "deslop", "less generic", "give it character", "design a UI for X", "design an app", "update DESIGN.md", or complains the output looks like every other AI site. Trigger even on a bare "build a UI for X" with no aesthetic named. Not for writing marketing copy.
humaniseur-fr
samber/cc-skills
Remove AI-writing patterns from French text and inject voice and personality. Use when editing, reviewing, or rewriting French content that reads like ChatGPT or Claude output. Detects and fixes 38 patterns: AI vocabulary (crucial, essentiel, notamment, dans le paysage), anglicisms from English-first models (faire du sens, adresser un problème), formulaic openings (À l'ère de, Dans un monde où), participle clauses in -ant, em dash overuse, decorative emojis, mixed guillemets and apostrophes, uniform sentence length. Trigger on humaniser, déslopifier, nettoyer le texte IA, enlever le slop, make it sound human. Do NOT use for English text — use samber/cc-skills@humanizer-en-asd-ste100 instead.
deep-research
samber/cc-skills
Deep research on any topic — broad parallel web searches, multi-source validation, confidence tracking, and a cited Markdown report. Use whenever the deliverable is a thorough sourced report rather than a quick answer: 'research ', 'deep dive on X', 'analyze the landscape', 'competitive analysis', 'compare these options', 'who are the players in Z', 'literature review', 'background on Y', 'what papers exist on X', 'product teardown', 'regulatory overview', 'funding landscape', 'what trends are emerging in X', 'patent landscape', 'community health', or any request requiring scanning many sources and producing a cited written analysis. Covers 11 research types: market (TAM/SAM, segments, pricing, trends), domain (industry structure, ecosystem, regulatory overview), technical (architecture, tooling, benchmarks, technology evaluation), competitive (competitor teardown, positioning, win/loss), product (feature analysis, reviews, teardowns, roadmap signals), academic (literature surve
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.