Folder Structure

NeatNode provides different folder structures for JavaScript and TypeScript templates, each optimized for clarity and scalability.

JavaScript Templates - Typical Structure

Used by Basic (JS), REST API (JS), and Socket.IO (JS) templates.


<project-root>/
├── package.json
├── server.js
└── src/
    ├── app.js
    ├── config/
    ├── controllers/
    ├── models/
    ├── routes/
    ├── services/
    ├── middleware/
    └── utils/

This structure follows a layer-based architecture, separating concerns clearly.

JavaScript Template Folders `/src`

controllers/

Request handlers mapped to routes.

routes/

Defines API endpoints.

services/

Business logic and database interactions.

models/

Mongoose schemas or DB models.

middleware/

Auth, validation, and error handling.

utils/

Shared helpers like ApiError, ApiResponse, CatchAsync.

TypeScript Templates - Layered + Modular Patterns

NeatNode TypeScript templates currently use two patterns:

Basic (TS) uses a clean layer-based structure
REST API (TS) uses a modular feature-based structure


<project-root>/
├── package.json
├── tsconfig.json
└── src/
    ├── app.ts
    ├── server.ts
    ├── config/
    ├── middlewares/
    ├── modules/
    │   └── auth/
    │       ├── auth.controller.ts
    │       ├── auth.route.ts
    │       ├── auth.service.ts
    │       ├── auth.validation.ts
    │       └── user.model.ts
    ├── routes/
    ├── types/
    └── utils/

This keeps TypeScript projects strongly typed while still easy to evolve.

Root Files

File	Purpose
package.json	Dependencies and scripts
server.js / server.ts	Application entry point
app.js / app.ts	Express configuration
tsconfig.json	TypeScript compiler configuration
.env / .env.example	Environment variables

TypeScript Template Folders `/src`

modules/ (REST API TS)

Feature-based modules that group domain logic.

Example:


modules/auth/
├── auth.controller.ts
├── auth.service.ts
├── auth.route.ts
├── auth.validation.ts
└── user.model.ts

config/

Database, logger, and typed environment setup.

middlewares/

Typed middleware (auth, validation, errors).

utils/

Typed helpers, error classes, response wrappers.

Template Variations

Template	Structure Type	Notes
Basic (JS)	Layer-based	Minimal Express setup
REST API (JS)	Layer-based	Auth + validation
Socket.IO (JS)	Layer-based	Adds socket config
Basic (TS)	Layer-based	Strict typing
REST API (TS)	Module-based	JWT + Zod + typed middleware
Socket.IO (TS)	Planned	Not shipped yet

Extending the Structure

You can safely add new folders in both JS and TS templates:


src/
 ┣ jobs/        # Background jobs
 ┣ validators/  # Custom schema validation
 ┗ scripts/     # Seeding or CLI scripts

Request Flow Comparison

JavaScript (Layer-Based)


Route → Controller → Service → Model → Response

TypeScript (Module-Based)


Route → Controller → Service → Model → Response
(all inside one module)

✅ Summary

JS templates → layer-based structure
TS templates → layer-based (Basic) and module-based (REST API)
Same concepts, different organization
Easy to scale, easy to understand

[!TIP] Once you understand one template, switching between JS and TS is straightforward.