nsbp-cli 0.2.27 → 0.2.30

package/templates/basic/docs/HUSKY_ESLINT_SETUP.md

@@ -0,0 +1,293 @@
+# Husky 和 ESLint 配置总结
+
+> **Husky 9.x 升级说明**：Husky 9.x 简化了安装方式，无需手动运行 `husky install`。Hooks 在 `pnpm install` 时自动创建。
+
+## ✅ 已完成的配置
+
+### 1. 创建的配置文件
+
+#### ESLint 配置
+- **`.eslintrc.js`** - ESLint 主配置文件
+  - TypeScript 支持（@typescript-eslint/parser）
+  - React 支持（eslint-plugin-react）
+  - React Hooks 支持（eslint-plugin-react-hooks）
+  - Prettier 集成（eslint-config-prettier）
+
+- **`.eslintignore`** - ESLint 忽略规则
+  - 忽略构建产物（build, dist, public）
+  - 忽略缓存（.temp_cache）
+  - 忽略 Webpack 配置文件
+
+#### Prettier 配置
+- **`.prettierrc.js`** - Prettier 格式化配置
+  - 2 空格缩进
+  - 单引号
+  - 无分号
+  - 100 字符换行
+  - Unix 换行符
+  - import 组织（prettier-plugin-organize-imports）
+
+#### Husky Git Hooks
+- **`.husky/pre-commit`** - 提交前钩子
+  - 运行 `pnpm run lint-staged`
+  - 自动修复和格式化暂存文件
+
+- **`.husky/pre-push`** - 推送前钩子
+  - 运行完整 lint 检查
+  - 防止推送有问题的代码
+
+- **`.husky/commit-msg`** - 提交信息验证
+  - 验证 Conventional Commits 格式
+  - 支持的类型：feat, fix, docs, style, refactor, test, chore, build, ci, perf, revert
+
+- **`.husky/README.md`** - Git hooks 使用说明
+
+#### VSCode 配置
+- **`.vscode/settings.json`** - 编辑器设置
+  - 保存时自动格式化
+  - 保存时自动修复 ESLint 问题
+  - 配置 Prettier 作为默认格式化器
+  - TypeScript 和 React 文件支持
+
+- **`.vscode/extensions.json`** - 推荐扩展
+  - ESLint
+  - Prettier
+  - TypeScript Importer
+  - Error Lens
+
+- **`.vscode/.gitignore`** - Git 忽略规则
+  - 允许提交 settings.json 和扩展配置
+  - 忽略 workspace 配置
+
+### 2. 更新的文件
+
+#### package.json
+- **添加的依赖**:
+  ```json
+  {
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-react": "^7.37.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^15.0.0",
+    "prettier-plugin-organize-imports": "^4.0.0"
+  }
+  ```
+
+- **添加的脚本**:
+  ```json
+  {
+    "lint": "eslint src --ext .ts,.tsx,.js,.jsx",
+    "lint:fix": "eslint src --ext .ts,.tsx,.js,.jsx --fix",
+    "prepare": "husky"
+  }
+  ```
+
+- **添加的 lint-staged 配置**:
+  ```json
+  {
+    "*.{ts,tsx,js,jsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{css,less,scss}": [
+      "prettier --write"
+    ]
+  }
+  ```
+
+#### .gitignore
+- 添加了 `.husky/_` 忽略规则（Husky 内部文件）
+
+#### README.md
+- 添加了快速开始部分
+- 添加了开发工具说明
+- 添加了文档链接
+
+### 3. 创建的文档
+
+- **`docs/ESLINT_AND_PRETTIER.md`** - ESLint 和 Prettier 详细配置说明
+- **`docs/SETUP_GIT_HOOKS.md`** - Git hooks 配置和使用说明
+- **`docs/DEVELOPMENT_GUIDE.md`** - 完整开发指南
+- **`docs/HUSKY_ESLINT_SETUP.md`** - 本文档
+
+### 4. 创建的辅助脚本
+
+- **`scripts/setup-husky.js`** - Husky 初始化脚本（备用）
+
+## 📦 依赖版本
+
+| 包名 | 版本 | 用途 |
+|------|------|------|
+| eslint | ^9.0.0 | 代码质量检查 |
+| eslint-config-prettier | ^9.0.0 | Prettier 集成 |
+| eslint-plugin-react | ^7.37.0 | React 规则 |
+| eslint-plugin-react-hooks | ^5.0.0 | React Hooks 规则 |
+| @typescript-eslint/eslint-plugin | ^8.0.0 | TypeScript 规则 |
+| @typescript-eslint/parser | ^8.0.0 | TypeScript 解析 |
+| prettier | ^3.3.0 | 代码格式化 |
+| prettier-plugin-organize-imports | ^4.0.0 | import 排序 |
+| husky | ^9.0.0 | Git hooks |
+| lint-staged | ^15.0.0 | 暂存文件处理 |
+
+## 🔧 ESLint 规则配置
+
+### 主要规则
+
+```javascript
+{
+  'prettier/prettier': 'error',                    // Prettier 冲突报错
+  'react/react-in-jsx-scope': 'off',           // 不需要 React 导入
+  'react/prop-types': 'off',                    // 使用 TypeScript
+  '@typescript-eslint/explicit-module-boundary-types': 'off',
+  '@typescript-eslint/no-explicit-any': 'warn',  // 允许 any
+  '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+  'react-hooks/rules-of-hooks': 'error',           // Hooks 规则
+  'react-hooks/exhaustive-deps': 'warn',       // 依赖检查
+  'no-console': ['warn', { allow: ['warn', 'error'] }] // 允许 console
+}
+```
+
+## 🎨 Prettier 配置
+
+```javascript
+{
+  semi: false,                 // 不使用分号
+  singleQuote: true,             // 使用单引号
+  tabWidth: 2,                  // 2 空格缩进
+  trailingComma: 'es5',         // ES5 尾部逗号
+  printWidth: 100,              // 100 字符换行
+  arrowParens: 'always',        // 箭头函数加括号
+  endOfLine: 'lf',              // Unix 换行符
+  plugins: ['prettier-plugin-organize-imports'],
+  importOrder: ['^react', '^@/(.*)$', '^[./]'],
+  importOrderSeparation: true,
+  importOrderSortSpecifiers: true
+}
+```
+
+## 🔄 Git Hooks 工作流程
+
+### 提交前（pre-commit）
+
+1. `lint-staged` 检测暂存文件
+2. 对 TypeScript/JS 文件运行 `eslint --fix`
+3. 对所有文件运行 `prettier --write`
+4. 重新暂存修复后的文件
+5. 如果有错误，阻止提交
+
+### 推送前（pre-push）
+
+1. 运行完整 `pnpm run lint`
+2. 如果有错误，阻止推送
+
+### 提交信息验证（commit-msg）
+
+1. 检查提交信息格式：`<type>(<scope>): <subject>`
+2. 支持的类型：feat, fix, docs, style, refactor, test, chore, build, ci, perf, revert
+3. 如果格式不正确，阻止提交并显示帮助信息
+
+## 📝 提交信息示例
+
+```bash
+# 功能
+git commit -m "feat(core): add SSR data preloading support"
+
+# Bug 修复
+git commit -m "fix(client): resolve hydration mismatch error"
+
+# 文档
+git commit -m "docs(readme): update installation instructions"
+
+# 样式
+git commit -m "style: format code with prettier"
+
+# 重构
+git commit -m "refactor(components): simplify layout component"
+
+# 测试
+git commit -m "test(add): add unit tests for utils"
+
+# 构建
+git commit -m "build(webpack): optimize production bundle"
+
+# CI
+git commit -m "ci(github): update workflow configuration"
+```
+
+## 🚀 使用方法
+
+### 初始化（首次使用）
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 初始化 Git hooks（会自动运行 prepare 脚本）
+pnpm run prepare
+
+# 3. 验证 hooks 安装
+ls .husky
+# 应该看到: pre-commit, pre-push, commit-msg
+```
+
+### 日常开发
+
+```bash
+# 开发
+pnpm run dev
+
+# 修改代码...
+
+# 提交（hooks 自动运行）
+git add .
+git commit -m "feat: add new feature"
+# pre-commit 自动运行: eslint --fix + prettier --write
+
+# 如果有错误
+pnpm run lint:fix
+git add .
+git commit --amend
+```
+
+### 跳过 hooks（不推荐）
+
+```bash
+# 跳过 pre-commit
+git commit --no-verify -m "message"
+
+# 跳过 pre-push
+git push --no-verify
+```
+
+⚠️ **警告**: 仅在紧急情况下使用！
+
+## 📚 相关文档
+
+- [README.md](../README.md) - 项目总览
+- [ESLINT_AND_PRETTIER.md](./ESLINT_AND_PRETTIER.md) - ESLint 和 Prettier 详细配置
+- [SETUP_GIT_HOOKS.md](./SETUP_GIT_HOOKS.md) - Git hooks 使用说明
+- [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md) - 完整开发指南
+
+## ✨ 特性
+
+- ✅ TypeScript + React 完整支持
+- ✅ 自动代码格式化（保存时自动运行）
+- ✅ 提交前自动 lint 和格式化
+- ✅ 提交信息格式验证
+- ✅ VSCode 集成（自动格式化 + 修复）
+- ✅ import 自动排序
+- ✅ 支持 Conventional Commits
+- ✅ React Hooks 规则检查
+
+## 🎯 下一步建议
+
+- [ ] 添加单元测试框架（Jest 或 Vitest）
+- [ ] 配置 CI/CD 流程
+- [ ] 添加代码覆盖率报告
+- [ ] 配置自动化部署
+- [ ] 添加 Commitlint 更严格的提交规范
+- [ ] 配置 Release Please 自动化版本发布

package/templates/basic/docs/SETUP_GIT_HOOKS.md

@@ -0,0 +1,106 @@
+# Git Hooks Setup
+
+This project uses **Husky** for managing Git hooks.
+
+## Quick Setup
+
+```bash
+# Install dependencies
+pnpm install
+
+# Initialize Git hooks (optional, runs automatically on prepare)
+pnpm run prepare
+```
+
+## How It Works
+
+Husky automatically creates Git hooks in the `.husky` directory:
+
+- **pre-commit**: Runs linting on staged files
+- **pre-push**: Runs full lint check before pushing
+- **commit-msg**: Validates commit message format
+
+## Commit Message Format
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```
+<type>(<scope>): <subject>
+```
+
+### Type Options
+
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `test`: Adding missing tests or correcting existing tests
+- `chore`: Maintenance tasks
+- `build`: Changes that affect the build system
+- `ci`: Changes to CI configuration files
+- `perf`: Performance improvements
+- `revert`: Reverts a previous commit
+
+### Examples
+
+```bash
+# Feature
+git commit -m "feat(core): add SSR data preloading support"
+
+# Bug fix
+git commit -m "fix(client): resolve hydration mismatch error"
+
+# Documentation
+git commit -m "docs(readme): update installation instructions"
+
+# Style (formatting)
+git commit -m "style: format code with prettier"
+```
+
+## Available Scripts
+
+```bash
+# Lint all files
+pnpm run lint
+
+# Lint and fix issues
+pnpm run lint:fix
+
+# Format code
+pnpm run format
+
+# Reinstall Git hooks
+pnpm run prepare
+```
+
+## Troubleshooting
+
+### Hooks not working?
+
+1. Make sure hooks are executable:
+   ```bash
+   chmod +x .husky/*
+   ```
+
+2. Reinstall hooks:
+   ```bash
+   pnpm run prepare
+   ```
+
+3. Check `.git/config` for hooks path:
+   ```bash
+   git config core.hooksPath
+   ```
+   Should output: `.husky`
+
+### Skip hooks (not recommended)
+
+If you need to bypass hooks temporarily:
+
+```bash
+git commit --no-verify
+git push --no-verify
+```
+
+⚠️ **Warning**: Use `--no-verify` only in emergencies!

package/templates/basic/eslint.config.js

@@ -0,0 +1,98 @@
+const js = require('@eslint/js')
+const typescriptEslint = require('@typescript-eslint/eslint-plugin')
+const typescriptParser = require('@typescript-eslint/parser')
+const reactPlugin = require('eslint-plugin-react')
+const reactHooksPlugin = require('eslint-plugin-react-hooks')
+const prettierPlugin = require('eslint-plugin-prettier')
+const prettierConfig = require('eslint-config-prettier')
+
+module.exports = [
+  js.configs.recommended,
+  {
+    ignores: [
+      'node_modules/**',
+      'build/**',
+      'dist/**',
+      '.temp_cache/**',
+      'public/js/**',
+      'public/css/**',
+      'public/*.js',
+      'public/*.js.map',
+      'public/*.css.map',
+      '*.bundle.js',
+      'loadable-stats.json',
+      'coverage/**',
+      '.nyc_output/**',
+      '*.config.js',
+      'webpack.base.js',
+      'webpack.client.js',
+      'webpack.server.js',
+      '.prettierrc.js',
+      'cli/**',
+      'scripts/**'
+    ]
+  },
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    languageOptions: {
+      parser: typescriptParser,
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true
+        },
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        project: './tsconfig.json',
+        tsconfigRootDir: __dirname
+      },
+      globals: {
+        window: 'readonly',
+        document: 'readonly',
+        console: 'readonly',
+        process: 'readonly',
+        module: 'readonly',
+        require: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        global: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        fetch: 'readonly',
+        setTimeout: 'readonly'
+      }
+    },
+    plugins: {
+      '@typescript-eslint': typescriptEslint,
+      react: reactPlugin,
+      'react-hooks': reactHooksPlugin,
+      prettier: prettierPlugin
+    },
+    settings: {
+      react: {
+        version: 'detect'
+      }
+    },
+    rules: {
+      ...typescriptEslint.configs.recommended.rules,
+      ...reactPlugin.configs.recommended.rules,
+      ...reactHooksPlugin.configs.recommended.rules,
+      ...prettierConfig.rules,
+      'prettier/prettier': 'error',
+      'react/react-in-jsx-scope': 'off',
+      'react/prop-types': 'off',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_' }
+      ],
+      '@typescript-eslint/no-unused-expressions': 'off',
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
+      'no-console': ['warn', { allow: ['warn', 'error'] }],
+      'no-undef': 'off'
+    }
+  }
+]

package/templates/basic/gitignore

@@ -43,6 +43,9 @@ coverage
 *.swo
 *~
 
+# Husky (git hooks)
+.husky/_
+
 # OS
 .DS_Store
 .DS_Store?

package/templates/basic/package.json

@@ -14,9 +14,12 @@
     "build:server": "webpack --config config/webpack.server.js --mode production",
     "build:client": "webpack --config config/webpack.client.js --mode production",
     "start": "node ./scripts/start.js",
-    "clean": "rimraf build && rimraf public/js && rimraf public/css && rimraf public/client.* && rimraf public/*.js && rimraf public/*.js.map && rimraf public/*.txt && rimraf public/*.json && rimraf .temp_cache",
+    "clean": "rimraf build && rimraf public/js && rimraf public/css && rimraf public/client.* && rimraf public/*.js && rimraf public/*.js.map && rimraf public/*.txt && rimraf public/*.json && rimraf config/.temp_cache",
     "format": "prettier --write **/*.{js,css,less,scss,ts,tsx}",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "lint": "eslint src --ext .ts,.tsx,.js,.jsx",
