scaffold-nextjs-app

pjt222

更新于 2 days ago

6 次查看

开发reactapi

关于

This skill scaffolds a new Next.js application with App Router, TypeScript, and modern defaults. It handles project creation, directory structure, routing setup, and initial configuration. Use it to kickstart web projects requiring server-side rendering, API routes, or full-stack TypeScript applications.

快速安装

Claude Code

技能文档

name: scaffold-nextjs-app description: > 搭建新的 Next.js 应用程序，使用 App Router、TypeScript 及现代默认配置。涵盖项目创建、目录结构、路由设置及初始配置。适用于启动新的 Web 应用项目、创建支持服务端渲染的 React 前端、构建带 API 路由的全栈应用，或从零搭建 TypeScript Web 项目。 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: web-dev complexity: basic language: TypeScript tags: nextjs, react, typescript, app-router, scaffold locale: zh-CN source_locale: en source_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16

搭建 Next.js 应用

使用 App Router、TypeScript 和生产就绪默认配置创建新的 Next.js 应用程序。

适用场景

启动新的 Web 应用项目
创建支持服务端渲染的 React 前端
构建带 API 路由的全栈应用
搭建 TypeScript Web 项目

输入

必需：应用名称
必需：包管理器偏好（npm、yarn、pnpm）
可选：是否包含 Tailwind CSS（默认：是）
可选：是否包含 ESLint（默认：是）
可选：src/ 目录结构（默认：是）

步骤

第 1 步：创建项目

npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

回答提示或使用标志以非交互方式设置所有选项。

预期结果： 项目目录已创建，所有依赖项已安装。

失败处理： 检查 Node.js 版本（node --version，必须 >= 18.17）。确保 npx 可用。如果命令在提示时挂起，添加 --use-npm（或 --use-pnpm/--use-yarn）标志以跳过包管理器提示。

第 2 步：验证项目结构

my-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx        # Root layout
│   │   ├── page.tsx          # Home page
│   │   ├── globals.css       # Global styles
│   │   └── favicon.ico
│   └── lib/                  # Shared utilities (create manually)
├── public/                   # Static assets
├── next.config.ts            # Next.js configuration
├── tailwind.config.ts        # Tailwind configuration
├── tsconfig.json             # TypeScript configuration
├── package.json
└── .eslintrc.json

预期结果： 所有列出的目录和文件均存在。

失败处理： 如果 src/ 目录缺失，说明未传入 --src-dir 标志。重新运行带该标志的 create-next-app，或手动将文件移入 src/app/。

第 3 步：配置 Next.js

根据项目需求编辑 next.config.ts：

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Enable React strict mode
  reactStrictMode: true,

  // Image optimization domains
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "example.com",
      },
    ],
  },
};

export default nextConfig;

预期结果： next.config.ts 保存时无 TypeScript 错误。

失败处理： 如果文件使用 .js 扩展名而非 .ts，请重命名。确保 NextConfig 类型从 "next" 导入。

第 4 步：设置目录约定

创建常用目录：

mkdir -p src/app/api
mkdir -p src/components
mkdir -p src/lib
mkdir -p src/types

预期结果： src/ 下四个目录均已创建。

失败处理： 如果 src/ 不存在，先创建它，或调整路径以匹配项目结构（非 src 布局在根目录使用 app/）。

第 5 步：创建基础布局

编辑 src/app/layout.tsx：

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "My Application",
  description: "Application description",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
}

预期结果： 布局使用 Inter 字体渲染并包裹所有页面。

失败处理： 如果字体加载失败，检查网络连接。临时方案可将 Inter 替换为系统字体回退。

第 6 步：添加示例 API 路由

创建 src/app/api/health/route.ts：

import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ status: "ok", timestamp: new Date().toISOString() });
}

预期结果： 文件创建于 src/app/api/health/route.ts。

失败处理： 确保 api/health/ 目录存在。文件必须导出具名 HTTP 方法处理函数（GET、POST 等），而非默认导出。

第 7 步：运行开发服务器

cd my-app
npm run dev

预期结果： 应用在 http://localhost:3000 运行。

失败处理： 检查 Node.js 版本（>= 18.17）。如果依赖项缺失，运行 npm install。

验证清单

npm run dev 启动无错误
首页在 localhost:3000 正常加载
TypeScript 编译成功
Tailwind CSS 类已应用
API 路由在 /api/health 响应
ESLint 运行无错误（npm run lint）

常见问题

Node.js 版本：Next.js 需要 Node.js >= 18.17。使用 node --version 检查。
端口冲突：默认端口 3000 可能已被占用。使用 npm run dev -- -p 3001。
导入别名混淆：@/* 映射到 src/*，不要与 node_modules 导入混淆。
Pages 与 App Router 混用：确保使用 App Router（src/app/）而非 Pages Router（src/pages/）。

GitHub 仓库

pjt222/agent-almanac

路径: i18n/zh-CN/skills/scaffold-nextjs-app

agentsagentskillsai-assisted-developmentclaude-codeskillsteams