Next.js SaaS Folder Structure for TypeScript

AGENTS.md for Next.js: a practical template for coding agents

An AGENTS.md file should be a short operating contract for your coding agent: where code belongs, what not to touch casually, how to validate a change, and which existing patterns to copy. It is not a giant prompt, a substitute for review, or a guarantee that an agent will make correct changes.For a solo developer building a Next.js SaaS with an agent, the useful goal is simpler: make the safe, repeatable path obvious before the agent starts exploring. That reduces the odds of a small feature spreading business logic into pages, pulling provider SDKs into components, or skipping the checks that would expose a regression.This guide gives you a practical starting template, explains the sections that do real work, and shows how to keep the file honest as your application changes.What an AGENTS.md file should doRepository instructions are persistent project context. GitHub documents repository-wide and path-specific custom instructions, including AGENTS.md files for agent guidance; the closest file can take precedence when multiple instruction files exist. That makes placement and scope part of the design, not just a naming choice.For a Next.js SaaS, a good root file answers four questions before an agent edits anything:What is this project? Identify the framework, major boundaries, and the kind of product it is.Where does a change belong? Describe feature modules, shared code, routing, and infrastructure seams.What must remain protected? Name areas that need deliberate review, such as auth, payments, configuration, migrations, and provider adapters.How is a change proven? Give the commands and targeted checks that are appropriate for the repository.The file should reduce discovery cost. It should not claim that a test suite is comprehensive if it is not, promise production safety, or instruct an agent to bypass review for sensitive changes.The practical AGENTS.md templateStart with this template, then replace every bracketed item with facts verified in your repository. Delete any rule you cannot maintain. The point is a usable contract, not a long document.# Project Agent Contract## Project context[Product name] is a [framework and architecture] application for [user/job].Read the target module and nearby implementations before changing code.Prefer existing patterns over a new abstraction.## Architecture- Put product behavior in `src/features/<feature>/`.- Keep `app/` limited to routing, layouts, route handlers, and composition.- Do not import one feature directly from another feature.- Move code to `src/shared/` only when it is genuinely reused.- Access databases, payments, and AI providers through their existing adapters.## Change boundariesTreat these areas as protected infrastructure; change them only when the task requires it:- `src/lib/`- `src/config/`- `src/services/`- authentication, billing, webhook, and deployment configurationDo not expose secrets to client code. Keep provider SDKs out of UI components.## Implementation rules- Default to Server Components; add `"use client"` only for browser APIs or interactivity.- Preserve strict TypeScript; do not add `any` to escape a type error.- Validate inputs at server boundaries.- Return the project’s established result shape for expected action failures.- Reuse the repository’s UI primitives and accessibility conventions.## VerificationRun the checks relevant to the change:```bashnpm run lintnpm test -- --runInBandnpm run build```Before finishing, review the diff, preserve unrelated local changes, and statewhich checks ran and which did not.The commands above are deliberately examples. If your project uses Playwright, a package workspace command, a database emulator, or a different test runner, record the exact command that contributors can actually run. A validation section that always fails will quickly be ignored.Why the architecture section matters mostCoding agents can generate a route, form, or component quickly. The more expensive failure is a feature that looks correct in isolation but bypasses the application’s boundaries. For example, a client component that reaches directly into a database SDK creates a different security, caching, and testing path from the rest of the product.Use the architecture section to state relationships, not slogans. “Keep business logic in feature modules” is useful when paired with “keep app/ focused on routing and composition.” “Use adapters” becomes actionable when it names the boundary: features call the project’s database or payment abstraction rather than importing a vendor SDK.Frontend Accelerator’s current agent contract follows this pattern: it identifies feature-first modules, keeps routing and composition in app/, and keeps provider-specific implementation behind adapters. That is a concrete example of instructions describing a codebase’s real seams rather than asking an agent to be generally careful.Annotate the template before you adopt itUse this review checklist to turn the template into repository-specific guidance.Map one recent feature. Trace a small change from route to feature logic, data access, and test. Write only the boundaries that actually exist.Name protected infrastructure. Include the paths and domains where a casual edit can change security, billing, configuration, or deployment behavior. Do not mark half the repository as protected.Check the agent’s working directory. If you use nested AGENTS.md files, define which root rules still apply and what the local file adds. Avoid contradictory instructions.Use real commands. Run every listed lint, test, type-check, and build command from a clean enough local environment. Record prerequisites such as an emulator or required environment variables without putting secrets in the file.Test with a small task. Ask an agent to add a contained feature or fix a clear bug. Review whether it chose the intended directory, obeyed the boundary, and ran the stated verification.This is a maintenance loop. When you move a feature boundary, change a test command, or replace a provider integration, update the instruction that would otherwise mislead the next agent.Common failure modesA file that describes an idealized repository“All actions return ActionResult” is harmful if half of the existing actions throw exceptions. Either migrate the pattern deliberately or state the local convention precisely. Agents need a reliable default, not aspirational policy.A wall of rules with no priorityLong instruction files make it difficult to notice the rules that matter. Put the architecture, protected areas, and verification commands near the top. Link to longer design documents instead of duplicating every implementation detail.Commands that are too broad for every changeA full production build may be necessary before a release but disproportionate for a copy change. Describe a baseline for all changes and add targeted checks by area. An agent should still report skipped checks rather than implying they ran.Using instructions as a security boundaryAn AGENTS.md file can tell an agent to validate authorization and keep secrets server-side. It cannot enforce those rules at runtime. Keep real controls in code, CI, access policies, review, and tests.A lightweight operating model for solo buildersUse one canonical root AGENTS.md for rules that apply to the whole app. Keep tool-specific files small and point them back to that contract. Add a nested instruction file only when a directory has genuinely different constraints, such as a payment integration, generated client, or mobile app.Then make the agent’s handoff inspectable. A good task result says what changed, which architectural boundary it used, what it did not change, and which verification ran. That is more useful than a confident claim that the change is “done.”If you want a structured starting point, review Frontend Accelerator’s architecture and AI conventions. It is designed as a Next.js SaaS foundation with a canonical agent contract, tool-specific instruction entrypoints, and repository-level Skills; you still need to adapt any template to your own product decisions and review the generated changes.SourcesOpenAI Codex documentation: AGENTS.mdGitHub Docs: Adding repository custom instructions for GitHub Copilot

