next.js 13

April 18, 2023

next.js app router 已稳定！
过时警告：以下内容根据 beta 版编写！
TODO：待修正

see docs here

Installation

npx create-next-app@latest --experimental-app

# 默认选项如下
√ What is your project named? ... nextjs-test
√ Would you like to use TypeScript with this project? ... No / [Yes]
√ Would you like to use ESLint with this project? ... [No] / Yes
√ Would you like to use Tailwind CSS with this project? ... No / [Yes]
√ Would you like to use `src/` directory with this project? ... [No] / Yes
√ What import alias would you like configured? ... @/*

vscode 插件

Routing

文件约定

.js, .jsx, 和 .tsx 后缀均可，下面以 .js 为例

layout.js
layout 是不同页面之间的共享 UI。在导航时，layout 会保留 state，仍然可以交互，因为其不会重新渲染。

// app目录下的根layout.js如下
export const metadata = {
    title: "Create Next App",
    description: "Generated by create next app",
};

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

template.js 与 layout.js 类似，但在其子页面中导航时，会重新挂载 React 实例（因此不会保存 state）

page.js
Create the unique UI of a route and make the path publicly accessible.

// app目录下的根page.js如下
import Image from "next/image";
import Link from "next/link";
import { Inter } from "next/font/google";
const inter = Inter({ subsets: ["latin"] });

export default function Home() {
    return (
        <main className="flex min-h-screen flex-col items-center justify-between p-24">
            <Image
                className="relative dark:drop-shadow-[0_0_0.3rem_#ffffff70] dark:invert"
                src="/next.svg"
                alt="Next.js Logo"
                width={180}
                height={37}
                priority
            />
            <Link href="/docs">
                <h2 className={`${inter.className} mb-3 text-2xl font-semibold`}>
                    Docs{" "}
                    <span className="inline-block transition-transform group-hover:translate-x-1 motion-reduce:transform-none">
                        -&gt;
                    </span>
                </h2>
            </Link>
        </main>
    );
}

还可以通过 useRouter hook 导航，参见：https://beta.nextjs.org/docs/api-reference/use-router

一个典型的 page.js 如下

// app/blog/[slug]/page.tsx
"use client";
export default function Page({
    params,
    searchParams, // searchParams是动态API，使用searchParams将会导致动态渲染！
}: {
    params: { slug: string },
    searchParams: { [key: string]: string | string[] | undefined },
}) {
    return <h1>My Page</h1>;
}
// e.g.
// /blog/test?a=1
//  params = { slug: 'test' }
//  searchParams = { a: '1' }

还可以通过 useSearchParams 获取 searchParams，参见：https://beta.nextjs.org/docs/api-reference/use-search-params

其余内容参见：https://beta.nextjs.org/docs/routing/fundamentals#file-conventions

路由

一个目录下如存在 page.js 即成为路由的一部分，反之若不存在则不会成为路由

路由分组

可以给每个路由分组目录（(groupname)）下添加 layout.js，这样就可以作用到这组路由（而不影响生成的路径）

可以给每一组路由下使用自己的 layout.js，从而在每一组下应用自己的根路由（删除 app/layout.js 根路由，因为已经不需要了），此时注意每组的根路由是需要 <html> 和 <body> 标签的（就像 app/layout.js 一样）
注意：在这样的多根 layout 之间的页面导航会导致网页的重新加载

动态路由段

// app/blog/[slug]/page.js
export default function Page({ params }) {
    return <div>My Post</div>;
}

// e.g.
// /blog/a  ->  params = { slug: 'a' }
// /blog/b  ->  params = { slug: 'b' }

// e.g.
// app/[categoryId]/[itemId]/page.js
// type param = { categoryId: string, itemId: string }

可以像这样捕获所有路由段

// app/shop/[...slug]/page.js
export default function Page({ params }) {
    return <div>My Post</div>;
}

// e.g.
// /blog/a    ->  params = { slug: ['a'] }
// /blog/a/b  ->  params = { slug: ['a', 'b'] }

可选捕获所有路由段

// app/shop/[[...slug]]/page.js

// e.g.
// /shop      ->  params = {}
// /shop/a    ->  params = { slug: ['a'] }
// /shop/a/b  ->  params = { slug: ['a', 'b'] }

Rendering

Server Components 与 Client Components

app 目录默认渲染 Server Components
在一个组件的顶行使用 "use client" 指令即可声明为 Client Components
Client Components 下导入的所有组件自动成为 Client Components，因此无需 "use client" 指令
Client Components 不能导入（import） Server Components，但可以将 Server Components 作为 Client Components 的子节点（children）

Server Components 传给其 Client Components 子节点的 props 必须能够被序列化（因此不能传函数等）

有的组件既能在服务端渲染，又能在客户端渲染（但为了避免安全问题），要使之仅在服务端渲染，先安装 npm install server-only

// lib/data.js
import "server-only";

export async function getData() {
    let resp = await fetch("https://external-service.com/data", {
        headers: {
            authorization: process.env.API_KEY,
        },
    });
    return resp.json();
}
// 通过这样，Client Component在导入此模块时将抛出编译错误，提示此模块仅能在Server Components导入

第三方包提供的 Client Components 可能不含 "use client" 指令，因此在 Server Components 中导入这样的组件将导致编译错误，因为 nextjs 不知道这是 Client Components（默认当作 Server Components）
nextjs 文档中建议这样做：

// app/carousel.js
"use client";
import { AcmeCarousel } from "acme-carousel";
export default AcmeCarousel;

在 Server Components 导入包装后的 Client Components 将不再导致编译错误

context

由于 Server Components 是静态的，所以其自身不能创建或消费 context

参见：https://beta.nextjs.org/docs/rendering/server-and-client-components#context

静态渲染和动态渲染

参见：https://beta.nextjs.org/docs/rendering/static-and-dynamic-rendering

edge & node.js runtime

参见：https://beta.nextjs.org/docs/rendering/edge-and-nodejs-runtimes

Data fetching

鉴于 react 对异步的支持（first-class-support-for-promises）未稳定，此处就直接贴出文档：https://beta.nextjs.org/docs/data-fetching/fundamentals

生成静态 Params

tsx

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
    const posts = await fetch("https://.../posts").then((res) => res.json());

    return posts.map((post) => ({
        slug: post.slug,
    }));
}

generateStaticParams API Reference

Route Handlers

Route Handlers (route.js) allow you to create custom request handlers for a given route using the Web Request and Response APIs.
（仅在新的 app 文件夹内有效，相当于 pages 文件夹内的 API Routes (注: 其扩展了 nodejs 的 http 模块的 req,res )）
（route.js 与 page.js 不能共存与同一目录(路由)，因为这两种文件都能完全接管路由）

// app/api/route.ts

// supported_http_methods: GET, POST, PUT, PATCH, DELETE, HEAD
export async function GET(request: Request) {
    const { searchParams } = new URL(request.url);
    const id = searchParams.get("id");
    return Response.json({ id });
}

Next.js extends native Request and Response with NextRequest and NextResponse to provide convenient helpers for advanced use cases.

// app/rss.xml/route.ts

// 当Router Handler函数是 GET 且不带任何参数，例如不是这样： GET(request: Request)
// 且没有使用 cookies 和 headers 等动态API函数时，该 handler 将被静态求值
export async function GET() {
    return new Response(`<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">

<channel>
  <title>Next.js Documentation</title>
  <link>https://nextjs.org/docs</link>
  <description>The React Framework for the Web</description>
</channel>

</rss>`);
}

动态 API 函数，参见：https://beta.nextjs.org/docs/routing/route-handlers#dynamic-functions

下面是演示：

// app/api/route.ts
import { NextResponse } from "next/server";
import { cookies, headers } from "next/headers";
import { redirect } from "next/navigation";

export async function GET(request: Request) {
    const headersList = headers();
    const referer = headersList.get("referer");

    const cookieStore = cookies();
    const token = cookieStore.get("token");

    const res = await fetch("https://data.mongodb-api.com/...", {
        next: { revalidate: 60 }, // Revalidate every 60 seconds
    });
    const data = await res.json();

    if (!referer.startsWith("https://example.net")) {
        redirect("https://nextjs.org/");
    } else {
        return new NextResponse(JSON.stringify({ data }), {
            status: 200,
            headers: { "Set-Cookie": `token=${token}` },
        });
    }
}

export const revalidate = 60; // false | 'force-cache' | 0 | number
// Route Segment Config Options
// 参见：https://beta.nextjs.org/docs/api-reference/segment-config

动态路由段 (for Route Handlers)

// app/items/[slug]/route.ts
//prettier-ignore
export async function GET(request: Request, { params }: {
  params: { slug: string }
}) {
  const slug = params.slug; // 'a', 'b', or 'c'
}
// e.g.
// /items/a -> { slug: 'a' }
// /items/b -> { slug: 'b' }

暂不支持使用 generateStaticParams()

流式响应

// app/api/route.ts
// https://developer.mozilla.org/docs/Web/API/ReadableStream#convert_async_iterator_to_stream
function iteratorToStream(iterator: any) {
    return new ReadableStream({
        async pull(controller) {
            const { value, done } = await iterator.next();

            if (done) {
                controller.close();
            } else {
                controller.enqueue(value);
            }
        },
    });
}

function sleep(time: number) {
    return new Promise((resolve) => {
        setTimeout(resolve, time);
    });
}

const encoder = new TextEncoder();

async function* makeIterator() {
    yield encoder.encode("<p>One</p>");
    await sleep(200);
    yield encoder.encode("<p>Two</p>");
    await sleep(200);
    yield encoder.encode("<p>Three</p>");
}

export async function GET() {
    const iterator = makeIterator();
    const stream = iteratorToStream(iterator);

    return new Response(stream);
}