Project structure · Frontend
Next.js (App Router) project structure
Opens with creditsFor React developers building a real web front end with Next.js: a shop dashboard with public pages, sign-in, orders and products, talking to a separate backend API. The app folder holds routes only, product code lives in feature folders, server-only code sits in src/server, and the browser side gets a proper React setup: providers, TanStack Query, forms with React Hook Form and Zod, and tests from unit to end-to-end.
Curated by Tauseef FayyazIntermediate236 files and foldersNext.js 16.4, React 19.3, TypeScript 5Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you26 files and folders
- 2GrowingWhat a real app with features and tests adds+129 files and folders
- ProductionWhat running it for real users adds+36 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+45 files and foldersOpens with credits
How it is organised
- The app folder is for routing: pages, layouts, loading, error and not-found files, route handlers. Product code lives outside it in src/features, src/components and src/lib.
- Group product code by feature (features/orders, features/products) rather than by file type. A feature owns its components, hooks, queries, actions, schema and tests, so one change touches one folder. Features never import each other; shared code moves to components or lib.
- Server first: components are Server Components unless they need state, effects or browser APIs. Add "use client" only to the small leaf that needs it. Wrapping the tree in a client providers.tsx does not turn its children into client code.
- Two homes for non-UI code: src/server holds server-only modules (secrets, the backend client, the session) and each starts with import "server-only"; src/lib holds code that is safe in the browser. The build fails if a Client Component imports src/server.
- Server state comes from the backend: Server Components fetch the first render, TanStack Query handles live and interactive data in the browser. Zustand is only for small UI state such as a collapsed sidebar, never for copies of server data.
- Route groups (marketing), (auth) and (app) give each part of the site its own layout without changing the URL.
- Tests grow in layers: Vitest for rules and components at Growing, Playwright journeys at Production, then contract, visual, accessibility and load tests when a team and real traffic justify them.
- Next.js does not force a layout. The docs show several valid strategies; this tree keeps code under src/ (the --src-dir flag) so the root holds only configuration, the same as the full stack tree.
At the top of the project
Open one in the explorer for the full story
- my-app/
- .git/The Git repository. create-next-app runs git init and makes a first commit for you.
- .husky/Git hooks managed by husky: checks that run on your machine before a commit.2 inside
- .next/Build output and dev cache written by next dev and next build.
- .vscode/Shared editor settings for VS Code and Cursor users on the team.3 inside
- coverage/Coverage report written by vitest run --coverage.
- messages/Translation files for next-intl, one JSON file per language.2 inside
- node_modules/Installed packages. create-next-app runs the install for you.
- public/Static files served as-is from the site root: /logo.svg, /og.png.6 inside
- src/All application code, kept apart from configuration files at the root.12 inside
- .editorconfigIndent style, line endings and final newline for every editor.
- .env.exampleEvery environment variable the app needs, with safe placeholder values. Committed.
- .env.localYour local values: backend URL and secrets.
- .gitignoreKeeps node_modules, .next, coverage, env files and next-env.d.ts out of Git.
- .nvmrcPins the Node.js version for nvm, fnm, CI and many hosts.
- .prettierignoreFiles Prettier must not touch: build output, lock files, generated types, snapshots.
- .prettierrc.jsonPrettier settings plus prettier-plugin-tailwindcss, which sorts class names.
- AGENTS.mdInstructions for AI coding agents. create-next-app writes a Next.js rules block into it.
- CLAUDE.mdOne line, @AGENTS.md, so Claude Code reads the same rules as other agents.
- README.mdHow to run the project. The generated one only covers npm run dev.
- commitlint.config.mjsExtends @commitlint/config-conventional so commits read feat:, fix:, chore:.
- docker-compose.ymlRuns the backend API (and its database) locally from their published images.
- eslint.config.mjsESLint flat config with the Next.js Core Web Vitals and TypeScript rules.
- next-env.d.tsTypeScript declarations for Next.js, regenerated by next dev, next build and next typegen.
- next.config.tsNext.js configuration. The scaffold turns on Cache Components, Partial Prefetching and the Tailwind Turbopack loader.
- package-lock.jsonExact versions of every installed package, written by npm.
- package.jsonDependencies and scripts: dev, build, start, lint, then typecheck, tests and helpers you add.
- tsconfig.jsonTypeScript settings, with strict mode and the @/* alias pointing at src/*.
- vitest.config.mtsVitest config for unit and component tests: jsdom, tsconfig paths, setup file, coverage.
- vitest.setup.tsRuns before every test file: jest-dom matchers, MSW server, cleanup.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with Next.js (App Router).
- Roadmap· ReactFrontend development roadmapHTML, CSS, JavaScript and a framework
- Roadmap· Next.js and PostgreSQLFull stack development roadmapBuild and ship whole web apps
- Roadmap· PlaywrightQA and test automation roadmapManual testing to automated suites
- RoadmapDevOps and cloud roadmapLinux, Docker, Kubernetes, AWS
- Cheat sheetFrontend development cheat sheetHTML, CSS, JavaScript and a framework.
- Cheat sheetFull stack development cheat sheetBuild and ship whole web apps.
- Cheat sheetQA and test automation cheat sheetManual testing to automated suites.
- FYP idea· AdvancedOffline-First Point of Sale Web App for Multi-Till Retail ShopsA browser-based point of sale for grocery stores, bakeries and general retail shops that keeps selling during internet and power cuts, syncs several tills and a back office without losing or double counting stock, and issues valid receipt numbers offline. An advanced final year project in local-first web engineering.
- FYP idea· IntermediateApproval Workflow Engine with Escalations for Small OfficesAn approval workflow engine for small offices, schools and NGOs that turns purchase requests, leave, reimbursements and document sign-offs into tracked flows with deadlines, escalations and email or WhatsApp-style reminders. A no-code automation final year project with a durable workflow runtime and an audit trail.
See 10 moreShow fewer
- FYP idea· IntermediateUrdu and RTL Accessibility Linter for Nastaliq Web Pages and Government FormsBuild an automated checker that finds the accessibility and layout faults specific to Urdu web pages: missing language and direction attributes, Urdu text drawn as images, broken Nastaliq rendering, mirrored icons and forms that screen readers announce in the wrong language. General tools such as axe-core do not look for any of these. The result is a command-line tool, a browser extension and a public audit of real Pakistani websites.
- QuestionWhat should I learn to become a web developer, and in what order?Learn the web platform first (HTML, CSS, JavaScript, how HTTP works), then one frontend framework, then a backend with a database, and build a real project at each stage. If you already know WordPress, you are not starting over: your HTML, CSS and PHP experience transfers.
- QuestionHow do I learn to read a large codebase when I can handle small projects but get lost in real ones?Nobody reads a large codebase from top to bottom. You follow one real path through it, such as a single request or button click, from entry point to database and back. Map what you find, ignore everything off that path for now, and repeat with a different path. Understanding builds in layers, and a first small change teaches more than a week of reading.
- QuestionHow do I build a developer portfolio as a beginner with nothing to show?Start with two or three small but complete projects that solve a real problem, each with a clear README, screenshots and a live link or easy run steps. Put them on a simple one-page site or a tidy GitHub profile. Depth and finish matter far more than the number of projects or a fancy design.
- QuestionHow do I know if code written by an AI tool is actually correct?You check it the same way you check any code, but more carefully: read the whole diff, confirm every function and package exists, run it against tests that could fail, especially one you wrote yourself, try the edge cases, and make sure you can explain every line. Correct means proven by evidence, not "the tool said it works".
- Resource· GuideNext.js DocumentationThe official Next.js documentation covers the React framework's App Router and the older Pages Router: routing and layouts, server and client components, data fetching, caching (including Cache Components), server actions, route handlers, Proxy (formerly middleware), streaming, Turbopack and deployment. Next.js Learn teaches one app step by step; these docs are the reference to keep open once you build your own. It suits React developers building production apps with Next.js.
- Resource· CourseNext.js LearnNext.js Learn is Vercel's free official course platform. Its main course builds a full-stack financial dashboard in 16 chapters, covering styling, fonts and images, layouts, navigation, a Postgres database, data fetching, static and dynamic rendering, streaming, search and pagination, mutations with server actions, error handling, accessibility, authentication and metadata. It suits React developers moving to Next.js and anyone confused about where server code ends and client code begins.
- Resource· GuideReact DocumentationThe official React documentation at react.dev is a full course as well as a reference. Its Learn track moves from a quick start through describing the UI, adding interactivity, managing state and escape hatches, with interactive sandboxes and challenges on nearly every page. It suits anyone learning React and any React developer whose habits come from older class-based tutorials, and it should be read before paying for a React course.
- Resource· GuideThe TypeScript HandbookThe TypeScript Handbook is the official, free guide to TypeScript's type system from the TypeScript team, written for working programmers and kept current with each release. It covers everyday types, narrowing, functions, object types, generics, type manipulation, classes and modules, and it is designed to be read in a few hours. It suits JavaScript developers adopting TypeScript and anyone who writes types by copying patterns without understanding them.
- Resource· GuidePlaywright DocumentationThe official documentation for Playwright, Microsoft's open-source framework for end-to-end testing in real Chromium, Firefox and WebKit browsers, with mobile emulation. It walks you from installation to your first test, then covers locators, assertions, fixtures, authentication, API testing, parallel runs and CI. Tools such as the code generator, UI mode and trace viewer make first tests easy. It suits developers and QA engineers adding reliable browser tests to a web app.
Checked against 21 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- Next.js docs: Installation (create-next-app defaults)
- Next.js docs: Project structure and organization
- Next.js docs: proxy.js
- Next.js docs: Data security
- Next.js docs: Forms and Server Actions
- Next.js docs: Content Security Policy
- Next.js docs: Internationalization
- Next.js docs: Environment variables
- Next.js docs: Self-hosting
- Next.js docs: Vitest
- Next.js docs: Playwright
- Next.js docs: Instrumentation
- Next.js docs: CI build caching
- TanStack Query: Advanced server rendering
- React Hook Form: schema validation
- Mock Service Worker docs
- Storybook for Next.js (Vite)
- next-intl: App Router without i18n routing
- Flags SDK
- Next.js with-docker example
- create-next-app templates (source)
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- React Best PracticesModern React best practices for 2026: pure components, lean state, fewer effects, React Compiler, form actions, accessibility and testing.
- Modern CSS Best PracticesModern CSS best practices: cascade layers, low specificity, custom properties, Grid and Flexbox layout, responsive design, container queries, :has() and nesting, plus Tailwind CSS v4 tips.
- TypeScript Best PracticesModern TypeScript best practices for 2026: strict settings, TypeScript 7, modeling data with unions, safe narrowing, runtime validation, generics and typed linting.
Checklists
See all- Web Accessibility ChecklistA practical web accessibility checklist built on WCAG 2.2 level AA, with a severity and a concrete way to verify every check.
- Web Performance ChecklistA practical web performance checklist built on Core Web Vitals: LCP, INP and CLS, with a severity and a concrete way to verify every check.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com