Chrome Extension Manifest MV3 + React Cursor Rules Template

Overview

The Cursor rules configuration for a Chrome extension using Manifest V3 and React provides a copyable .cursorrules workspace profile to guide Cursor AI in building secure, maintainable MV3 extensions with React frontends. This template focuses on MV3 extensions with a React UI, aligned with Cursor AI rules for safe AI-assisted development.

When to Use These Cursor Rules

• Scaffolding a Chrome extension MV3 project with React-based UI (popup, options, and content UI)
• Need a repeatable .cursorrules configuration to enforce architecture, security, and testing constraints
• Integrating Cursor AI for code reviews, linting, and safe AI-assisted development within MV3 extensions
• Working within MV3 limitations and Chrome APIs via a structured, rule-driven workflow

Copyable .cursorrules Configuration

// Cursor Rules for Chrome Extension MV3 + React
Framework Role & Context
- You are a Cursor AI assistant configured to help build a Chrome extension using Manifest V3 and React.
- You ensure secure, audit-friendly code, with explicit boundaries between background worker, content scripts, and UI.

Code Style and Style Guides
- Follow ESLint recommended + Airbnb style (if applicable) and Prettier formatting.
- Use TypeScript for all new files; enable noImplicitAny and strict mode.
- Enforce consistent import ordering and path aliases defined in tsconfig.json.

Architecture & Directory Rules
- Background: service_worker.ts under src/background
- UI: popup and options under src/popup and src/options
- Content scripts: under src/content
- Manifest: at src/manifest.json and assets under assets/
- Use a single source of truth for API endpoints; avoid inline permissions beyond what is required.

Authentication & Security Rules
- Do not expose API keys in code; use chrome.storage and runtime messages for secure data retrieval
- Validate host permissions strictly; request only required origins at install
- Service worker must be event-driven; no long-running background tasks

Database and ORM patterns
- For extension data storage, use chrome.storage.local with structured data
- If complex data, use IndexedDB with a simple schema; avoid global singletons
- Do not rely on server-side sessions; rely on signed tokens if needed

Testing & Linting Workflows
- Run ESLint + Prettier in pre-commit hooks
- Unit tests with Jest for TS code
- End-to-end tests with Playwright for popup and options pages

Prohibited Actions and Anti-patterns for the AI
- Do not generate insecure permissions or broad host access
- Do not inline secrets; avoid eval; no DOM mutation in background without event
- Do not bypass MV3 service worker constraints or JSON web tokens without proper verification

Recommended Project Structure

chrome-extension/
├─ manifest.json
├─ src/
│  ├─ background/
│  │  └─ service_worker.ts
│  ├─ content/
│  │  └─ content.ts
│  ├─ popup/
│  │  └─ Popup.tsx
│  │  
│  ├─ options/
│  │  └─ Options.tsx
│  ├─ manifest.json (merged)
│  └─ utils/
│
├─ assets/
│  └─ icons/
└─ tests/
   └─ extension.test.ts

Core Engineering Principles

• Secure by default and least privilege for MV3
• Clear separation of concerns between background, content, and UI
• Type-safe code with TypeScript and strict linting
• Deterministic build with CI checks and pre-commit hooks
• Cursor AI rules to guide code quality and safe AI usage

Code Construction Rules

• Use a strict TypeScript configuration and TS config paths
• All UI components must be functional React components with props types
• Background must be a service worker, not a persistent background page
• Do not perform network fetches from content scripts; route through background
• All API calls should go through a typed messenger protocol

Security and Production Rules

• Use MV3 permissions and host permissions minimal
• Bundle code and avoid dynamic evaluation or inline scripts
• Store sensitive data in chrome.storage with appropriate access controls
• Audit third-party libraries and keep dependencies up to date

Testing Checklist

• Unit tests for each React component
• Background and content script interaction tests
• CI workflow runs lint, typecheck, and unit tests
• Manual testing of popup, options, and content interactions

Common Mistakes to Avoid

• Overbroad permissions in manifest.json
• Placing DOM manipulation in background script
• Not handling MV3 service worker lifecycle correctly
• Ignoring TypeScript strict mode and type safety

FAQ

What is a Cursor Rules Template in this context?

A Cursor Rules Template is a copyable .cursorrules workspace profile that codifies stack-specific guidelines for Cursor AI behavior. For this page, it defines a Chrome extension MV3 with React stack, emphasizing security, architecture, and testing practices. It enables developers to paste a ready-to-use configuration into their project root.

Which stack does this template target?

This template targets Chrome Extension Manifest V3 using React for UI, with TypeScript, ESLint, Prettier, and Cursor AI rules to guide development, testing, and secure deployment in a browser extension environment.

How do I use the copyable .cursorrules block?

Copy the code inside the block and save it as .cursorrules in your project root. Cursor AI will read the workspace profile, apply the framework rules, and guide code generation, reviews, and linting for your MV3 extension.

What should I validate before shipping?

Ensure MV3 service worker lifecycle is correct, permissions are minimized, content security policy is strict, and all tests pass in CI. Validate messaging between background, popup, and content scripts, and confirm manifest.json accuracy.

Can I adapt this template to other stacks?

Yes. The structure is designed to be adapted. Replace the stack-specific blocks with your own framework and MV3 setup, preserving security constraints and Cursor AI workflow.