Project structure · Full stack
Next.js full stack (database and auth) project structure
Opens with creditsOne Next.js app that is both your frontend and your backend: pages render on the server, forms call Server Actions, and Route Handlers serve the few real HTTP endpoints (auth, webhooks, jobs, health). PostgreSQL through Prisma ORM, sign-in through Better Auth, background jobs with Inngest, and every database read goes through a small Data Access Layer that checks who is asking. The example features are invoices and clients for freelancers.
Curated by Tauseef FayyazIntermediate258 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+143 files and folders
- ProductionWhat running it for real users adds+46 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+43 files and foldersOpens with credits
How it is organised
- src/app is for routing only: page, layout, loading, error and route files. The real code for a feature lives in src/features/<feature>, so the URL tree stays easy to read.
- Server first. Pages are Server Components that read data through the Data Access Layer; only interactive pieces are Client Components. Forms call Server Actions instead of hand-written API routes.
- Route Handlers (route.ts) are only for real HTTP endpoints: the auth handler, payment webhooks, the background job endpoint, health checks, and a versioned API if a mobile app needs one.
- All data access goes through a Data Access Layer: server-only functions that check the session, filter by owner and return only the fields a page needs. proxy.ts can redirect early, but it is never the security check.
- Same split as the frontend tree: src/server holds server-only modules (database, auth, env, logger, jobs, rate limits), each importing "server-only"; src/lib holds code that is safe in the browser.
- Group by feature (invoices, clients), and features never import each other. If invoices needs a client name, it reads it in its own query.
- Prisma ORM over Drizzle here because its schema file and migrations are the easiest to read when you are learning. Drizzle (schema in TypeScript, closer to SQL) is an equally good choice; only prisma/ and src/server/db.ts would change.
- Tests grow in layers: Vitest unit and component tests at Growing, integration tests against a real Postgres in a throwaway container plus Playwright journeys at Production, then contract, visual, accessibility and load tests at Expert.
At the top of the project
Open one in the explorer for the full story
- my-app/
- .git/Git history. create-next-app runs git init and makes the first commit for you.
- .devcontainer/A Dev Container: Node 24 and Postgres ready in VS Code or GitHub Codespaces.1 inside
- .husky/Git hooks managed by husky, created by npx husky init.2 inside
- .next/Build output and dev server cache, written by next dev and next build.
- .vscode/Shared editor settings for the team.3 inside
- coverage/Coverage report from vitest run --coverage.
- node_modules/Installed packages.
- prisma/The database schema, its migration history and the seed script.3 inside
- public/Static files served from the site root, like /next.svg.6 inside
- src/All application code, kept apart from config files at the root.11 inside
- .editorconfigIndentation, line endings and final newline for every editor.
- .envLocal values for DATABASE_URL and the auth secret and URL. Never committed.
- .env.exampleEvery variable the app needs, with placeholders. The one env file you commit.
- .gitignoreIgnores node_modules, .next, coverage, .env* files, next-env.d.ts and build info.
- .nvmrcPins Node.js 24 LTS for laptops, CI and Docker.
- .prettierignoreFiles Prettier skips: build output, lock files, src/generated, migrations, snapshots.
- .prettierrc.jsonPrettier settings with prettier-plugin-tailwindcss.
- AGENTS.mdInstructions for AI coding agents, generated by create-next-app.
- CLAUDE.mdA one-line file you add, @AGENTS.md, so Claude Code reads the same rules.
- README.mdStarts as the create-next-app readme. Rewrite it for your app.
- commitlint.config.mjsExtends @commitlint/config-conventional.
- docker-compose.ymlRuns PostgreSQL (and optionally a local mail catcher) with docker compose up -d.
- eslint.config.mjsESLint flat config using the Next.js Core Web Vitals and TypeScript rule sets.
- next-env.d.tsTypeScript declarations Next.js writes for itself.
- next.config.tsNext.js settings. The scaffold turns on Cache Components and wires Tailwind into Turbopack.
- package-lock.jsonExact versions of every installed package.
- package.jsonDependencies and scripts: dev, build, start, lint, then typecheck, tests and db helpers.
- prisma.config.tsPrisma CLI settings: schema and migrations paths, the database URL and the seed command.
- tsconfig.jsonTypeScript settings, including the @/* alias that points at src/*.
- vitest.config.mtsVitest projects: "unit" (jsdom, MSW) at Growing, "integration" (node, real Postgres) added at Production.
- vitest.setup.tsUnit project setup: jest-dom matchers, the MSW server, cleanup.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with Next.js full stack (database and auth).
- Roadmap· Next.js and PostgreSQLFull stack development roadmapBuild and ship whole web apps
- Roadmap· ReactFrontend development roadmapHTML, CSS, JavaScript and a framework
- Roadmap· PostgreSQLSQL and databases roadmapQueries, design, indexes, transactions
- Roadmap· PlaywrightQA and test automation roadmapManual testing to automated suites
- Cheat sheetFull stack development cheat sheetBuild and ship whole web apps.
- Cheat sheetSQL and databases cheat sheetQueries, design, indexes, transactions.
- Cheat sheetFrontend development cheat sheetHTML, CSS, JavaScript and a framework.
- Cheat sheetQA and test automation cheat sheetManual testing to automated suites.
- FYP idea· BeginnerForm Backend Service for Static Sites with Spam FilteringA developer-facing web service that gives static and no-code websites a form endpoint: submissions are stored, filtered for spam, emailed to the owner and sent to webhooks, with a dashboard and CSV export. A beginner-friendly final year project in backend development with a clear SaaS model.
See 11 moreShow fewer
- FYP idea· IntermediatePharmacy Stock Ledger with Batch Expiry and FEFO DispensingA web-based stock ledger and billing counter for independent pharmacies that tracks every medicine by batch and expiry, sells loose tablets from strips correctly, and dispenses first-expiry-first-out. A final year project in healthcare retail software with real inventory correctness problems to solve.
- FYP idea· BeginnerMasters Application and Scholarship Deadline PlannerA web app for students applying to masters programmes and scholarships abroad: add each application with its deadline, time zone, fees and documents, and the app works backwards to a week-by-week plan, flags clashes and tracks referees. A beginner final year project with real users in every graduating class.
- QuestionShould I learn TypeScript or Python first in 2026?Learn Python first if you are new to programming or drawn to data and AI. Learn TypeScript first only if you already know some JavaScript or are certain about web development, and even then learn plain JavaScript for a few weeks before the types. The second language is much easier than the first.
- 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.
- QuestionDo I need Docker and Kubernetes as a junior developer?Docker, yes: learn the basics, because nearly every team uses containers and you will be expected to run the project locally and read a Dockerfile. Kubernetes, mostly no: understand what it does and a few core terms, but deep Kubernetes can wait until your job or a DevOps direction needs it.
- QuestionWhich final year project will actually help me get a job?Pick an FYP that matches the role you want, solves a real problem for a real user, uses the tools that role uses, and that your group can finish and deploy. A modest idea done properly, with clean code, tests and a clear demo, helps far more in interviews than an ambitious idea that never fully 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· GuidePrisma DocumentationThe official documentation for Prisma ORM, the TypeScript ORM for Node.js, and for Prisma's hosted services such as Prisma Postgres. It covers schema modelling, migrations, type-safe queries, relations, Prisma Studio and deployment, with getting started guides for frameworks such as Next.js, NestJS, Nuxt and others. It suits TypeScript developers who want database access with strong typing, ideally after they understand SQL and relational modelling.
- Resource· GuidePostgreSQL DocumentationThe official PostgreSQL manual for the current release: a tutorial, the full SQL language reference, every data type and function, server administration, and chapters on indexes, EXPLAIN and concurrency control. It is accurate, well written and the place to check any PostgreSQL behaviour before trusting a blog post.
- 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.
- Resource· Cheat sheetOWASP Cheat Sheet SeriesThe OWASP Cheat Sheet Series is a free collection of short, expert-written guides on specific security tasks, such as authentication, session management, password storage, input validation, JSON Web Tokens, REST security, XSS and SQL injection prevention. It suits developers who need to implement something securely right now and want a concise list of what to do and which mistakes to avoid, rather than a textbook.
Checked against 20 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- Next.js: Installation (create-next-app defaults)
- Next.js: Project structure and organization
- Next.js: Authentication and the Data Access Layer
- Next.js: Data security
- Next.js: Server Actions security and configuration
- Next.js: Content Security Policy
- Next.js: proxy.ts file convention
- Next.js: Environment variables
- Next.js: Self-hosting
- Next.js: output standalone
- Next.js: AI coding agents (AGENTS.md)
- Better Auth: Next.js integration
- Better Auth: Prisma adapter
- Better Auth: Rate limit
- Prisma: Quickstart with PostgreSQL
- Prisma: Customizing migrations
- Inngest: Serving functions with Next.js
- Testcontainers for Node.js: PostgreSQL module
- Vitest: Test projects
- Docker Hub: official postgres image (PGDATA in 18+)
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- TypeScript Best PracticesModern TypeScript best practices for 2026: strict settings, TypeScript 7, modeling data with unions, safe narrowing, runtime validation, generics and typed linting.
- Next.js App Router Best PracticesNext.js 16 App Router best practices: Server Components, Cache Components and use cache, secure Server Actions, proxy.ts, metadata and images.
- React Best PracticesModern React best practices for 2026: pure components, lean state, fewer effects, React Compiler, form actions, accessibility and testing.
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.
- Web Application Security ChecklistA practical web application security checklist built on the OWASP Top 10:2025 and ASVS 5.0, with a severity and a 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