+    "lint:fix": "eslint src --ext .ts,.tsx,.js,.jsx --fix",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepare": "husky"
   },
   "keywords": [
     "react",
@@ -29,7 +32,7 @@
   ],
   "author": "Erishen Sun",
   "license": "ISC",
-  "packageManager": "pnpm@10.27.0",
+  "packageManager": "pnpm@10.28.0",
   "dependencies": {
     "@loadable/component": "^5.15.0",
     "@loadable/server": "^5.15.0",
@@ -60,6 +63,7 @@
     "@babel/plugin-transform-optional-chaining": "^7.25.0",
     "@babel/preset-env": "^7.25.0",
     "@babel/preset-react": "^7.24.0",
+    "@eslint/js": "^9.39.2",
     "@loadable/babel-plugin": "^5.13.2",
     "@loadable/webpack-plugin": "^5.15.0",
     "@types/express": "^5.0.6",
@@ -73,6 +77,8 @@
     "@types/react-router-dom": "^5.3.3",
     "@types/serialize-javascript": "^5.0.3",
     "@types/styled-components": "^5.1.36",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
     "babel-loader": "^10.0.0",
     "babel-plugin-styled-components": "^2.1.4",
     "browser-sync": "^3.0.4",
@@ -81,15 +87,24 @@
     "cross-spawn": "^7.0.6",
     "css-loader": "^7.1.0",
     "css-minimizer-webpack-plugin": "^7.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-react": "^7.37.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "globals": "^17.0.0",
     "html-webpack-plugin": "^5.6.0",
+    "husky": "^9.0.0",
     "less": "^4.2.0",
     "less-loader": "^12.0.0",
+    "lint-staged": "^15.0.0",
     "mini-css-extract-plugin": "^2.9.0",
     "nodemon": "^3.1.0",
     "npm-run-all": "^4.1.5",
     "postcss-loader": "^8.1.0",
     "postcss-preset-env": "^10.6.1",
     "prettier": "^3.3.0",
+    "prettier-plugin-organize-imports": "^4.0.0",
     "rimraf": "^6.1.2",
     "sass-loader": "^16.0.0",
     "style-loader": "^4.0.0",
@@ -101,5 +116,14 @@
     "webpack-cli": "^6.0.1",
     "webpack-dev-server": "^5.1.0",
     "webpack-node-externals": "^3.0.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{css,less,scss}": [
+      "prettier --write"
+    ]
   }
 }

