nsbp-cli 0.2.26 → 0.2.29

package/README.md

@@ -147,7 +147,7 @@ node ./bin/nsbp.js --help  # Test CLI locally
 
 - **Package Name**: `nsbp-cli`
 - **Bin Command**: `nsbp` (install globally and run `nsbp --help`)
-- **Version**: `0.2.26`
+- **Version**: `0.2.29`
 - **Dependencies**: chalk, commander, fs-extra, inquirer
 - **Package Manager**: Uses pnpm (also compatible with npm)
 - **Node Version**: >=16.0.0

package/bin/nsbp.js

@@ -1,55 +1,59 @@
 #!/usr/bin/env node
 
-const { Command } = require('commander');
-const chalk = require('chalk');
-const fs = require('fs-extra');
-const path = require('path');
-const { execSync } = require('child_process');
-const inquirer = require('inquirer');
+const { Command } = require('commander')
+const chalk = require('chalk')
+const fs = require('fs-extra')
+const path = require('path')
+const { execSync } = require('child_process')
+const inquirer = require('inquirer')
 
 // Read version from package.json dynamically
-const packageJson = require('../package.json');
+const packageJson = require('../package.json')
 
-const program = new Command();
+const program = new Command()
 
 program
   .name('nsbp')
   .description('CLI tool to create NSBP (Node React SSR by Webpack) projects')
-  .version(packageJson.version);
+  .version(packageJson.version)
 
 program
   .command('create <project-name>')
   .description('Create a new NSBP project')
-  .option('-t, --template <template>', 'Specify template (basic, blog, ecommerce)', 'basic')
+  .option(
+    '-t, --template <template>',
+    'Specify template (basic, blog, ecommerce)',
+    'basic'
+  )
   .option('--skip-install', 'Skip pnpm install')
   .action(async (projectName, options) => {
-    console.log(chalk.cyan(`🚀 Creating NSBP project: ${projectName}`));
-    
+    console.log(chalk.cyan(`🚀 Creating NSBP project: ${projectName}`))
+
     try {
       // Check if directory already exists
-      const targetDir = path.join(process.cwd(), projectName);
+      const targetDir = path.join(process.cwd(), projectName)
       if (fs.existsSync(targetDir)) {
         const { overwrite } = await inquirer.prompt([
           {
             type: 'confirm',
             name: 'overwrite',
             message: `Directory "${projectName}" already exists. Overwrite?`,
-            default: false,
-          },
-        ]);
+            default: false
+          }
+        ])
         if (!overwrite) {
-          console.log(chalk.yellow('Operation cancelled.'));
-          process.exit(0);
+          console.log(chalk.yellow('Operation cancelled.'))
+          process.exit(0)
         }
-        fs.removeSync(targetDir);
+        fs.removeSync(targetDir)
       }
 
       // Create project directory
-      fs.ensureDirSync(targetDir);
+      fs.ensureDirSync(targetDir)
 
       // Get template source path from built-in templates
-      const templateSource = path.join(__dirname, '../templates/basic');
-      
+      const templateSource = path.join(__dirname, '../templates/basic')
+
       // List of files/directories to copy
       const copyItems = [
         'src',
@@ -67,112 +71,128 @@ program
         'gitignore',
         'Makefile',
         'README.md'
-      ];
+      ]
 
       // Copy each item
-      console.log(chalk.cyan('📦 Copying project files...'));
+      console.log(chalk.cyan('📦 Copying project files...'))
       for (const item of copyItems) {
-        const source = path.join(templateSource, item);
-        const target = path.join(targetDir, item);
+        const source = path.join(templateSource, item)
+        const target = path.join(targetDir, item)
         if (fs.existsSync(source)) {
           if (fs.statSync(source).isDirectory()) {
             fs.copySync(source, target, {
               filter: (src) => {
                 // Exclude node_modules, build, .temp_cache, etc.
                 // Use relative path to avoid matching parent directory names
-                const relativePath = path.relative(source, src);
-                const segments = relativePath.split(path.sep);
-                const excluded = ['node_modules', '.temp_cache', 'build', '.git', '.DS_Store', '.serena'];
-                return !segments.some(seg => excluded.includes(seg));
+                const relativePath = path.relative(source, src)
+                const segments = relativePath.split(path.sep)
+                const excluded = [
+                  'node_modules',
+                  '.temp_cache',
+                  'build',
+                  '.git',
+                  '.DS_Store',
+                  '.serena'
+                ]
+                return !segments.some((seg) => excluded.includes(seg))
               }
-            });
+            })
           } else {
-            fs.copySync(source, target);
+            fs.copySync(source, target)
           }
         }
       }
 
       // Rename gitignore to .gitignore
