create-extension-react 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiangcheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# Chrome Extension React + Vite 脚手架
+
+一个用于快速开发 Chrome Extension 的脚手架，使用 React + Vite 构建，支持热重载。
+
+## 功能特性
+
+- ⚡️ 纯 Vite + React，无额外插件依赖
+- ⚛️ React 18 支持
+- 🔥 开发模式支持热重载（文件变化自动重建）
+- 📦 TypeScript 支持
+- 🎨 现代化 UI 模板
+- 🧭 支持 New Tab / History / Bookmarks 页面
+- 🛠️ 完全可自定义的构建配置
+
+## 项目结构
+
+```
+.
+├── src/
+│   ├── manifest.json      # Chrome Extension 配置文件
+│   ├── popup.html         # Popup 页面 HTML
+│   ├── popup.tsx          # Popup 页面 React 组件
+│   ├── popup.css          # Popup 页面样式
+│   ├── background.ts      # Service Worker 后台脚本
+│   └── content.ts         # Content Script 内容脚本
+├── scripts/
+│   └── dev.js             # 开发模式脚本（支持热重载）
+├── vite.config.ts         # Vite 配置文件
+├── tsconfig.json          # TypeScript 配置
+└── package.json
+```
+
+## 快速开始
+
+### 使用脚手架创建项目
+
+```bash
+npx create-extension-react my-extension
+```
+
+安装时会提示选择 `newtab` / `history` / `bookmarks` 三选一，并只生成对应模板。
+
+也可以通过参数直接指定类型：
+
+```bash
+npx create-extension-react my-extension --type newtab
+```
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 开发模式（支持热重载）
+
+```bash
+npm run dev
+```
+
+开发模式会：
+
+1. 自动监听文件变化并重新构建
+2. 自动复制 `manifest.json` 到 `dist` 目录
+3. 在 Chrome 中加载扩展后，修改代码会自动重建，刷新扩展即可看到更新
+
+**在 Chrome 中加载扩展：**
+
+1. 打开 Chrome 浏览器
+2. 访问 `chrome://extensions/`
+3. 开启"开发者模式"
+4. 点击"加载已解压的扩展程序"
+5. 选择项目的 `dist` 目录
+6. 开发时，修改代码后点击扩展的刷新按钮即可看到更新
+
+### 构建生产版本
+
+```bash
+npm run build
+```
+
+构建完成后，`dist` 目录就是可以打包的扩展文件。
+
+**注意：**
+
+- `npm run dev` - 开发模式，代码**不压缩**，构建速度快，便于调试
+- `npm run build` - 生产模式，代码**会压缩**，文件体积小，适合发布
+
+## 开发说明
+
+### 热重载
+
+在开发模式下（`npm run dev`），修改代码后：
+
+1. Vite 会自动监听文件变化并重新构建到 `dist` 目录
+2. `manifest.json` 也会自动同步到 `dist` 目录
+3. 在 Chrome 扩展管理页面点击扩展的刷新按钮即可看到更新
+
+### 自定义配置
+
+这是一个纯 Vite + React 的配置，你可以完全自定义：
+
+- **修改构建配置**：编辑 `vite.config.ts`
+- **添加新页面**：在 `src` 目录创建文件，然后在 `vite.config.ts` 的 `rollupOptions.input` 中添加入口点
+- **修改开发脚本**：编辑 `scripts/dev.js`
+
+### 页面覆盖
+
+项目内置了 3 个可用页面：
+
+- `newtab`：新标签页
+- `history`：历史记录页
+- `bookmarks`：书签页
+
+对应入口文件：
+
+- `src/newtab.html` → `src/newtab/index.tsx`
+- `src/history.html` → `src/history/index.tsx`
+- `src/bookmarks.html` → `src/bookmarks/index.tsx`
+
+如果只需要其中某一类页面，请在 `src/manifest.json` 的 `chrome_url_overrides` 中保留对应条目，并同步删除 `vite.config.ts` 的 `rollupOptions.input` 入口。
+
+### 使用 Chrome API
+
+项目已配置 TypeScript 类型支持，可以直接使用 Chrome API：
+
+```typescript
+chrome.tabs.query({ active: true }, (tabs) => {
+  console.log(tabs);
+});
+```
+
+## 许可证
+
+MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "create-extension-react",
+  "version": "0.0.1",
+  "author": "Jiangcheng <plutavian@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/AsukaCC/create-extension-react",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AsukaCC/create-extension-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AsukaCC/create-extension-react/issues"
+  },
+  "type": "module",
+  "description": "Chrome Extension scaffold with React and Vite",
+  "keywords": [
+    "create-extension-react",
+    "chrome",
+    "chrome extension"
+  ],
+  "files": [
+    "scripts/",
+    "src/",
+    "vite-plugin-fix-extension.ts",
+    "vite.config.ts",
+    "tsconfig.json",
+    "tsconfig.node.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "create-extension-react": "scripts/create.js"
+  },
+  "scripts": {
+    "dev": "node scripts/dev.js",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@reduxjs/toolkit": "^2.11.2",
+    "dayjs": "^1.11.19",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-redux": "^9.2.0",
+    "redux-persist": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/chrome": "^0.0.268",
+    "@types/react": "^18.2.66",
+    "@types/react-dom": "^18.2.22",
+    "@vitejs/plugin-react": "^4.2.1",
+    "typescript": "^5.4.3",
+    "vite": "^5.2.0"
+  }
+}

