Ship-ready Next.js Starter Checklist

corepack enable
pnpm create next-app@latest
pnpm install
pnpm dev

我想为这个 Next.js + shadcn 项目确定 UI 组件边界：primitive 目录（monorepo 通常是 packages/ui，单应用通常是 src/components/ui）只存放与业务无关、可跨功能复用的组件。

更具体的客制化组件应在对应 feature 或页面附近引用 primitive 后二次封装。封装默认继承 primitive 的 props，只处理自身需要的属性，其余通过 ...props 透传，包括 className、ref、aria-*、data-* 和事件。

先不要更新。请先检查当前目录和已有组件，和我讨论：primitive 的实际目录映射、业务封装应该放在哪里、哪些属性必须由封装控制，以及是否存在合理例外。确认后再把最终约束写入项目文档并实施。

import type { ComponentProps } from "react";

import { Card } from "@/components/ui/card";
import { cn } from "@/lib/utils";

type ResultCardProps = ComponentProps<typeof Card> & {
  isSelected?: boolean;
};

export function ResultCard({
  className,
  isSelected = false,
  ...props
}: ResultCardProps) {
  return (
    <Card
      className={cn("transition-colors", className)}
      {...props}
      data-selected={isSelected || undefined}
    />
  );
}

我想为这个 Next.js App Router 项目确定 Loading 与 Streaming 边界。

先不要更新。请先检查 Next.js 版本、Cache Components 配置、App Router 路由树、已有 loading.tsx、runtime / uncached data access、真实异步数据边界，以及 notFound()、鉴权和授权的执行顺序。

逐个 page.tsx 评估导航是否存在真实等待成本；需要反馈时，确定最邻近且有意义的 route fallback，以及 application / feature 层页面 skeleton 的位置。再找出 cookies()、headers()、searchParams、params、uncached fetch 等读取发生在哪里，判断哪些慢模块确实能在页面 shell 可用时独立加载和 reveal，并把覆盖读取的最近有效 <Suspense> 放在实际等待的上方。

同步、静态、必须先完成鉴权或存在性检查的路径不要为了 skeleton 被人为拆分。受保护数据仍由 DAL 或数据访问旁的 guard 执行权威鉴权与授权，layout 里的检查只能用于非权威的乐观 UI。要求真实 redirect / 404 / HTTP status 时，如果不能在 fallback flush 前完成 guard，就不要添加同 segment 的 loading.tsx，只在 guard 通过后增加局部 Suspense。确认后，把最终约束写入 docs/frontend/loading-and-streaming.md 或等价长期文档，再实施。

// app/blog/loading.tsx
import { BlogPageSkeleton } from "@/components/blog/blog-page-skeleton";

export default function Loading() {
  return <BlogPageSkeleton />;
}

import { Suspense } from "react";

async function LatestPosts() {
  const response = await fetch("https://example.com/api/posts", {
    cache: "no-store",
  });

  if (!response.ok) {
    throw new Error("Failed to load latest posts");
  }

  const posts = await response.json();

  return <PostList posts={posts} />;
}

export function BlogOverview() {
  return (
    <Suspense fallback={<LatestPostsSkeleton />}>
      <LatestPosts />
    </Suspense>
  );
}