-      const gitignorePath = path.join(targetDir, 'gitignore');
+      const gitignorePath = path.join(targetDir, 'gitignore')
       if (fs.existsSync(gitignorePath)) {
-        fs.renameSync(gitignorePath, path.join(targetDir, '.gitignore'));
+        fs.renameSync(gitignorePath, path.join(targetDir, '.gitignore'))
       }
 
       // Create package.json for new project
-      const originalPackage = require(path.join(templateSource, 'package.json'));
+      const originalPackage = require(path.join(templateSource, 'package.json'))
       const newPackage = {
         ...originalPackage,
         name: projectName,
         version: '1.0.0',
         description: `NSBP project: ${projectName}`
-      };
+      }
 
       fs.writeFileSync(
         path.join(targetDir, 'package.json'),
         JSON.stringify(newPackage, null, 2)
-      );
+      )
 
       // Remove package-lock.json if exists (use pnpm instead)
-      const packageLockPath = path.join(targetDir, 'package-lock.json');
+      const packageLockPath = path.join(targetDir, 'package-lock.json')
       if (fs.existsSync(packageLockPath)) {
-        fs.removeSync(packageLockPath);
+        fs.removeSync(packageLockPath)
       }
 
       // Create .npmignore to prevent package-lock.json from being committed
-      const npmignorePath = path.join(targetDir, '.npmignore');
+      const npmignorePath = path.join(targetDir, '.npmignore')
       if (!fs.existsSync(npmignorePath)) {
-        fs.writeFileSync(npmignorePath, 'package-lock.json\n');
+        fs.writeFileSync(npmignorePath, 'package-lock.json\n')
       }
 
       // Optionally install dependencies
       if (!options.skipInstall) {
         // Check if pnpm is available
         try {
-          execSync('which pnpm', { stdio: 'ignore' });
+          execSync('which pnpm', { stdio: 'ignore' })
         } catch {
-          console.error(chalk.red('❌ pnpm is not installed or not available in PATH.'));
-          console.error(chalk.yellow('Please install pnpm before continuing:'));
-          console.error(chalk.cyan('  npm install -g pnpm'));
-          console.error(chalk.yellow('Or use --skip-install flag to skip dependency installation.'));
-          process.exit(1);
+          console.error(
+            chalk.red('❌ pnpm is not installed or not available in PATH.')
+          )
+          console.error(chalk.yellow('Please install pnpm before continuing:'))
+          console.error(chalk.cyan('  npm install -g pnpm'))
+          console.error(
+            chalk.yellow(
+              'Or use --skip-install flag to skip dependency installation.'
+            )
+          )
+          process.exit(1)
         }
-        
-        console.log(chalk.cyan('📦 Installing dependencies...'));
-        process.chdir(targetDir);
-        execSync('pnpm install', { stdio: 'inherit' });
+
+        console.log(chalk.cyan('📦 Installing dependencies...'))
+        process.chdir(targetDir)
+        execSync('pnpm install', { stdio: 'inherit' })
       }
 
-      console.log(chalk.green(`✅ NSBP project "${projectName}" created successfully!`));
-      console.log(chalk.yellow('\nNext steps:'));
-      console.log(`  cd ${projectName}`);
+      console.log(
+        chalk.green(`✅ NSBP project "${projectName}" created successfully!`)
+      )
+      console.log(chalk.yellow('\nNext steps:'))
+      console.log(`  cd ${projectName}`)
       if (options.skipInstall) {
-        console.log('  pnpm install');
+        console.log('  pnpm install')
       }
