🚀 Browser Extension Template with Plasmo + tRPC + React Query

A modern, type-safe browser extension starter template that helps you build extensions faster. This template combines the power of Plasmo, tRPC, and React Query to provide a robust foundation for your browser extension projects.

English | 简体中文

✨ Why Use This Template?

• Type Safety: Built-in end-to-end type safety with tRPC
• Modern Development: Hot reload, automatic reloading, and modern development experience
• Battle-tested Stack: Carefully selected technology stack for optimal development
• Ready to Use: Pre-configured with essential tools and best practices
• Beautiful UI: Integrated with shadcn/ui for stunning user interfaces

🔧 Tech Stack

• Core:
  • Plasmo - Modern framework for building browser extensions
  • React - UI library for building user interfaces
  • TailwindCSS - Utility-first CSS framework
  • shadcn/ui - High-quality, customizable React components
• Type Safety & Data Management:
  • tRPC - End-to-end typesafe APIs
  • TanStack Query - Powerful data fetching and async state management
  • trpc-browser - Type-safe messaging interface for browser extensions

📁 Template Structure

src/
├── background/   # Background service workers
├── components/   # Reusable UI components
├── contents/     # Content scripts
├── hooks/       # Custom React hooks
├── lib/         # Utility functions and configurations
├── tabs/        # Extension tabs
├── popup.tsx    # Extension popup
├── options.tsx  # Extension options page
└── style.css    # Global styles

🚀 Getting Started

Prerequisites

• Node.js 16.14.x or later
• macOS, Windows, or Linux
• pnpm (Strongly Recommended)

Using This Template

1. Clone this repository or use it as a template
2. Install dependencies:

pnpm install

3. Start development:

pnpm dev

4. Load the extension:
   • Chrome: Open chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked" and select the build/chrome-mv3-dev directory

Development Commands

# Start development server with hot reload
pnpm dev

# Build for production
pnpm build

# Package the extension
pnpm package

Customizing the Template

Adding UI Components

Add new shadcn/ui components using the CLI:

pnpm dlx shadcn@latest add <component-name>
# Example: pnpm dlx shadcn@latest add button

Modifying Extension Permissions

Edit the manifest section in package.json to modify permissions:

"manifest": {
  "host_permissions": ["https://*/*"],
  "permissions": []
}

🏗️ Building for Production

1. Build the extension:

pnpm build

2. Find your production-ready extension in the build directory
3. Package for store submission:

pnpm package

🌐 Browser Compatibility

Officially supported browsers:

• ✅ Chrome/Chromium (Manifest V3) - Default target
• ✅ Firefox (Manifest V2)
• ✅ Firefox (Manifest V3) - Experimental
• ✅ Edge (Manifest V3)
• ✅ Brave (Manifest V3)
• ✅ Opera (Manifest V3)
• ⚠️ Safari (Manifest V3) - Requires safari-web-extension-converter

All Chromium-based browsers are supported through their respective MV3 targets:

pnpm build --target=edge-mv3
pnpm build --target=brave-mv3
pnpm build --target=opera-mv3

For Safari development, build with --target=safari-mv3 and use the Safari Web Extension converter tool.

🤝 Contributing

This template is open to improvements. Feel free to:

• Submit bug reports
• Propose new features
• Create pull requests

📄 License

MIT License - Feel free to use this template for your projects!