const tailwindColorLiteralPattern =
  // eslint-disable-next-line sonarjs/regex-complexity -- Mirrors the explicit Tailwind color policy matrix.
  /(?:bg|text|border|outline|ring|shadow|fill|stroke|from|via|to|decoration|caret|accent)-\[[^\]]*(?:#[0-9a-fA-F]{3,8}|(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color)\()/u;

const tailwindPalettePattern =
  // eslint-disable-next-line sonarjs/regex-complexity -- Mirrors the explicit Tailwind color policy matrix.
  /(?:^|[^A-Za-z0-9_-])(?:bg|text|border(?:-[trblxyse])?|outline|ring(?:-offset)?|shadow|drop-shadow|inset-shadow|inset-ring|fill|stroke|from|via|to|decoration|caret|accent|divide|placeholder)-(?:black|white|(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone|mauve|olive|mist|taupe)-(?:50|100|200|300|400|500|600|700|800|900|950))(?:\/[^\s"']+)?(?:[^A-Za-z0-9_/-]|$)/u;

const colorLiteralPattern =
  /(?:#[0-9a-fA-F]{3,8}|(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color)\()/u;

const colorStyleProperties = new Set([
  "background",
  "backgroundColor",
  "borderColor",
  "boxShadow",
  "color",
  "fill",
  "outlineColor",
  "stroke",
  "textShadow",
]);

const hasHardcodedTailwindColor = (value) =>
  tailwindColorLiteralPattern.test(value) || tailwindPalettePattern.test(value);

const getPropertyName = (node) => {
  if (node.key.type === "Identifier" && !node.computed) {
    return node.key.name;
  }

  if (node.key.type === "Literal" && typeof node.key.value === "string") {
    return node.key.value;
  }

  return null;
};

export const noColorLiteralsRule = {
  create: (context) => {
    const reportedNodes = new WeakSet();

    const reportColorLiteral = (node) => {
      if (reportedNodes.has(node)) {
        return;
      }

      reportedNodes.add(node);
      context.report({ messageId: "useSemanticColor", node });
    };

    const checkLiteral = (node) => {
      if (
        typeof node.value === "string" &&
        hasHardcodedTailwindColor(node.value)
      ) {
        reportColorLiteral(node);
      }
    };

    const checkProperty = (node) => {
      const propertyName = getPropertyName(node);
      const ownsColor =
        propertyName !== null &&
        (propertyName.startsWith("--") ||
          colorStyleProperties.has(propertyName));

      if (
        ownsColor &&
        node.value.type === "Literal" &&
        typeof node.value.value === "string" &&
        colorLiteralPattern.test(node.value.value)
      ) {
        reportColorLiteral(node.value);
      }
    };

    const checkTemplateElement = (node) => {
      if (hasHardcodedTailwindColor(node.value.raw)) {
        reportColorLiteral(node);
      }
    };

    return {
      Literal: checkLiteral,
      Property: checkProperty,
      TemplateElement: checkTemplateElement,
    };
  },
  meta: {
    messages: {
      useSemanticColor:
        "Use a semantic color token from the shared theme instead of a hardcoded color.",
    },
    schema: [],
    type: "problem",
  },
};

import { noColorLiteralsRule } from "./eslint/rules/no-color-literals.js";

const localPlugin = {
  rules: {
    "no-color-literals": noColorLiteralsRule,
  },
};

export default [
  {
    plugins: {
      local: localPlugin,
    },
    rules: {
      "local/no-color-literals": "error",
    },
  },
];

{
  "scripts": {
    "check": "ultracite check",
    "fix": "ultracite fix"
  }
}

npx skills add https://github.com/multicul-silver-wolf/agent-docs-system-skill --skill project-docs-system
npx skills add https://github.com/mattpocock/skills --skill ask-matt
npx skills add https://github.com/mattpocock/skills --skill grilling
npx skills add https://github.com/mattpocock/skills --skill domain-modeling
npx skills add https://github.com/mattpocock/skills --skill grill-with-docs
npx skills add https://github.com/mattpocock/skills --skill codebase-design
npx skills add https://github.com/mattpocock/skills --skill to-spec
npx skills add https://github.com/mattpocock/skills --skill to-tickets
npx skills add https://github.com/mattpocock/skills --skill implement
npx skills add https://github.com/mattpocock/skills --skill tdd
npx skills add https://github.com/mattpocock/skills --skill code-review
npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture

{
  "scripts": {
    "test": "vitest run"
  }
}

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm run check
      - run: pnpm test
      - run: pnpm run build