package/scripts/create.js

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+import fs from 'fs/promises';
+import path from 'path';
+import readline from 'readline';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const templateRoot = path.resolve(__dirname, '..');
+
+const TYPE_OPTIONS = ['newtab', 'history', 'bookmarks'];
+const PAGE_META = {
+  newtab: {
+    label: 'newtab',
+    desc: '新标签页',
+    html: 'src/newtab.html',
+    entry: 'src/newtab/index.tsx',
+    permission: null,
+  },
+  history: {
+    label: 'history',
+    desc: '历史记录页',
+    html: 'src/history.html',
+    entry: 'src/history/index.tsx',
+    permission: 'history',
+  },
+  bookmarks: {
+    label: 'bookmarks',
+    desc: '书签页',
+    html: 'src/bookmarks.html',
+    entry: 'src/bookmarks/index.tsx',
+    permission: 'bookmarks',
+  },
+};
+const PRUNE_PATHS = {
+  newtab: ['src/newtab.html', 'src/newtab', 'src/components/NewTabContent'],
+  history: ['src/history.html', 'src/history', 'src/components/HistoryContent'],
+  bookmarks: [
+    'src/bookmarks.html',
+    'src/bookmarks',
+    'src/components/BookmarksContent',
+  ],
+};
+const STYLE_PATTERNS = {
+  newtab: [
+    /\/\* NewTab 特定全局样式 \*\/[\s\S]*?}\r?\n\r?\n?/,
+    /\/\* 亮色主题背景渐变 \*\/[\s\S]*?body\.newtab[\s\S]*?}\r?\n\r?\n?/,
+    /\/\* 暗色主题背景渐变 \*\/[\s\S]*?body\.newtab[\s\S]*?}\r?\n\r?\n?/,
+  ],
+  history: [
+    /\/\* History 特定全局样式 \*\/[\s\S]*?}\r?\n\r?\n?/,
+    /\/\* 亮色主题背景渐变 \*\/[\s\S]*?body\.history[\s\S]*?}\r?\n\r?\n?/,
+    /\/\* 暗色主题背景渐变 \*\/[\s\S]*?body\.history[\s\S]*?}\r?\n\r?\n?/,
+  ],
+  bookmarks: [
+    /\/\* Bookmarks 特定全局样式 \*\/[\s\S]*?}\r?\n\r?\n?/,
+    /\/\* 亮色主题背景渐变 \*\/[\s\S]*?body\.bookmarks[\s\S]*?}\r?\n\r?\n?/,
+    /\/\* 暗色主题背景渐变 \*\/[\s\S]*?body\.bookmarks[\s\S]*?}\r?\n\r?\n?/,
+  ],
+};
+
+const getOptionValue = (args, keys) => {
+  const index = args.findIndex((arg) => keys.includes(arg));
+  if (index === -1) return null;
+  return args[index + 1] ?? null;
+};
+
+const promptType = async () => {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const question = (text) =>
+    new Promise((resolve) => {
+      rl.question(text, resolve);
+    });
+
+  if (!process.stdin.isTTY) {
+    rl.close();
+    return 'newtab';
+  }
+
+  readline.emitKeypressEvents(process.stdin, rl);
+  process.stdin.setRawMode(true);
+
+  let selectedIndex = Math.max(TYPE_OPTIONS.indexOf('newtab'), 0);
+  const render = () => {
+    process.stdout.write('\x1b[2J');
+    process.stdout.write('\x1b[0f');
+    console.log('请选择要创建的扩展类型（↑↓ 选择，Enter 确认）：');
+    TYPE_OPTIONS.forEach((option, index) => {
+      const prefix = index === selectedIndex ? '➤' : ' ';
+      console.log(`${prefix} ${option}`);
+    });
+  };
+
+  render();
+
+  const selectedType = await new Promise((resolve) => {
+    const cleanup = () => {
+      process.stdin.removeListener('keypress', onKeypress);
+      process.stdin.removeListener('close', onClose);
+      process.stdin.removeListener('end', onClose);
+      process.stdin.removeListener('error', onClose);
+    };
+
+    const onClose = () => {
+      cleanup();
+      resolve(null);
+    };
+
+    const onKeypress = (_, key) => {
+      if (!key) return;
+      if (key.name === 'up') {
+        selectedIndex =
+          (selectedIndex - 1 + TYPE_OPTIONS.length) % TYPE_OPTIONS.length;
+        render();
+      } else if (key.name === 'down') {
+        selectedIndex = (selectedIndex + 1) % TYPE_OPTIONS.length;
+        render();
+      } else if (key.name === 'return') {
+        cleanup();
+        resolve(TYPE_OPTIONS[selectedIndex]);
+      } else if (key.name === 'c' && key.ctrl) {
+        cleanup();
+        resolve(null);
+      }
+    };
+
+    process.stdin.on('keypress', onKeypress);
+    process.stdin.once('close', onClose);
+    process.stdin.once('end', onClose);
+    process.stdin.once('error', onClose);
+  });
+
+  process.stdin.setRawMode(false);
+  rl.close();
+
+  return selectedType;
+};
+
+const ensureEmptyDir = async (targetDir) => {
+  try {
+    const entries = await fs.readdir(targetDir);
+    return entries.length === 0;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      await fs.mkdir(targetDir, { recursive: true });
+      return true;
+    }
+    throw error;
+  }
+};
+
+const copyDir = async (
+  source,
+  destination,
+  ignore = new Set(),
+  ignorePaths = new Set()
+) => {
+  await fs.mkdir(destination, { recursive: true });
+  const entries = await fs.readdir(source, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (ignore.has(entry.name)) {
+      continue;
+    }
+
+    const sourcePath = path.join(source, entry.name);
+    const destPath = path.join(destination, entry.name);
+    if (ignorePaths.has(sourcePath)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      await copyDir(sourcePath, destPath, ignore, ignorePaths);
+    } else if (entry.isFile()) {
+      await fs.copyFile(sourcePath, destPath);
+    }
+  }
+};
+
+const removePath = async (targetPath) => {
+  try {
+    await fs.rm(targetPath, { recursive: true, force: true });
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+};
+
+const updateManifest = async (targetDir, type) => {
+  const manifestPath = path.join(targetDir, 'src', 'manifest.json');
+  const data = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+
+  data.chrome_url_overrides = {
+    [type]: `${type}.html`,
+  };
+
+  const permissions = new Set(data.permissions || []);
+  permissions.delete('history');
+  permissions.delete('bookmarks');
+  const permission = PAGE_META[type]?.permission;
+  if (permission) {
+    permissions.add(permission);
+  }
+  data.permissions = Array.from(permissions);
+
+  await fs.writeFile(manifestPath, JSON.stringify(data, null, 2));
+};
+
+const updateViteConfig = async (targetDir, type) => {
+  const vitePath = path.join(targetDir, 'vite.config.ts');
+  const content = await fs.readFile(vitePath, 'utf-8');
+  const lines = content.split(/\r?\n/);
+
+  const filtered = lines.filter((line) => {
+    if (line.includes('newtab: resolve(')) return type === 'newtab';
+    if (line.includes('history: resolve(')) return type === 'history';
+    if (line.includes('bookmarks: resolve(')) return type === 'bookmarks';
+    return true;
+  });
+
+  await fs.writeFile(vitePath, filtered.join('\n'));
+};
+
+const removePatterns = (content, patterns) =>
+  patterns.reduce((acc, pattern) => acc.replace(pattern, ''), content);
+
+const updateStyles = async (targetDir, type) => {
+  const stylePath = path.join(targetDir, 'src', 'style.css');
+  let content = await fs.readFile(stylePath, 'utf-8');
+
+  const targets = TYPE_OPTIONS.filter((option) => option !== type);
+  targets.forEach((option) => {
+    content = removePatterns(content, STYLE_PATTERNS[option] || []);
+  });
+
+  await fs.writeFile(stylePath, content.trimEnd() + '\n');
+};
+
+const updateReadme = async (targetDir, type) => {
+  const readmePath = path.join(targetDir, 'README.md');
+  let content = await fs.readFile(readmePath, 'utf-8');
+
+  const meta = PAGE_META[type];
+  const section = [
+    '### 页面覆盖',
+    '',
+    '项目内置 1 个页面：',
+    '',
+    `- \`${meta.label}\`：${meta.desc}`,
+    '',
+    '对应入口文件：',
+    '',
+    `- \`${meta.html}\` → \`${meta.entry}\``,
+    '',
+  ].join('\n');
+
+  const sectionRegex = /### 页面覆盖[\s\S]*?(?=\n### |\n## |$)/;
+  if (sectionRegex.test(content)) {
+    content = content.replace(sectionRegex, section.trim());
+  } else {
+    content = content.trimEnd() + '\n\n' + section.trim() + '\n';
+  }
+
+  await fs.writeFile(readmePath, content.trimEnd() + '\n');
+};
+
+const updatePackageJson = async (targetDir, projectName) => {
+  const pkgPath = path.join(targetDir, 'package.json');
+  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf-8'));
+  pkg.name = projectName;
+  if (pkg.bin) {
+    delete pkg.bin;
+  }
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2));
+};
+
+const updatePackageLock = async (targetDir, projectName) => {
+  const lockPath = path.join(targetDir, 'package-lock.json');
+  try {
+    const lock = JSON.parse(await fs.readFile(lockPath, 'utf-8'));
+    lock.name = projectName;
+    if (lock.packages && lock.packages['']) {
+      lock.packages[''].name = projectName;
+    }
+    await fs.writeFile(lockPath, JSON.stringify(lock, null, 2));
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+};
+
+const pruneFiles = async (targetDir, type) => {
+  const removals = TYPE_OPTIONS.filter((option) => option !== type)
+    .flatMap((option) => PRUNE_PATHS[option] || [])
+    .map((item) => removePath(path.join(targetDir, item)));
+  await Promise.all(removals);
+};
+
+const createProgress = (total) => {
+  let current = 0;
+  const isTty = Boolean(process.stdout.isTTY);
+  const barWidth = 24;
+
+  const render = (label) => {
+    if (!isTty) {
+      return;
+    }
+    const percent = Math.min(100, Math.round((current / total) * 100));
+    const filled = Math.round((barWidth * percent) / 100);
+    const bar = `${'#'.repeat(filled)}${'.'.repeat(barWidth - filled)}`;
+    const text = `[${bar}] ${percent}% ${label}`;
+    process.stdout.write(`\r${text}`);
+  };
+
+  const step = (label) => {
+    current += 1;
+    render(label);
+    if (current >= total && isTty) {
+      process.stdout.write('\r\x1b[2K');
+    }
+  };
+
+  return step;
+};
+
+const main = async () => {
+  const args = process.argv.slice(2);
+  const targetArg = args.find((arg) => !arg.startsWith('-')) || 'extension-app';
+  const targetDir = path.resolve(process.cwd(), targetArg);
+  const projectName = path.basename(targetDir);
+  const typeArg = getOptionValue(args, ['--type', '-t']);
+  let selectedType = typeArg && TYPE_OPTIONS.includes(typeArg) ? typeArg : null;
+
+  if (!selectedType) {
+    selectedType = await promptType();
+  }
+
+  if (!selectedType || !TYPE_OPTIONS.includes(selectedType)) {
+    console.log('未选择有效类型，已退出。');
+    process.exit(1);
+  }
+
+  const empty = await ensureEmptyDir(targetDir);
+  if (!empty) {
+    console.log(`目录不为空，请选择空目录：${targetDir}`);
+    process.exit(1);
+  }
+
+  const ignore = new Set([
+    'node_modules',
+    'dist',
+    '.git',
+    '.DS_Store',
+    'scripts',
+  ]);
+
+  const ignorePaths = new Set();
+  const relativeTarget = path.relative(templateRoot, targetDir);
+  if (
+    relativeTarget === '' ||
+    (!relativeTarget.startsWith('..') && !path.isAbsolute(relativeTarget))
+  ) {
+    ignorePaths.add(targetDir);
+  }
+
+  const step = createProgress(9);
+
+  step('复制模板');
+  await copyDir(templateRoot, targetDir, ignore, ignorePaths);
+
+  step('写入脚本');
+  await fs.mkdir(path.join(targetDir, 'scripts'), { recursive: true });
+  await fs.copyFile(
+    path.join(templateRoot, 'scripts', 'dev.js'),
+    path.join(targetDir, 'scripts', 'dev.js')
+  );
+
+  step('裁剪文件');
+  await pruneFiles(targetDir, selectedType);
+
+  step('更新 manifest');
+  await updateManifest(targetDir, selectedType);
+
+  step('更新 Vite 配置');
+  await updateViteConfig(targetDir, selectedType);
+
+  step('更新样式');
+  await updateStyles(targetDir, selectedType);
+
+  step('更新 README');
+  await updateReadme(targetDir, selectedType);
+
+  step('更新 package.json');
+  await updatePackageJson(targetDir, projectName);
+
+  step('更新 package-lock.json');
+  await updatePackageLock(targetDir, projectName);
+
+  console.log('');
+  console.log(`✅ 已创建项目：${targetDir}`);
+  console.log(`✅ 选择页面类型：${selectedType}`);
+  console.log('');
+  console.log('下一步：');
+  console.log(`cd ${path.relative(process.cwd(), targetDir)}`);
+  console.log('npm install');
+  console.log('npm run dev');
+};
+
+main().catch((error) => {
+  console.error('创建失败：', error);
+  process.exit(1);
+});

package/scripts/dev.js

@@ -0,0 +1,26 @@
+import { spawn } from 'child_process';
+
+console.log('🚀 Development mode started');
+console.log('📦 Watching for file changes...');
+console.log('💡 Load the extension from the "dist" folder in Chrome');
+console.log('');
+
+// 启动 Vite watch 模式（插件会自动处理修复）
+const viteProcess = spawn(
+  'vite',
+  ['build', '--watch', '--mode', 'development'],
+  {
+    stdio: 'inherit',
+    shell: true,
+    env: {
+      ...process.env,
+      NODE_ENV: 'development',
+    },
+  }
+);
+
+// 处理退出
+process.on('SIGINT', () => {
+  viteProcess.kill();
+  process.exit();
+});

package/src/background.ts

@@ -0,0 +1,9 @@
+// Service Worker for Chrome Extension
+chrome.runtime.onInstalled.addListener(() => {
+  console.log('Extension installed');
+});
+
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  console.log('Message received:', message);
+  return true;
+});

package/src/bookmarks/index.module.css

@@ -0,0 +1,17 @@
+.container {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  color: var(--text-primary);
+  transition: color 0.3s ease;
+}
+
+.themeButtonWrapper {
+  position: absolute;
+  top: 20px;
+  right: 20px;
+  z-index: 1000;
+  filter: drop-shadow(0 2px 4px var(--shadow-md));
+  transition: filter 0.3s ease;
+}