Node.js with TypeScript: Project Structure, ESM vs CJS, and Build Setup

Overview

If you want a stable node typescript setup, the goal is not to assemble the most modern stack possible. The goal is to make local development, tests, builds, and production runtime agree with each other.

That usually comes down to five decisions:

1. Module system: ESM or CommonJS
2. Development runtime: run TypeScript directly or compile before running
3. Build output: plain tsc or a bundling/transpiling step
4. Project structure: app layout, path aliases, config separation
5. Package target: internal app, CLI, or published library

For most backend applications, maintainability improves when you keep the setup boring:

• Use one module system consistently
• Keep src and build output clearly separated
• Use a dedicated tsconfig for builds if needed
• Avoid path alias tricks unless you fully support them in runtime and tests
• Make your npm scripts describe the workflow clearly

A simple baseline structure often works well:

project/
  src/
    index.ts
    server.ts
    routes/
    services/
    lib/
    types/
  dist/
  test/
  package.json
  tsconfig.json
  tsconfig.build.json

That structure is not mandatory, but it keeps source code, compiled output, and tests from drifting into each other. If you need a deeper configuration guide, see tsconfig.json Best Practices: Recommended Settings for Apps, Libraries, and Monorepos.

Before choosing tools, answer these questions:

• Is this an application deployed to your own environment, or a package consumed by others?
• Do you need maximum compatibility with older tooling?
• Will you run Node directly in production, or through a bundled artifact?
• Does your team already have ESM experience?
• Do tests, scripts, and migration tools all support the same module choice?

Those answers matter more than fashion. In node js with TypeScript, the biggest source of friction is not the language itself. It is mismatch between compiler output and runtime expectations.

Checklist by scenario

Use this section as a decision worksheet. Pick the scenario closest to your project, then adjust only if you have a clear reason.

Scenario 1: Internal backend app that values predictability

This is the safest default for many teams building APIs, workers, or service backends.

Recommended direction:

• Prefer CommonJS if your ecosystem still depends on older tools or mixed scripts
• Use tsc for type-checking and compilation
• Compile to dist/ before production runs
• Keep imports relative unless aliases are truly needed

Why this works: CommonJS remains straightforward in many Node deployments. If your team has shell scripts, older Jest setups, migration scripts, or internal tooling that expect require-style behavior, CommonJS reduces surprises.

Checklist:

• package.json scripts clearly separate dev, build, start, and typecheck
• tsconfig.json has a clear rootDir and outDir
• Production runs compiled JavaScript, not raw TypeScript
• Tests target the same module behavior as runtime
• No source files are imported from dist or vice versa

Good fit for: APIs, cron jobs, workers, internal services, and teams migrating from JavaScript.

Scenario 2: New Node app using modern ESM conventions

If you are starting fresh and want alignment with modern JavaScript syntax, ESM can be a strong choice. It is especially reasonable when your team already understands import specifier rules and your tools support ESM cleanly.

Recommended direction:

• Choose ESM intentionally, not by accident
• Use Node-compatible module settings in TypeScript
• Test file extension handling, package exports, and local scripts early
• Keep runtime assumptions explicit in documentation

Why this works: ESM aligns with standard JavaScript modules and can make your codebase feel more consistent across frontend and backend projects. It also helps when sharing conventions with frameworks and modern libraries.

Checklist:

• package.json module behavior is explicitly declared
• Local dev command uses a runtime that supports your chosen TypeScript + ESM workflow
• Compiled output is tested with the same Node version used in production
• Any tools that load config files are checked for ESM compatibility
• Dynamic imports and JSON imports, if used, are validated in your actual runtime

Good fit for: new services, modern monorepos, teams standardizing around ESM, and codebases that already use modern package export patterns.

Scenario 3: Fast local development with separate production build

Many teams want fast reloads in development but still want clean compiled output in production. That is usually a healthy compromise.

Recommended direction:

• Use a dev runner optimized for quick iteration
• Use tsc for type-checking and production-safe compilation, or at least for validation
• Treat development execution and production build as separate concerns

Why this works: Development speed and production reliability do not need to come from the same tool. A fast dev runner can improve feedback loops, while a stricter build pipeline catches issues before deployment.

Checklist:

• Dev command supports watch mode and restart behavior clearly
• Build command produces deterministic output
• Type-checking is not accidentally skipped in CI
• Source maps are configured for debugging where needed
• Environment variable loading works the same way in dev and production

Good fit for: most application teams, especially where startup time matters during local work but deploys still depend on compiled artifacts.

Scenario 4: Published TypeScript library for Node users

Libraries need more care than apps because consumers do not share your exact runtime assumptions.

Recommended direction:

• Be conservative about output and package metadata
• Consider whether consumers need ESM, CommonJS, or both
• Ship type declarations clearly
• Avoid leaking internal folder structure into public imports

Why this works: Application teams can control their runtime. Library authors cannot. Your package should be easy to consume without forcing downstream users into your exact toolchain choices.

Checklist:

• Public entry points are intentional
• types and runtime entry files are aligned
• Subpath exports are documented if used
• Build output does not expose private source layout
• Consumers can import the package without guessing file paths

Good fit for: npm packages, shared internal libraries, SDKs, and CLI utilities.

Scenario 5: JavaScript to TypeScript migration in an existing Node project

This is where many teams overcomplicate things. During migration, consistency usually matters more than ideal architecture.

Recommended direction:

• Keep the existing module system first
• Introduce TypeScript with minimal runtime disruption
• Compile in a way that mirrors the current deployment flow
• Convert high-value modules before chasing perfect type coverage