July 14, 2026Learn more

A Production-Ready Next.js SaaS Folder Structure for TypeScript, Firestore, and Stripe

Use app/ for routes and composition, src/features/ for product behavior, src/lib/ for provider adapters, and src/shared/ only for code that is genuinely reusable. That split gives a Next.js SaaS a place to grow without turning page files into the place where authentication, billing, Firestore access, and UI state get tangled together.For a solo technical founder, the payoff is not an academic folder taxonomy. It is being able to ask an AI coding agent for a new SaaS capability, review the change in a predictable area, and keep Stripe or Firebase details out of unrelated features. The structure below is a real, current shape from the Frontend Accelerator product repository, adapted into a practical pattern rather than a promise that every SaaS needs the same folders.The folder structure to start withNext.js leaves project organization largely up to you: app is the App Router, public serves static assets, and src is an optional source folder. A route becomes accessible when a segment contains a page or route file. That flexibility is useful, but it also means a SaaS needs its own boundary rules before feature work accumulates.app/ [locale]/ localized marketing, auth, and protected routes api/ auth, lead-capture, payment, and webhook handlerssrc/ features/ auth, blog, changelog, dashboard, glossary, marketing, and profile behavior shared/ reusable components, hooks, layouts, and utilities lib/ auth, AI, database, email, and payment adapters config/ application and sitemap configuration i18n/ routing, request configuration, and messages services/ shared API and state services styles/ global styles and design tokens types/ global TypeScript declarationspublic/ static assetsThis is a feature-first structure, not a claim that folders alone make an app production-ready. The useful part is the dependency direction: route files compose; features own product behavior; provider integrations sit behind narrow infrastructure adapters.Architecture diagram: the dependency direction that mattersapp/[locale] and app/api │ route composition, request entry points ▼src/features/<feature> │ feature actions, components, validation, product rules ├──────────────► src/shared/ only cross-feature reuse ▼src/lib/<domain>/adapter │ provider-specific implementation remains here ▼Firestore / MongoDB / Stripe / Lemon Squeezy / AI providerThe arrow should not point directly from a feature to a provider SDK. In Accelerator, database work is accessed through a database adapter and repositories; payments through a payment adapter; and AI behavior through an AI adapter. The concrete Firestore, MongoDB, Stripe, Lemon Squeezy, OpenAI, Claude, and Gemini integrations live in adapter folders. That gives the rest of the application a smaller, more stable surface to depend on.What belongs in app/Keep app/ intentionally thin. It owns URL structure, layouts, route groups, route handlers, loading and error boundaries, and composition of the UI for a route. In the verified product repository, localized public, auth, and protected routes live under app/[locale]/; API routes cover authentication, lead capture, payments, and payment webhooks.Do not turn a page into a hidden service layer. A dashboard page can fetch the data it needs and compose feature components, but it should not grow a second copy of billing rules or scattered Firebase calls. Next.js route groups can organize layouts without affecting the URL, and private folders can colocate non-routable utilities when a route needs them. Use those framework features for route-local concerns; use feature modules for product behavior that must survive beyond one page.Server Components are the default boundaryIn an App Router project, start with Server Components and introduce "use client" only where hooks, event handlers, browser APIs, or client-only libraries require it. This matters for folder structure because a Client Component must not become a shortcut around server-only infrastructure. Keep database and payment setup on the server side, then pass narrow data and callbacks into interactive components.What belongs in src/features/A feature directory owns behavior that a user recognizes: authentication, the blog, a dashboard capability, or profile management. It can contain focused components, server actions, validation, types that are specific to the feature, and small local utilities. The key rule is that one feature should not reach into another feature’s internals. If code truly becomes reusable across independent features, promote it to src/shared/; otherwise keep it close to the behavior it supports.This is especially valuable when working with agents. A task such as “add a customer-facing subscription status to the dashboard” can be constrained to the dashboard feature, the payment boundary, and the relevant route. That is much safer to review than a broad instruction such as “update the dashboard everywhere.” The architectural rule becomes a practical review checklist.What belongs in src/lib/: provider boundariesTreat src/lib/ as protected infrastructure. In the product repository, it holds auth, AI, database, email, and payment domains. Provider-specific code stays below those domains’ adapter folders. Features do not import Stripe, Firebase, MongoDB, or another provider SDK directly.For example, a subscription feature should express what it needs from a payment adapter—such as creating a checkout session or reconciling a verified event—not how the Stripe SDK formats a request. A Firestore-backed feature should use the database adapter and repository shape rather than query a collection from a component. This is not abstraction for its own sake: it localizes a provider change, makes tests more targeted, and prevents the client bundle from accidentally reaching server credentials.An illustrative addition workflowDefine the reader-visible behavior in the relevant src/features/<feature> directory.Decide whether the request enters through a Server Action or a Route Handler; keep the route file as the request boundary.Use the existing database or payment adapter contract. If it lacks a needed operation, extend the domain boundary deliberately before adding provider code.Keep provider SDK calls inside src/lib/**/adapters/.Add a focused Jest or Testing Library test for the feature rule and an expected failure path.Run the project’s lint, test, and build checks before treating the change as done.This workflow is a recommendation based on the repository’s documented architecture; it is not an assertion that a particular implementation has already been tested for your product.Where src/shared/ helps—and where it hurtssrc/shared/ is useful for UI primitives, layouts, generic hooks, and utilities used by multiple features. It becomes harmful when it is used as a parking lot for feature-specific logic. A “shared” folder full of one-off checkout helpers, dashboard policy checks, and blog-only types obscures ownership and invites cross-feature coupling.Use this decision rule: if deleting a feature would make the module irrelevant, keep it inside that feature. If two independently evolving features need it and the API can stay generic, move it to src/shared/. Keep global configuration, provider setup, and top-level TypeScript declarations in their explicit homes rather than importing them through a generic utility layer.Four failure modes this structure preventsProvider leakage: a React component imports a payment or database SDK, which blurs server/client boundaries and makes later replacement harder.Route logic sprawl: a page file owns validation, authorization, persistence, and presentation, so a second entry point duplicates the rules.Feature-to-feature imports: one feature reaches into another’s private components or data details, making a local refactor unexpectedly risky.Shared-folder gravity: every unsure module is placed in shared, leaving no clear owner and no safe place for agents to make changes.A practical review testBefore merging an AI-assisted change, trace the imports from the changed page or Route Handler. You should be able to explain which feature owns the rule, which server-side boundary validates it, and which adapter reaches the provider. If a component jumps straight to Firestore or Stripe, or a feature imports another feature’s internal component, stop and move the responsibility to its proper boundary. This quick trace catches structural drift before it becomes a costly cleanup.When this structure is the wrong choiceA tiny one-screen prototype does not need every folder shown here. Start smaller if there is no meaningful feature boundary yet. Conversely, this is not an organization-based multi-tenant or enterprise-permissions architecture; those needs require deliberate product and authorization design beyond a folder tree. The structure also does not replace security review, webhook verification, tests, monitoring, or product-specific decisions.For a TypeScript SaaS with authentication, payment state, data access, and a growing dashboard, though, defining these boundaries early is usually cheaper than unpicking them after several AI-assisted feature passes. Start from a codebase whose routes, feature modules, and providers have a clear relationship—then keep the relationship intact as you build.View the reference architectureFrontend Accelerator is a Next.js SaaS foundation that uses the feature-first boundaries described here, along with database, payment, and AI adapters. It is a fit for solo developers and freelancers who want an understandable starting point to extend; it does not replace product-specific engineering or testing. View Accelerator’s architecture.SourcesNext.js documentation: Project structure and organizationNext.js documentation: Server and Client Components

