gpolanco/skills-as-context

Overview

This skill enforces Next.js App Router patterns and conventions across routing, caching, middleware, Server Actions, and metadata to keep projects consistent and secure. It codifies required files, prevents App Router anti-patterns, and guides data flow (Action → Service → Repository) and caching defaults. Use it as the authoritative checklist when creating or reviewing Next.js routes and server logic.

How this skill works

The skill inspects the app/ directory and project root for required files (layout.tsx, page.tsx, loading.tsx, error.tsx, middleware.ts, etc.), validates routing structure and dynamic segments, and checks use of App Router APIs. It flags forbidden patterns (Pages Router APIs, router.push for mutations, route handlers for internal mutations), enforces input validation with Zod in Server Actions, and verifies metadata, image/font usage, and cache/revalidation settings. It also highlights where to read deeper references for Server Actions, routing, and architecture decisions.

When to use it

• When adding new routes, dynamic segments, or nested layouts with the App Router
• When creating Server Actions, modifying data flow, or handling internal mutations
• When configuring caching, ISR, or on-demand revalidation for fetched data
• When implementing middleware for auth/session handling or path matching
• When creating public APIs or webhooks that require Route Handlers
• When adding dynamic SEO via generateMetadata() or optimizing images/fonts

Best practices

• Always use the App Router for new pages; never use Pages Router APIs like getServerSideProps
• Follow Action → Service → Repository flow for Server Actions and return ApiResponse<T> (avoid throwing)
• Validate every Action input with Zod, including ID and env var validation at build time
• Provide loading.tsx and error.tsx at each major route segment and export generateMetadata() for dynamic SEO
• Default to static generation; opt into dynamic with cache: 'no-store' and use next.fetch revalidate options
• Use Route Handlers only for external webhooks or public third-party APIs; use Server Actions for internal mutations

Example use cases

• Reviewing a pull request that adds a new nested dashboard route with dynamic [id] segment
• Implementing a Server Action that updates a record: ensure Zod validation, ApiResponse<T>, and revalidatePath call
• Adding Stripe webhook endpoint under app/api/webhooks/stripe/route.ts with signature verification
• Setting up middleware.ts to guard /dashboard paths and redirect unauthenticated users to /login
• Converting legacy Pages Router code to App Router patterns and replacing getServerSideProps usage