package/templates/basic/scripts/setup-husky.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+/**
+ * Setup Husky Git Hooks
+ *
+ * Note: Husky 9.x doesn't need manual installation.
+ * Hooks are automatically created during pnpm install.
+ */
+
+console.log('🔧 Husky Git Hooks Setup\n')
+
+console.log('ℹ️  Husky 9.x Information:')
+console.log('   Hooks are automatically created during pnpm install')
+console.log('   No manual setup required!\n')
+
+console.log('📝 Configured Git Hooks:')
+console.log('   • pre-commit  - Lint staged files before commit')
+console.log('   • pre-push   - Run full lint check before push')
+console.log('   • commit-msg - Validate commit message format\n')
+
+console.log('💡 Commit message format: type(scope): description')
+console.log('   Types: feat, fix, docs, style, refactor, test, chore, etc.\n')
+
+console.log('✅ Setup complete! Git hooks are ready to use.\n')

package/templates/basic/src/Routers.tsx

@@ -1,21 +1,20 @@
 import React from 'react'
 import { loadData as homeLoadData } from '@services/home'
-import { loadData as photoLoadData } from '@services/photo'
-import loadable from "@loadable/component"
+import loadable from '@loadable/component'
 
 const Loading = () => {
   return <div>Loading...</div>
 }
 