-      console.log('  pnpm run dev');
-      console.log(chalk.cyan('\nHappy coding! 🎉'));
-
+      console.log('  pnpm run dev')
+      console.log(chalk.cyan('\nHappy coding! 🎉'))
     } catch (error) {
-      console.error(chalk.red(`❌ Error creating project: ${error.message}`));
-      process.exit(1);
+      console.error(chalk.red(`❌ Error creating project: ${error.message}`))
+      process.exit(1)
     }
-  });
+  })
 
 program
   .command('info')
   .description('Display information about NSBP')
   .action(() => {
-    console.log(chalk.cyan('NSBP - Node React SSR by Webpack'));
-    console.log(chalk.gray('A lightweight React SSR framework with full Webpack control.'));
-    console.log('');
-    console.log(chalk.yellow('Key Features:'));
-    console.log('  • ~60% less resource usage than Next.js');
-    console.log('  • Full Webpack configuration control');
-    console.log('  • TypeScript support out of the box');
-    console.log('  • Built-in image service');
-    console.log('');
-    console.log(chalk.cyan('Website: ') + 'https://github.com/nsbp/nsbp');
-    console.log(chalk.cyan('Usage:   ') + 'nsbp create my-app');
-  });
+    console.log(chalk.cyan('NSBP - Node React SSR by Webpack'))
+    console.log(
+      chalk.gray('A lightweight React SSR framework with full Webpack control.')
+    )
+    console.log('')
+    console.log(chalk.yellow('Key Features:'))
+    console.log('  • Lightweight and flexible')
+    console.log('  • Full Webpack configuration control')
+    console.log('  • TypeScript support out of the box')
+    console.log('  • Built-in image service')
+    console.log('')
+    console.log(chalk.cyan('Website: ') + 'https://github.com/nsbp/nsbp')
+    console.log(chalk.cyan('Usage:   ') + 'nsbp create my-app')
+  })
 
 // Parse command line arguments
-program.parse();
+program.parse()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsbp-cli",
-  "version": "0.2.26",
+  "version": "0.2.29",
   "description": "CLI tool for creating NSBP (Node React SSR by Webpack) projects",
   "main": "index.js",
   "homepage": "https://nsbp.erishen.cn/",

package/templates/basic/README.md

