ck:web-frameworks

Web 框架技能组

使用 Next.js、Turborepo 和 RemixIcon 构建现代全栈 Web 应用的综合指南。

概述

此技能组结合了三款强大的 Web 开发工具：

Next.js - React 框架，提供 SSR、SSG、RSC 和优化功能
Turborepo - 面向 JavaScript/TypeScript 的高性能 monorepo 构建系统
RemixIcon - 图标库，包含 3,100 多个线框和实心风格的图标

何时使用此技能组

• 使用现代 React 构建新的全栈 Web 应用
• 设置包含多个应用和共享包的 monorepo
• 实现服务端渲染和静态生成
• 使用智能缓存优化构建性能
• 使用专业图标打造风格一致的 UI
• 管理多个项目间的工作区依赖
• 通过适当的优化部署可用于生产环境的应用

技术栈选择指南

单个应用：Next.js + RemixIcon

构建独立应用时使用：

• 电商网站
• 营销网站
• SaaS 应用
• 文档网站
• 博客和内容平台

设置：

npx create-next-app@latest my-app
cd my-app
npm install remixicon

Monorepo：Next.js + Turborepo + RemixIcon

构建包含共享代码的多个应用时使用：

• 微前端
• 多租户平台
• 使用共享组件库的内部工具
• 共享逻辑的多个应用（Web、管理后台、移动 Web）
• 带文档网站的设计系统

设置：

npx create-turbo@latest my-monorepo
# Then configure Next.js apps in apps/ directory
# Install remixicon in shared UI packages

框架功能对比

功能	Next.js	Turborepo	RemixIcon
主要用途	Web 框架	构建系统	UI 图标
最适合	SSR/SSG 应用	Monorepo	风格一致的图标
性能	内置优化	缓存和并行任务	轻量字体/SVG
TypeScript	完全支持	完全支持	提供类型定义

快速入门

Next.js 应用

# Create new project
npx create-next-app@latest my-app
cd my-app

# Install RemixIcon
npm install remixicon

# Import in layout
# app/layout.tsx
import 'remixicon/fonts/remixicon.css'

# Start development
npm run dev

Turborepo Monorepo

# Create monorepo
npx create-turbo@latest my-monorepo
cd my-monorepo

# Structure:
# apps/web/          - Next.js application
# apps/docs/         - Documentation site
# packages/ui/       - Shared components with RemixIcon
# packages/config/   - Shared configs
# turbo.json         - Pipeline configuration

# Run all apps
npm run dev

# Build all packages
npm run build

集成 RemixIcon

// Webfont (HTML/CSS)
<i className="ri-home-line"></i>
<i className="ri-search-fill ri-2x"></i>

// React component
import { RiHomeLine, RiSearchFill } from "@remixicon/react"
<RiHomeLine size={24} />
<RiSearchFill size={32} color="blue" />

参考文档导航

Next.js 参考文档：

• App Router 架构 - 路由、布局、页面、并行路由
• 服务器组件 - RSC 模式、客户端与服务器端、流式传输
• 数据获取 - fetch API、缓存、重新验证、加载状态
• 优化 - 图片、字体、脚本、包分析、PPR

Turborepo 参考文档：

• 设置与配置 - 安装、工作区配置、包结构
• 任务管道 - 依赖、并行执行、任务排序
• 缓存策略 - 本地缓存、远程缓存、缓存失效

RemixIcon 参考文档：

• 集成指南 - 安装、使用、自定义、无障碍

常见模式与工作流

模式 1：全栈 Monorepo

my-monorepo/
├── apps/
│   ├── web/              # Customer-facing Next.js app
│   ├── admin/            # Admin dashboard Next.js app
│   └── docs/             # Documentation site
├── packages/
│   ├── ui/               # Shared UI with RemixIcon
│   ├── api-client/       # API client library
│   ├── config/           # ESLint, TypeScript configs
│   └── types/            # Shared TypeScript types
└── turbo.json            # Build pipeline

turbo.json：

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {},
    "test": {
      "dependsOn": ["build"]
    }
  }
}

模式 2：共享组件库

// packages/ui/src/button.tsx
import { RiLoader4Line } from "@remixicon/react"

export function Button({ children, loading, icon }) {
  return (
    <button>
      {loading ? <RiLoader4Line className="animate-spin" /> : icon}
      {children}
    </button>
  )
}

// apps/web/app/page.tsx
import { Button } from "@repo/ui/button"
import { RiHomeLine } from "@remixicon/react"

export default function Page() {
  return <Button icon={<RiHomeLine />}>Home</Button>
}

模式 3：优化数据获取

// app/posts/[slug]/page.tsx
import { notFound } from 'next/navigation'

// Static generation at build time
export async function generateStaticParams() {
  const posts = await getPosts()
  return posts.map(post => ({ slug: post.slug }))
}

// Revalidate every hour
async function getPost(slug: string) {
  const res = await fetch(`https://api.example.com/posts/${slug}`, {
    next: { revalidate: 3600 }
  })
  if (!res.ok) return null
  return res.json()
}

export default async function Post({ params }: { params: { slug: string } }) {
  const post = await getPost(params.slug)
  if (!post) notFound()

  return <article>{post.content}</article>
}

模式 4：Monorepo CI/CD 管道

# .github/workflows/ci.yml
name: ck:CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm install
      - run: npx turbo run build test lint
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

实用脚本

/scripts/ 目录中的 Python 实用工具：

nextjs-init.py - 使用最佳实践初始化 Next.js 项目
turborepo-migrate.py - 将现有 monorepo 转换为 Turborepo

使用示例：

# Initialize new Next.js app with TypeScript and recommended setup
python scripts/nextjs-init.py --name my-app --typescript --app-router

# Migrate existing monorepo to Turborepo with dry-run
python scripts/turborepo-migrate.py --path ./my-monorepo --dry-run

# Run tests
cd scripts/tests
pytest

最佳实践

Next.js：

• 默认使用 Server Components，仅在需要时使用 Client Components
• 实现适当的加载和错误状态
• 使用 Image 组件进行自动优化
• 设置适当的元数据以优化 SEO
• 利用缓存策略（force-cache、revalidate、no-store）

Turborepo：

• 采用清晰的目录划分（apps/、packages/）组织单体仓库
• 正确设置任务依赖关系（拓扑排序使用 ^build）
• 配置输出，以便正确缓存
• 启用远程缓存，便于团队协作
• 使用筛选器，仅对已更改的包运行任务

RemixIcon：

• 简洁界面使用线框样式，强调内容使用填充样式
• 保持 24x24 网格对齐，以实现清晰的渲染效果
• 提供 aria-label，以确保无障碍访问
• 使用 currentColor，灵活适配主题
• 多个图标优先使用 Web 字体，单个图标使用 SVG

资源

• Next.js：https://nextjs.org/docs/llms.txt
• Turborepo：https://turbo.build/repo/docs
• RemixIcon：https://remixicon.com

实施检查清单

使用此技术栈进行构建：

• 创建项目结构（单个应用或单体仓库）
• 配置 TypeScript 和 ESLint
• 使用 App Router 设置 Next.js
• 配置 Turborepo 流水线（如果使用单体仓库）
• 安装并配置 RemixIcon
• 实现路由和布局
• 添加加载和错误状态
• 配置图像和字体优化
• 设置数据获取模式
• 配置缓存策略
• 根据需要添加 API 路由
• 实现共享组件库（如果使用单体仓库）
• 配置远程缓存（如果使用单体仓库）
• 设置 CI/CD 流水线
• 配置部署平台