# NextJsWeb

**Repository Path**: TheCrisis/next-js-web

## Basic Information

- **Project Name**: NextJsWeb
- **Description**: nextJS框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# next-js-web

前后端一体的 monorepo：前端 Next.js + TypeScript，后端 Java。

## 目录结构

```
.
├── apps/
│   ├── web/                # Next.js 16 + React 19 + TypeScript 前端
│   └── server/             # Java 后端 Spring Boot 3.5.16（见 apps/server/README.md）
├── packages/
│   └── shared/             # 前后端共享的 API 契约类型（@next-js-web/shared）
├── tsconfig.base.json      # 各包共用的 TS 基础配置
└── package.json            # workspace 根清单
```

## 环境要求

- Node.js >= 20.9（推荐 22 LTS）
- npm >= 10（使用 npm workspaces 管理，无需 pnpm / yarn）
- 后端另需 JDK 21 + Maven 3.9 —— **当前机器尚未安装**，详见 `apps/server/README.md`

## 快速开始

依赖必须在**仓库根目录**安装一次。workspace 会把各子包的依赖统一提升到根 `node_modules`：

```bash
npm install
```

启动前端开发服务器：

```bash
npm run dev            # 等价于 npm run dev -w @next-js-web/web
```

打开 http://localhost:3000 查看结果。

## 常用命令

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 启动前端开发服务器（3000） |
| `npm run build` | 构建前端生产版本 |
| `npm run start` | 运行前端生产构建 |
| `npm run lint` | 对所有 workspace 执行 lint |
| `npm run typecheck` | 对所有 workspace 执行类型检查 |

只操作单个包时用 `-w` 指定：

```bash
npm run dev -w @next-js-web/web
npm run typecheck -w @next-js-web/shared
npm install <pkg> -w @next-js-web/web      # 给前端加依赖
npm install <pkg> -w @next-js-web/shared   # 给共享包加依赖
```

## workspace 约定

- 包名统一使用 `@next-js-web/` 作用域，避免与 npm 公共包重名冲突。
- 新增应用放 `apps/`，新增可复用库放 `packages/`。根 `package.json` 的 `workspaces` 已用通配符覆盖，
  新增目录**无需**再改配置。
- `packages/shared` 是纯 TS 源码包，由前端 Next.js 的 `transpilePackages` 直接消费，
  **没有构建步骤**，改完即可生效。
- 跨包引用一律使用包名（`@next-js-web/shared`），不要写 `../../packages/shared` 这类相对路径。

## 前端样式约定

**新页面一律使用 Tailwind 工具类。**（2026-09-27 更新：此前为兼容老浏览器而采取的「页面尽量不依赖 Tailwind」
处置已废止。）

设计令牌集中在 `apps/web/app/globals.css` 的 `@theme` 里，Tailwind 会自动生成工具类，业务代码直接写类名：

| 类别 | 可用类名（节选） |
| --- | --- |
| 高饱和色板 | `bg-nb-pink` / `bg-nb-yellow-soft` / `bg-nb-pink-tint` / `border-nb-line` / `text-nb-ink` |
| 偏移实心阴影 | `shadow-nb-sm` / `shadow-nb-md` / `shadow-nb-lg` |
| 字体栈 | `font-display` / `font-body` / `font-mono-nb` |
| 动画 | `animate-nb-float` / `animate-nb-wiggle` / `animate-nb-blink` |
| 纹理背景 | `bg-nb-dot` / `bg-nb-stripe`（配 `bg-size-[16px_16px]`） |

约定要点：

- 新增颜色 / 阴影 / 动画一律加到 `globals.css` 的 `@theme`，不要在页面里另起 `:root` 变量。
- Tailwind 只识别**字面量类名**：`bg-nb-${tone}` 这类动态拼接一条 CSS 都不会生成，
  需要按数据切换样式时把完整类名写进数据。
- 只有 Tailwind 表达不了的少数规则才手写 CSS，且必须放进 `@layer components`。
- 完整参考实现：`apps/web/app/personPage/`（由一份静态 HTML 作品集还原而来）。

> 历史遗留：首页 `apps/web/app/page.tsx` 的样式独立在 `app/css/home.css`、不依赖 Tailwind。
> 该页保持现状，但**新页面不要照它写**。

## 后端状态

`apps/server` 是**单模块 Spring Boot 3.5.16 + Java 21** 工程骨架，已包含统一响应体 `Result<T>`、
分页契约 `PageQuery` / `PageResult`、全局异常处理、CORS 放行、H2 本地内存库与 Swagger 文档。

**已通过编译 + 运行双验证**：`mvn clean compile` BUILD SUCCESS；`/api/health` 返回 `{"code":0,...}`；
`/v3/api-docs`、`/swagger-ui.html` 均 200。运行方式与两个版本坑（springdoc 必须用 2.8.x、
`mybatis-plus-jsqlparser` 必须显式声明）见 `apps/server/README.md`。