@@ -2,6 +2,49 @@
 
 🌐 **Online Demo**: [https://nsbp.erishen.cn/](https://nsbp.erishen.cn/)
 
+## 🚀 快速开始
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 初始化 Git hooks（代码质量检查）
+pnpm run prepare
+
+# 3. 配置环境变量
+cp .env.example .env
+
+# 4. 启动开发环境
+pnpm run dev
+```
+
+## 📝 开发工具
+
+本项目配置了完整的代码质量检查工具：
+
+- **ESLint**: TypeScript + React 代码质量检查
+- **Prettier**: 自动代码格式化
+- **Husky**: Git hooks 自动化
+
+### 代码检查命令
+
+```bash
+pnpm run lint        # Lint 检查
+pnpm run lint:fix    # Lint 自动修复
+pnpm run format      # 格式化代码
+```
+
+### Git Hooks
+
+- `pre-commit`: 提交前自动 lint 和格式化
+- `pre-push`: 推送前运行完整 lint 检查
+- `commit-msg`: 验证提交信息格式（Conventional Commits）
+
+详细配置请查看：
+- [docs/ESLINT_AND_PRETTIER.md](./docs/ESLINT_AND_PRETTIER.md) - ESLint 和 Prettier 配置
+- [docs/SETUP_GIT_HOOKS.md](./docs/SETUP_GIT_HOOKS.md) - Git hooks 配置
+- [docs/DEVELOPMENT_GUIDE.md](./docs/DEVELOPMENT_GUIDE.md) - 完整开发指南
+
 ## 环境变量配置
 
 ### 快速开始

package/templates/basic/docs/DEVELOPMENT_GUIDE.md

@@ -0,0 +1,290 @@
+# NSBP 开发指南
+
+## 🚀 快速开始
+
+### 1. 安装依赖
+
+```bash
+# 使用 pnpm（Husky hooks 自动创建）
+pnpm install
+```
+
+⚠️ **注意**：Husky 9.x 会自动创建 Git hooks，无需运行 `pnpm run prepare`。
+
+### 2. 启动开发环境
+
+```bash
+# 开发模式（带热重载）
+pnpm run dev
+
+# 或分步启动
+pnpm run dev:init      # 初始化构建
+pnpm run dev:build:*  # 监听文件变化
+pnpm run dev:build:start # 启动服务器
+```
+
+### 3. 访问应用
+
+- **客户端渲染**: http://localhost:3001/
+- **服务端渲染**: http://localhost:3001/?seo=1
+- **BrowserSync**: http://localhost:3000/
+
+## 📝 开发工作流
+
+### 提交代码
+
+```bash
+# 1. 创建功能分支
+git checkout -b feat/your-feature
+
+# 2. 开发并测试
+# ...
+
+# 3. 格式化代码
+pnpm run format
+
+# 4. Lint 检查
+pnpm run lint
+
+# 5. 提交（Git hooks 自动运行 lint-staged）
+git add .
+git commit -m "feat: add new feature"
+
+# 6. 推送（Git hooks 自动运行 lint）
+git push origin feat/your-feature
+```
+
+### 提交信息格式
+
+遵循 Conventional Commits 规范：
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**类型 (type)**:
+- `feat`: 新功能
+- `fix`: Bug 修复
+- `docs`: 文档更新
+- `style`: 代码格式化
+- `refactor`: 重构（非功能或 Bug）
+- `test`: 测试相关
+- `chore`: 构建/工具链相关
+- `perf`: 性能优化
+- `ci`: CI 配置变更
+
+**示例**:
+```bash
+git commit -m "feat(core): add SSR data preloading support"
+git commit -m "fix(client): resolve hydration mismatch error"
+git commit -m "docs(readme): update installation guide"
+```
+
+## 🛠️ 常用命令
+
+### 开发命令
+
+```bash
+pnpm run dev              # 完整开发环境
+pnpm run dev:init        # 初始化构建
+pnpm run dev:build:*     # 监听文件变化
+pnpm run dev:build:start  # 启动开发服务器
+```
+
+### 构建命令
+
+```bash
+pnpm run build            # 生产构建
+pnpm run build:server     # 构建服务端
+pnpm run build:client     # 构建客户端
+pnpm run start            # 启动生产服务器
+```
+
+### 代码质量
+
+```bash
+pnpm run lint            # ESLint 检查
+pnpm run lint:fix        # ESLint 自动修复
+pnpm run format          # Prettier 格式化
+pnpm run lint-staged     # 对暂存文件运行 lint（Git 钩子自动执行）
+```
+
+### 清理命令
+
+```bash
+pnpm run clean           # 清理构建产物和缓存
+rm -rf .temp_cache      # 清理 Webpack 缓存
+rm -rf node_modules      # 清理依赖
+pnpm install            # 重新安装依赖
+```
+
+### Docker 命令
+
+```bash
+# 生产环境
+make build              # 构建镜像
+make prod               # 启动生产环境
+make logs               # 查看日志
+make restart            # 重启容器
+make shell              # 进入容器
+make down               # 停止容器
+make clean              # 完全清理
+
+# 开发环境
+make dev                # 启动开发环境
+make logs-dev           # 查看开发日志
+make rebuild-dev        # 重新构建并启动
+```
+
+## 📂 项目结构
+
+```
+nsbp/
+├── cli/                   # CLI 工具和模板
+│   ├── bin/             # CLI 二进制文件
+│   ├── templates/        # 项目模板
+│   └── scripts/          # 构建脚本
+├── config/               # Webpack 配置
+│   ├── webpack.base.js    # 基础配置
+│   ├── webpack.client.js  # 客户端配置
+│   └── webpack.server.js  # 服务端配置
+├── public/              # 静态资源输出目录
+├── src/                 # 源代码目录
+│   ├── client/          # 客户端入口
+│   ├── server/          # 服务端代码
+│   ├── containers/      # 页面组件
+│   ├── component/       # 公共组件
+│   ├── styled/          # 样式组件
+│   ├── services/        # API 服务
+│   ├── reducers/        # Redux reducers
+│   ├── store/           # Redux store
+│   └── utils/           # 工具函数
+├── scripts/             # Node.js 脚本
+├── docker/              # Docker 配置
+├── docs/                # 文档
+└── .husky/              # Git hooks
+```
+
+## 🔍 代码检查工具
+
+### ESLint
+
+- **配置文件**: `.eslintrc.js`
+- **忽略文件**: `.eslintignore`
+- **用途**: TypeScript + React 代码质量检查
+
+**规则**:
+- TypeScript: 类型检查、未使用变量警告
+- React: Hooks 规则、组件最佳实践
+- Prettier: 代码风格一致性
+
+### Prettier
+
+- **配置文件**: `.prettierrc.js`
+- **用途**: 自动格式化代码
+
+**配置**:
+- 2 空格缩进
+- 单引号
+- 无分号
+- 100 字符换行
+
+### Husky
+
+- **配置目录**: `.husky/`
+- **用途**: Git 钩子自动化
+
+**钩子**:
+- `pre-commit`: 提交前 lint 暂存文件
+- `pre-push`: 推送前全量 lint
+- `commit-msg`: 验证提交信息格式
+
+## 🐛 常见问题
+
+### Webpack 缓存错误
+
+**问题**:
+```
+Cannot find module 'xxx'
+Restoring failed for ResolverCachePlugin
+```
+
+**解决方案**:
+```bash
+# 清理缓存
+pnpm run clean
+rm -rf .temp_cache
+
+# 重新构建
+pnpm run dev
+```
+
+### Git 钩子失败
+
+**问题**:
+```
+husky - pre-commit hook failed
+```
+
+**解决方案**:
+```bash
+# 查看错误
+pnpm run lint
+
+# 自动修复
+pnpm run lint:fix
+
+# 重新提交
+git add .
+git commit -m "style: resolve linting issues"
+```
+
+### TypeScript 类型错误
+
+**问题**: 编辑器显示类型错误，但项目能编译
+
+**解决方案**:
+```bash
+# 重启 TypeScript 服务器
+# VSCode: Ctrl+Shift+P -> "TypeScript: Restart TS Server"
+
+# 确保项目已编译
+pnpm run build:server
+```
+
+### Docker 权限错误
+
+**问题**:
+```
+EACCES: permission denied
+```
+
+**解决方案**:
+Docker 已在 `entrypoint.sh` 中自动修复权限，无需手动处理。
+
+## 📚 相关文档
+
+- [ESLINT_AND_PRETTIER.md](./ESLINT_AND_PRETTIER.md) - 代码风格配置
+- [SETUP_GIT_HOOKS.md](./SETUP_GIT_HOOKS.md) - Git hooks 配置
+- [README.md](../README.md) - 项目总览
+
+## 💡 最佳实践
+
+1. **提交前**: 总是运行 `pnpm run format` 和 `pnpm run lint:fix`
+2. **分支管理**: 使用功能分支，不直接在 main/master 分支开发
+3. **提交信息**: 遵循 Conventional Commits 规范
+4. **代码审查**: 提交 PR 前自查代码质量和格式
+5. **定期清理**: 定期运行 `pnpm run clean` 清理缓存
+6. **依赖更新**: 使用 `pnpm update` 而不是手动修改版本号
+
+## 🎯 下一步
+
+- [ ] 配置 CI/CD 流程
+- [ ] 添加单元测试
+- [ ] 添加 E2E 测试
+- [ ] 配置代码覆盖率
+- [ ] 设置自动化部署