nextjs-patterns
Next.js 15+ 开发模式,含 App Router、服务器组件、客户端组件和 Convex 集成。用于构建 React 组件、页面、布局或在此 monorepo 中使用 Next.js 功能。
📖 中文导读:Next.js 15+ 开发模式,含 App Router、服务器组件、客户端组件和 Convex 集成。用于构建 React 组件、页面、布局或在此 monorepo 中使用 Next.js 功能。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: nextjs-patterns description: Next.js 15+ development patterns with App Router, Server Components, Client Components, and Convex integration. Use when building React components, pages, layouts, or working with Next.js features in this monorepo.
Next.js Development Patterns
When to use this skill
Use this skill when:
- Creating pages, layouts, or route handlers
- Building React components (Server or Client)
- Integrating Convex with Next.js
- Implementing loading states, error boundaries
- Working with metadata, SEO, or routing
App Router Structure
app/
├── layout.tsx # Root layout (Server Component)
├── page.tsx # Home page
├── loading.tsx # Loading UI
├── error.tsx # Error boundary
├── not-found.tsx # 404 page
├── (routes)/
│ └── dashboard/
│ ├── page.tsx
│ └── layout.tsx
└── api/
└── route.ts # API routes
Server vs Client Components
Server Components (Default)
// No directive needed - default is Server Component
import { api } from "@/convex/_generated/api";
import { fetchQuery } from "convex/nextjs";
export default async function Page() {
// Can fetch data directly
const data = await fetchQuery(api.items.list, {});
return <div>{/* render data */}</div>;
}
Client Components
"use client";
import { useQuery, useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
export function InteractiveComponent() {
const data = useQuery(api.items.list, {});
const addItem = useMutation(api.items.add);
if (data === undefined) return <LoadingSpinner />;
return (
<button onClick={() => addItem({ name: "New" })}>
Add Item
</button>
);
}
Convex Provider Setup
// providers/ConvexClientProvider.tsx
"use client";
import { ConvexProvider, ConvexReactClient } from "convex/react";
const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
export function ConvexClientProvider({ children }: { children: React.ReactNode }) {
return <ConvexProvider client={convex}>{children}</ConvexProvider>;
}
Loading States Pattern
// Always handle undefined state from useQuery
const data = useQuery(api.items.list, {});
if (data === undefined) {
return <Skeleton />; // Loading
}
if (data.length === 0) {
return <EmptyState />;
}
return <ItemList items={data} />;
Error Boundaries
// app/error.tsx
"use client";
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
return (
<div>
<h2>Something went wrong!</h2>
<button onClick={reset}>Try again</button>
</div>
);
}
Metadata & SEO
import type { Metadata } from "next";
export const metadata: Metadata = {
title: "Page Title",
description: "Page description",
openGraph: {
title: "OG Title",
description: "OG Description",
},
};
Best Practices
- Use Server Components by default, Client only when needed
- Handle loading states -
useQueryreturnsundefinedwhile loading - Colocate components - keep related files together
- Use TypeScript - never use
anytype - Implement error boundaries - graceful error handling