TypeScript Project Structure: A Scalable Folder Layout for Frontend and Node.js Apps

Overview

There is no single correct TypeScript folder structure. A small command-line tool, a React application, a Node.js API, and a monorepo have different boundaries and deployment needs. The useful goal is not to arrange every file perfectly; it is to make the important boundaries visible and keep related code close together.

Start with four questions:

• What can change independently?
• Which code belongs to a feature, and which code is genuinely shared?
• Where do external concerns enter the application, such as HTTP, databases, files, or environment variables?
• How will the project be built, tested, and deployed?

These questions usually lead to a structure based on application type and module boundaries rather than a large collection of generic folders. A typical TypeScript application may separate source code, tests, configuration, generated output, and documentation:

project/
├── src/
├── tests/
├── scripts/
├── docs/
├── package.json
├── tsconfig.json
├── tsconfig.build.json
└── README.md

Keep the root focused on project-level configuration. Do not place compiled JavaScript, coverage reports, local environment files, or temporary exports beside source files unless the tool specifically requires it. Use .gitignore and build configuration to keep generated artifacts out of the working tree.

Checklist by scenario

Frontend applications with React or Next.js

Frontend projects often benefit from feature-oriented folders because screens, state, UI, and API calls tend to evolve together. A practical structure might look like this:

src/
├── app/                 # routes, layouts, or application composition
├── features/
│   ├── billing/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── api.ts
│   │   ├── types.ts
│   │   └── index.ts
│   └── profile/
├── components/          # genuinely reusable UI
├── lib/                 # configured clients and infrastructure helpers
├── hooks/               # cross-feature hooks only
├── styles/
└── test-utils/

Use features for code that has a clear product or user-facing purpose. Keep reusable components in a shared location only after they have a stable interface and more than one consumer. For Next.js, the exact location of routes may be determined by the framework's routing convention, but feature logic can still live outside route files.

• Keep page or route components thin: compose features rather than implementing every detail there.
• Put browser-only code behind an explicit boundary when server and client code coexist.
• Keep API response types near the client or feature that owns the request, unless multiple applications consume the contract.
• Place component tests beside components when that makes the relationship obvious; keep shared test setup in test-utils.

For API response design, see this guide to typing API responses in TypeScript. Type declarations describe expected data at compile time, but external responses should still be checked at runtime when the boundary requires it.

Node.js APIs and services

For a Node.js application, separate transport, application logic, and infrastructure. This prevents request objects, database clients, and framework-specific details from spreading through the whole codebase.

src/
├── server.ts             # process startup and server wiring
├── app.ts                # application composition
├── config/
│   ├── env.ts
│   └── index.ts
├── modules/
│   ├── users/
│   │   ├── user.routes.ts
│   │   ├── user.controller.ts
│   │   ├── user.service.ts
│   │   ├── user.repository.ts
│   │   ├── user.schema.ts
│   │   └── user.types.ts
│   └── orders/
├── infrastructure/
│   ├── database/
│   ├── logging/
│   └── http/
└── shared/
    ├── errors/
    └── types/

Use module folders for business capabilities. A controller can translate an HTTP request into an application call, a service can coordinate business rules, and a repository can hide persistence details. This is a useful separation, but do not add layers that contain no independent behavior. A small service may reasonably combine a few responsibilities until the code gives you a reason to split them.

Validate environment variables at startup rather than allowing missing configuration to fail later. The TypeScript environment variable guide covers patterns for keeping configuration typed and checked at the application boundary.

Small projects and JavaScript migrations

When migrating JavaScript to TypeScript, preserve the existing behavior before attempting a full architectural redesign. Begin with a structure that reflects the current application:

src/
├── components/
├── services/
├── utils/
├── types/
└── index.ts

Then move related files into feature or domain modules as the boundaries become clear. Avoid creating a large types directory as a destination for every interface. A type used only by one module usually belongs beside that module. Shared types should represent a deliberate contract, not merely a convenient import location.

Monorepos and shared packages

In a monorepo, organize around package ownership and public interfaces:

apps/
├── web/
└── api/
packages/
├── config/
├── domain/
├── api-client/
└── ui/

Each package should have a clear purpose, its own entry point, and a limited public API. Do not share framework-specific code simply because two applications happen to use the same language. Share stable domain models, validation schemas, design-system components, or API clients when the dependency direction is clear. The TypeScript monorepo guide explains project references, aliases, and package boundaries in more detail.

What to double-check

A folder layout is only useful when the tooling enforces its assumptions. Review these areas before adopting a new TypeScript application structure.

Module boundaries and imports

Decide which modules may import one another. A feature should not reach into another feature's private files through long relative paths. Use an index.ts entry point when it provides a meaningful public surface, and consider lint rules or package boundaries for larger projects. Path aliases can improve readability, but they must work consistently in the editor, test runner, bundler, and production runtime. See the path alias guide before adding them.

tsconfig layering

Keep the base compiler settings separate from environment-specific concerns when the project has more than one build target. A common arrangement is a base tsconfig.json, a build configuration that defines output and included files, and a test configuration when tests need different globals or module behavior.

Check rootDir, outDir, include, exclude, module resolution, and strictness settings together. A configuration that passes in an editor but fails in the build or test command is not a stable project foundation.

Runtime and build behavior

TypeScript types are removed during compilation. They do not validate JSON, environment variables, request bodies, or database results by themselves. Keep runtime validation at external boundaries and derive or align TypeScript types from those contracts where practical. Also document whether the project uses tsc, a bundler, or a transpiler for each output. The TypeScript build tools comparison can help when that choice changes.

Testing locations

Place unit tests close to the code when discoverability matters, and use a top-level integration or end-to-end test directory when tests represent a complete application flow. Whichever pattern you choose, make test discovery predictable and keep fixtures, mocks, and test-only helpers from becoming production dependencies.

Common mistakes

• Creating folders before responsibilities exist. Empty services, repositories, and adapters folders add ceremony. Introduce a boundary when it isolates a real concern.
• Using one global types folder. This often becomes an unowned collection of unrelated declarations. Keep local types local and expose shared contracts intentionally.
• Making shared code depend on an application. Shared packages should not import UI screens, route handlers, or application configuration. Keep dependencies flowing toward stable abstractions.
• Putting business logic in framework files. Route and component files are convenient entry points, but logic placed there is harder to reuse and test.
• Confusing compile-time safety with runtime safety. An interface cannot prove that an external payload has the expected shape. Validate data where it enters the system.
• Adding aliases without checking every tool. An alias that works in TypeScript may still fail in a test runner or deployed runtime.
• Mixing generated and authored files. Generated clients, declarations, and build output should have clear locations and ownership.

When to revisit

Review the project structure before a seasonal planning cycle, a substantial migration, or a change in build and test tooling. Also revisit it when a team repeatedly struggles to find code, when imports cross feature boundaries, or when a supposedly shared module requires application-specific exceptions.

Use this short checklist during the review:

1. List the main deployable applications and identify their entry points.
2. Map each feature or package to an owner and a public interface.
3. Find the most common cross-module imports and question the dependency direction.
4. Confirm that TypeScript, the bundler, the test runner, and the runtime resolve modules in the same way.
5. Check that external data is validated and that shared types represent real contracts.
6. Remove empty abstraction folders, obsolete aliases, generated files, and unused shared utilities.
7. Document the decisions that are not obvious from the directory tree.

Make one small structural improvement at a time, run the full type-check and test commands, and update the project documentation alongside the change. A scalable TypeScript architecture is not defined by the number of folders. It is defined by boundaries that remain understandable as features, tools, and deployment targets evolve.