--- > "Next.js gives you the scaffolding — these practices determine whether you build a cathedral or a shack." Next.js has matured into the default choice for production React applications, and for good reason. But a framework's power is only as useful as the engineering decisions made around it. Across dozens of web projects, we've distilled the practices that separate maintainable, performant codebases from ones that collapse under their own weight. This is that list. --- ## 01 — Project Architecture: Structure Your Project for Scale from Day One The single biggest source of technical debt we see in Next.js projects is an unplanned folder structure. When you start with a clear architecture, refactoring later becomes a choice rather than a necessity. ### Recommended Layout ``` src/ ├── app/ # App Router pages & layouts │ ├── (auth)/ # Route group — no URL segment │ ├── (marketing)/ │ └── api/ # API route handlers ├── components/ │ ├── ui/ # Primitives (Button, Input, Modal) │ └── features/ # Domain-level components ├── lib/ # Utilities, constants, helpers ├── server/ # Server-only code, data fetchers ├── hooks/ # Custom React hooks └── types/ # TypeScript types & interfaces ``` > **Key Principle:** Use Next.js Route Groups `(folder)` to co-locate layouts, loading states, and error boundaries without polluting your URL structure. - Keep `server/` strictly for server-side code — never import it into client components - Co-locate component tests, stories, and styles in the same folder as the component - Prefer barrel files (`index.ts`) only at the feature level, not the component level - Use path aliases (`@/components`, `@/lib`) configured via `tsconfig.json` --- ## 02 — Rendering Strategy: Choose Your Rendering Pattern Intentionally Next.js App Router gives you multiple rendering options. Using the wrong one for a given page is one of the most common — and most impactful — mistakes we see. | Strategy | Best For | Characteristic | |---|---|---| | **Static (SSG)** | Marketing pages, blog posts, docs | Build-time generation, CDN-cached, fastest TTFB | | **ISR** | Product listings, news feeds | Revalidate on a schedule or on-demand | | **Dynamic SSR** | User dashboards, personalised pages | Per-request rendering with access to cookies & headers | | **Client-Side** | Real-time widgets, highly interactive UI | Use sparingly — offloads work to the user's device | ### ISR with On-Demand Revalidation ```typescript // app/products/[slug]/page.tsx export async function generateStaticParams() { const products = await fetchAllProducts(); return products.map((p) => ({ slug: p.slug })); } export const revalidate = 3600; // 1 hour fallback export default async function ProductPage({ params, }: { params: { slug: string }; }) { const product = await fetchProduct(params.slug); return ; } ``` --- ## 03 — Server Components: Embrace the Server Component Model React Server Components let you run server-side code directly inside your component tree — no API route needed, no client-side waterfall, no `useEffect` data-fetching. ### The Golden Rule Default every component to a Server Component. Only add `"use client"` when you need interactivity (event handlers, state, browser APIs). Push the `"use client"` boundary as far down the component tree as possible. ```typescript // ❌ Wrong: entire page is client-rendered "use client" export default function DashboardPage() { /* ... */ } // ✅ Right: only the interactive part is a client component // app/dashboard/page.tsx (Server Component) import { UserStats } from "./UserStats"; // server import { ActivityFeed } from "./ActivityFeed"; // server import { FilterBar } from "./FilterBar"; // client ✓ export default async function DashboardPage() { const user = await getUser(); // direct DB call return (

{/* client island */}

); } ``` > **Watch Out:** Never pass non-serializable values (functions, class instances, Date objects) from Server Components to Client Components via props. Only plain JSON-serializable data crosses the boundary safely. --- ## 04 — Data Fetching: Fetch Data at the Right Level, Cache Intelligently Next.js extends the native `fetch` API with built-in caching and revalidation. Use it — don't fight it. ```typescript // lib/data.ts — centralise your fetchers import { cache } from "react"; // cache() deduplicates calls within a single render pass export const getUser = cache(async (id: string) => { const res = await fetch(`/api/users/${id}`, { next: { tags: [`user-${id}`], revalidate: 300 }, }); if (!res.ok) throw new Error("User not found"); return res.json(); }); // On-demand revalidation in a Server Action "use server" import { revalidateTag } from "next/cache"; export async function updateUser(id: string, data: UserInput) { await db.user.update({ where: { id }, data }); revalidateTag(`user-${id}`); // purge cache instantly } ``` - Parallel-fetch independent data with `Promise.all()` — never await sequentially when not needed - Use `React.cache()` to deduplicate fetches across a single server render - Tag your fetches for precise on-demand invalidation via `revalidateTag()` - Prefer Server Actions over traditional API routes for mutations from forms --- ## 05 — TypeScript: Treat It as a Design Tool, Not a Tax Projects that lean fully into TypeScript — strict mode, typed route params, typed Server Action return values — ship with dramatically fewer runtime errors. ### Strict Configuration ```json { "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true, "exactOptionalPropertyTypes": true, "noImplicitOverride": true, "paths": { "@/*": ["./src/*"] } } } ``` ### Typed Server Actions with Zod ```typescript "use server" import { z } from "zod"; const ContactSchema = z.object({ name: z.string().min(2), email: z.string().email(), message: z.string().min(10), }); type ActionResult = | { success: true } | { success: false; error: string }; export async function submitContact( _prev: ActionResult, formData: FormData ): Promise { const parsed = ContactSchema.safeParse({ name: formData.get("name"), email: formData.get("email"), message: formData.get("message"), }); if (!parsed.success) return { success: false, error: parsed.error.message }; await sendEmail(parsed.data); return { success: true }; } ``` --- ## 06 — Performance: Ship It as a Feature Next.js automates a lot of optimisation, but you still need to make deliberate choices. ### Images Always use `next/image`. It handles WebP conversion, responsive srcsets, and lazy loading automatically. Never use a raw `` tag for content images. ```typescript import Image from "next/image"; // For images above the fold — set priority Hero banner