July 13, 2026Learn more

Are SaaS Boilerplates Obsolete in the Age of Claude Code and Codex?

No - SaaS boilerplates are not obsolete. But a boilerplate that is only a collection of pages and components is easier than ever to replace. Claude Code and Codex can generate routes, forms, schemas, UI states, and first-pass integrations quickly. The remaining value is a codebase that already makes the hard systems agree: who may do what, where payment state comes from, how data access is isolated, and how changes are verified.For a React and Next.js-capable solo founder, the useful question is not “can an agent build this?” It usually can. Ask instead: do I want to design, connect, test, and maintain the foundation myself before I learn whether customers want the product?This is a commercial decision, not an argument against agents. A strong starter should give an agent less ambiguity and give you more control over the changes it makes.What coding agents changedCoding agents have reduced the cost of producing individual features. They can help you explore an implementation, generate a draft, find relevant files, and make a contained change. Both Claude Code and Codex support project-level instructions, which makes repository conventions part of the working context rather than something you must restate in every prompt.That changes the minimum bar for a boilerplate. “Includes a dashboard” is not much of a moat when an agent can scaffold one. The more durable value lies in the decisions that span multiple features:where authentication and authorization are checked, rather than merely where a sign-in button appears;how checkout, webhooks, subscription events, refunds, and portal actions map to one payment model;how application code depends on database and payment providers without spreading provider SDK calls everywhere;which server/client boundary a change belongs to; andwhich commands, tests, and review steps establish that a change did not break an existing flow.An agent can assist with all of these. It does not remove the need to choose the boundaries or inspect the result. That is why the best current reason to buy a starter is not to avoid writing code. It is to begin with a coherent set of decisions that you can inspect, extend, and replace deliberately.What a boilerplate still has to earnA boilerplate is worth evaluating only if it saves integration and maintenance work, not just typing. Treat these as evidence requests, not marketing claims.1. Connected flows, not a feature inventoryAuthentication, roles, billing, data access, and dashboard behavior should be connected in code. Ask to see how a checkout event changes application state, what happens when an event is delivered twice, and where administrator access is protected on the server. A starter with many disconnected folders can still leave you to solve the important transitions.2. Clear seams for providers and product choicesMost SaaS products change their minds about a provider, data model, or product rule. A practical foundation keeps those dependencies behind explicit adapters or feature boundaries. That does not make switching free; it makes the dependency visible and narrows the area you must change.3. Instructions an agent can followA useful agent-ready repository explains its structure, local rules, verification commands, and prohibited shortcuts. OpenAI documents project instructions through AGENTS.md; Anthropic documents shared project memory through CLAUDE.md. Those files are not a substitute for architecture, but they make the architecture easier for a coding agent to work within.4. A maintainable starting pointStarting code is a liability if you cannot explain it six weeks later. Prefer a smaller foundation with explicit conventions over a huge bundle of opaque features. You still own product-specific engineering, testing, monitoring, and security review after you adopt it.An honest build-versus-buy decision treeUse this as the promised scorecard. Answer each step based on the next product you actually intend to ship, not on the most ambitious future version.Is your product intentionally unusual at the foundation? Build from a blank repository if its core needs are organization-based multi-tenancy, unusual authorization, compliance-driven identity, a database model the starter does not support, or a heavily bespoke billing model. Forcing a starter to become a different product is false economy.Do you already have proven internal patterns? Build if you maintain a current template with tested auth, billing, data, observability, and deployment conventions that your team understands. Rebuying the same patterns adds little.Are common SaaS systems a prerequisite rather than your differentiation? Consider a boilerplate if you need sign-in, payments, a member area, content, or admin tooling before customers can use the distinctive part of your product.Can you inspect the repository before committing? Buy only when you can verify the stack, boundaries, provider assumptions, license, update model, and testing approach. If those are unavailable, treat the starter as unverified source code—not a shortcut.Will your agent have project-specific guardrails? A boilerplate becomes more valuable when its conventions and verification steps are written down. Without them, an agent may create locally plausible changes that drift from the intended architecture.Can you name the first product-specific feature? If you cannot, do customer and product discovery first. A foundation cannot validate an idea for you.Recommendation: buy a foundation when it lets you spend the first week on a customer-facing differentiator instead of reconnecting commodity systems. Build from scratch when your architecture itself is the differentiator or the starter conflicts with it.Who should not buy a SaaS boilerplateYou should probably not buy one when any of these conditions are true:You are new to React and Next.js and need to learn the fundamentals before taking on a large codebase.Your project requires enterprise SSO, organization or workspace multi-tenancy, fine-grained permissions, or compliance requirements from the first release.You need PostgreSQL or Supabase and the starter only supports a different database approach.You expect an agent to run the entire product, deployment, security, and maintenance process without engineering judgment.You have no time to read the architecture, configure providers, and test the specific flows you will ship.In those cases, the realistic options are a more appropriate platform, a smaller custom build, or a foundation whose constraints match your product. “AI-ready” should not mean “every product fits.”Where Frontend Accelerator fitsFrontend Accelerator is aimed at the middle case: a solo developer or freelancer who already knows React and basic Next.js, wants an integrated SaaS foundation, and plans to extend it with coding agents without surrendering ownership of the codebase.Its documented foundation includes Next.js 16 App Router, React 19, strict TypeScript, Firestore and MongoDB adapters, Stripe and Lemon Squeezy payment adapters, common authentication options, admin and member roles, protected administrator routes, and agent-oriented project instructions. Its public product page is also explicit about the boundary: it is not a no-code system, organization-based multi-tenancy, enterprise SSO, fine-grained enterprise permissions, PostgreSQL/Supabase support without your own adapter, or autonomous deployment.That makes it a candidate when your product needs conventional SaaS infrastructure but your differentiation sits above it. It is not a reason to skip threat modeling, provider configuration, feature-specific tests, or a real launch checklist.How to evaluate any starter in an afternoonTrace one request: follow a protected dashboard action from UI to server authorization to data write and expected error.Trace one revenue event: inspect how a payment event is verified, mapped, stored, and made idempotent.Find the seams: locate database, payment, and AI provider abstractions. Confirm that product code does not need direct provider calls everywhere.Read the agent instructions: look for architecture rules, commands, file ownership, and verification expectations—not just a generic prompt.Run the checks: install, configure the minimum environment, and execute the documented test or lint commands before making it your foundation.The scorecard is simple: if a starter gives you verified seams, connected flows, and understandable conventions, it can be more valuable in the agent era than before. If it gives you only generated surface area, let the agent generate that surface area for you.Run the build-versus-buy scorecard: if the decision tree points toward a foundation, review Frontend Accelerator if that starting point fit your needs.SourcesOpenAI Help Center: Getting started with CodexAnthropic: Manage Claude Code memoryFrontend Accelerator: AI-Ready Next.js SaaS Boilerplate

July 12, 2026Learn more

A Production-Ready Next.js SaaS Folder Structure for TypeScript, Firestore, and Stripe

The folder structure to start with

Architecture diagram: the dependency direction that matters

What belongs in `app/`

Server Components are the default boundary

What belongs in `src/features/`

What belongs in `src/lib/`: provider boundaries

An illustrative addition workflow

Where `src/shared/` helps—and where it hurts

Four failure modes this structure prevents

A practical review test

When this structure is the wrong choice

View the reference architecture

Sources

More articles

AGENTS.md for Next.js: a practical template for coding agents

A Production-Ready Next.js SaaS Folder Structure for TypeScript, Firestore, and Stripe

Are SaaS Boilerplates Obsolete in the Age of Claude Code and Codex?

Ready to Launch Your SaaS Faster?