-const Home = loadable(() => import("@containers/Home"), {
+const Home = loadable(() => import('@containers/Home'), {
   fallback: <Loading />
 })
 
-const Login = loadable(() => import("@containers/Login"), {
+const Login = loadable(() => import('@containers/Login'), {
   fallback: <Loading />
 })
 
-const Photo = loadable(() => import("@containers/Photo"), {
+const Photo = loadable(() => import('@containers/Photo'), {
   fallback: <Loading />
 })
 

package/templates/basic/src/client/index.tsx

@@ -23,7 +23,11 @@ const App = () => {
         <BrowserRouter>
           <Routes>
             {routers.map((router) => (
-              <Route key={router.key} path={router.path} element={router.element} />
+              <Route
+                key={router.key}
+                path={router.path}
+                element={router.element}
+              />
             ))}
           </Routes>
         </BrowserRouter>

package/templates/basic/src/component/Header.tsx

@@ -1,6 +1,12 @@
 import React from 'react'
 import { Link, useLocation } from 'react-router-dom'
-import { Container, LogoWrapper as Logo, Nav, NavLink, Brand } from '@styled/component/header'
+import {
+  Container,
+  LogoWrapper as Logo,
+  Nav,
+  NavLink,
+  Brand
+} from '@styled/component/header'
 
 const Header = () => {
   const location = useLocation()
@@ -16,19 +22,13 @@ const Header = () => {
       </Brand>
       <Nav>
         <Link to="/">
-          <NavLink $active={location.pathname === '/'}>
-            🏠 首页
-          </NavLink>
+          <NavLink $active={location.pathname === '/'}>🏠 首页</NavLink>
         </Link>
         <Link to="/login">
-          <NavLink $active={location.pathname === '/login'}>
-            🔐 登录
-          </NavLink>
+          <NavLink $active={location.pathname === '/login'}>🔐 登录</NavLink>
         </Link>
         <Link to="/photo">
-          <NavLink $active={location.pathname === '/photo'}>
-            🖼️ 图片
-          </NavLink>
+          <NavLink $active={location.pathname === '/photo'}>🖼️ 图片</NavLink>
         </Link>
       </Nav>
     </Container>