// For fill layouts in containers with unknown dimensions

``` ### Fonts Use `next/font` with `display: "swap"` and `preload: true`. It zero-layout-shift-loads fonts by inlining font-face declarations and preloading the files — no external font requests at runtime. ### Bundle Analysis - Run `@next/bundle-analyzer` before every major release - Dynamic import heavy components: `const Chart = dynamic(() => import('./Chart'), { ssr: false })` - Avoid importing entire libraries — use named imports and rely on tree-shaking - Set `modularizeImports` in `next.config.js` for icon and component libraries --- ## 07 — Security: Can't Be an Afterthought ### Security Headers ```javascript // next.config.js const securityHeaders = [ { key: "X-Content-Type-Options", value: "nosniff" }, { key: "X-Frame-Options", value: "DENY" }, { key: "X-XSS-Protection", value: "1; mode=block" }, { key: "Content-Security-Policy", value: [ "default-src 'self'", "script-src 'self' 'unsafe-inline'", // tighten in prod "img-src 'self' data: https:", ].join(";"), }, ]; module.exports = { headers: async () => [{ source: "/(.*)", headers: securityHeaders, }], }; ``` - Validate and sanitise all inputs server-side with Zod on every Server Action and API route - Use environment variable validation with `@t3-oss/env-nextjs` at startup - Never expose secrets — anything prefixed `NEXT_PUBLIC_` is bundled into client JS - Implement rate limiting on API routes using middleware + a key-value store (e.g. Upstash) --- ## 08 — Testing & Quality: Ship Confidence, Not Just Code A Next.js project without a testing strategy is a Next.js project that will eventually be rewritten. | Tool | Role | |---|---| | **Vitest + RTL** | Unit and integration tests for components and utilities | | **Playwright** | End-to-end tests for critical user journeys, run in CI against preview deployments | | **Storybook** | Component documentation and visual regression testing | > **Our Testing Rule:** Write integration tests that cover user behaviour, not implementation details. Test that "a logged-in user can submit the contact form and see a success message" — not that a specific function was called with specific arguments. --- ## 09 — Developer Experience: A Great DX Is Part of the Product ### Tooling Baseline - **ESLint** with `eslint-config-next` + `eslint-plugin-unicorn` for opinionated code quality - **Prettier** with `prettier-plugin-tailwindcss` for consistent formatting - **Husky** + **lint-staged** to run linting and type-checking on every commit - **Conventional Commits** enforced by `commitlint` for a meaningful git history ### Validated Environment Variables ```typescript // env.ts — fail fast at startup if vars are missing import { createEnv } from "@t3-oss/env-nextjs"; import { z } from "zod"; export const env = createEnv({ server: { DATABASE_URL: z.string().url(), AUTH_SECRET: z.string().min(32), }, client: { NEXT_PUBLIC_SITE_URL: z.string().url(), }, runtimeEnv: { DATABASE_URL: process.env.DATABASE_URL, AUTH_SECRET: process.env.AUTH_SECRET, NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL, }, }); ``` --- ## Closing Thoughts Next.js removes enormous amounts of boilerplate and infrastructure complexity. But every senior engineer we've worked with has landed on the same conclusion: the framework gets you 40% of the way there. The other 60% is the architecture decisions you make on top of it. Follow these practices not as rigid rules but as a map. Every project has unique constraints. What matters is that each trade-off is a deliberate decision — not a default you fell into. We're always iterating on this list at Neolatika as the ecosystem evolves. If you have a practice that's served you well, we'd love to hear about it. --- *Want to go deeper? We offer technical audits, architecture consulting, and team workshops tailored to Next.js projects. Reach us at **hello@neolatika.com**.*

Building Web Projects the Right Way with Next.js