Why this works: If you change language, module system, test runner behavior, and build pipeline at once, failures become harder to isolate. Migration is smoother when runtime behavior stays familiar.

Checklist:

• Add TypeScript without immediately switching from CJS to ESM unless necessary
• Allow mixed JS and TS temporarily if the migration demands it
• Move utility types and shared interfaces into stable locations early
• Use CI to enforce no regression in build output
• Document temporary exceptions and cleanup steps

For broader migration patterns, your team may also benefit from related TypeScript fundamentals such as TypeScript Narrowing Guide: typeof, in, instanceof, and Custom Type Guards and Generics in TypeScript: Practical Patterns for Functions, APIs, and Components.

What to double-check

Once you have chosen a direction, this is the short list to verify before your setup becomes team convention.

1. Runtime and compiler agree on modules

This is the center of the esm vs cjs typescript problem. Your TypeScript compiler can happily produce code that your Node runtime, test runner, or CLI loader handles differently. Double-check:

• How imports are written in source
• What JavaScript gets emitted
• How Node interprets that output
• How your tests and scripts load those files

If one layer assumes ESM and another assumes CommonJS, errors often appear late and look unrelated.

2. Project structure supports growth

A maintainable typescript project structure should make it obvious where application logic belongs. Useful boundaries include:

• routes or handlers for transport concerns
• services for business logic
• lib for reusable internal helpers
• types for shared interfaces and contracts
• test separated from production code unless co-location is deliberate

If every file starts importing from every other folder, the structure is not helping. Simpler folders are better than elaborate architecture no one follows.

3. Build scripts describe intent

Your scripts should answer four questions quickly:

• How do I start local development?
• How do I type-check?
• How do I produce production output?
• How do I run that output?

If a new developer cannot infer the workflow from scripts and a short README, your setup is probably too opaque.

4. Path aliases are fully supported or not used

Aliases can improve readability, but they often add hidden complexity. They must work in:

• TypeScript
• Runtime resolution
• Tests
• Build tools
• Editor navigation

If even one layer needs extra configuration, ask whether relative imports would be cheaper to maintain.

5. CI type-checking is explicit

Some fast build tools transpile without full type-checking. That can be fine in development, but CI should still run a real type-check. If your deployment path depends only on transpilation, type errors may slip through until later. A dedicated typecheck script is worth keeping even when the build tool appears to “handle TypeScript.”

For debugging difficult compiler output, keep a reference to TypeScript Error Guide: Common Compiler Errors and How to Fix Them and a lightweight syntax refresher like the TypeScript Cheat Sheet: Syntax, Utility Types, and Everyday Patterns.

Common mistakes

These are the setup problems that tend to waste the most time because they look small at first.

Changing to ESM and TypeScript at the same time without a rollback plan

Each change affects imports, config files, tests, and deployment behavior. Together they multiply uncertainty. If you are migrating an established service, it is often safer to adopt TypeScript first, then revisit ESM later.

Using multiple execution paths that behave differently

For example:

• Dev runs raw TypeScript
• Tests run transformed files differently
• Production runs compiled JavaScript with different resolution rules

This creates bugs that only appear in one environment. The closer these paths are, the easier the system is to trust.

Letting dist become part of the source tree

Compiled output should be treated as generated code. Do not import from it inside source files, and do not mix handwritten files into the build folder. Keep the boundary clean.

Overdesigning the folder structure too early

A deeply nested architecture can look mature while slowing down real work. Start with a small number of obvious folders and split only when responsibilities become clear.

Assuming “works in editor” means “works in runtime”

Editors can resolve types and aliases in ways your runtime cannot. Always validate actual runtime behavior, especially around module resolution and import paths.

Skipping documentation because the setup feels obvious

Tooling choices are only obvious to the people who made them. Add a short setup note that explains:

• Why you chose ESM or CommonJS
• Which command is for development
• Which command builds for production
• Whether CI type-checks separately

That small note saves repeated onboarding effort.

When to revisit

Your Node TypeScript build setup should not change every month, but it should be reviewed when the surrounding assumptions change. Use this practical checklist before planning cycles or after tooling updates.

Revisit your setup when:

• You upgrade Node versions across environments
• You introduce a new test runner or build tool
• You start publishing shared packages from an app-oriented repo
• You add path aliases, package exports, or monorepo workspaces
• You move from CommonJS conventions toward ESM across the organization
• Your deployment target changes from compiled output to direct runtime execution, or the reverse

Questions to ask during a review

1. Is our current module system still the least surprising option?
2. Are development and production closer together or drifting apart?
3. Do our scripts still describe the workflow clearly?
4. Are new team members confused by imports, build output, or file layout?
5. Do we still need every tool in the chain?

Practical action plan

If you are setting up a project today, choose one of these starting points:

• Need maximum stability: CommonJS, tsc build, compiled production output
• Starting fresh with modern conventions: ESM, explicit Node-compatible config, test your runtime assumptions early
• Need faster local iteration: fast dev runner plus separate type-check and production build
• Migrating from JavaScript: preserve current runtime behavior first, then improve gradually

Then write down your choices in the repo. A good setup is not just technically correct. It is understandable six months later.

If your work also touches framework boundaries, continue with Next.js with TypeScript: App Router Patterns, Server Actions, and Type Safety or React with TypeScript: Best Practices for Props, Hooks, and Component APIs. But for pure Node backends, the durable lesson is simpler: keep the runtime model clear, keep the build repeatable, and avoid introducing cleverness that your team will have to debug later.