← Instructions

Neexo Next.js Conventions

Shared App Router, React 19, TypeScript, UI, and validation conventions for Neexo's Next.js 16 projects.

AuthorNeexoCore
Sourcegithub.com/NeexoCore/awesome-neexo
Apply to**/*.{ts,tsx}, **/app/**/*.tsx
Updated
nextjsreacttypescript

Overview

Neexo projects default to Next.js 16 App Router patterns, server components, narrow TypeScript boundaries, and existing local UI conventions.

Server vs Client Components

  • Prefer server components unless hooks, browser APIs, or event handlers require client components
  • Keep server/client boundaries explicit — mark client components with "use client" at the top
  • Use server actions for mutations; do not create API routes for simple form submissions

Next.js 16 Specifics

  • params and searchParams are now async in route components — always await them: 
    export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
}
  • cookies() and headers() from next/headers are async — await before reading
  • Turbopack is the default bundler in development — do not add Webpack-specific config unless required for production
  • Use the use hook from React 19 to unwrap promises in client components
  • Use "use cache" for fine-grained caching instead of relying solely on route segment config

TypeScript and Code Style

  • Avoid any unless justified at an integration boundary
  • Reuse existing components, hooks, utilities, and design tokens
  • Add dependencies only when the existing stack cannot reasonably solve the problem
  • Prefer satisfies for type narrowing of config objects

Patterns to Avoid

  • Do not use getServerSideProps or getStaticProps — these are Pages Router patterns
  • Do not wrap server components in unnecessary client wrappers
  • Do not use useEffect for data fetching — fetch in server components or use server actions

Raw content

Copy this into your project — e.g. .instructions.md, .agent.md, or SKILL.md

## Overview

Neexo projects default to Next.js 16 App Router patterns, server components, narrow TypeScript boundaries, and existing local UI conventions.

## Server vs Client Components

- Prefer server components unless hooks, browser APIs, or event handlers require client components
- Keep server/client boundaries explicit — mark client components with `"use client"` at the top
- Use server actions for mutations; do not create API routes for simple form submissions

## Next.js 16 Specifics

- `params` and `searchParams` are now async in route components — always `await` them:
  ```tsx
  export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
    const { slug } = await params
  }
  ```
- `cookies()` and `headers()` from `next/headers` are async — `await` before reading
- Turbopack is the default bundler in development — do not add Webpack-specific config unless required for production
- Use the `use` hook from React 19 to unwrap promises in client components
- Use `"use cache"` for fine-grained caching instead of relying solely on route segment config

## TypeScript and Code Style

- Avoid `any` unless justified at an integration boundary
- Reuse existing components, hooks, utilities, and design tokens
- Add dependencies only when the existing stack cannot reasonably solve the problem
- Prefer `satisfies` for type narrowing of config objects

## Patterns to Avoid

- Do not use `getServerSideProps` or `getStaticProps` — these are Pages Router patterns
- Do not wrap server components in unnecessary client wrappers
- Do not use `useEffect` for data fetching — fetch in server components or use server actions