Backend boilerplate DuploJS

Minimal boilerplate to start a back end with DuploJS, TypeScript, ESLint, and an architecture that separates the business core from the infrastructure.

Requirements

• Node.js >= 22.15.1
• npm

Installation

npm install

The npm run dev:http command already sets ENVIRONMENT=DEV, so the development server can be started without additional configuration.

Commands

npm run dev:http

Starts the HTTP server in watch mode with tsx.

---

npm run test:types

Checks TypeScript types for each part of the project.

---

npm run test:lint

Runs ESLint on the business/ and infrastructure/ directories.

HTTP Server

The HTTP entry point is infrastructure/http/main.ts.

In development, the server listens on:

http://localhost:1506

Route available in the boilerplate:

curl "http://localhost:1506/hello-world?name=Duplo"

The route is declared in infrastructure/http/routes/index.ts.

The server also plugs in:

• the DuploJS client type generator, with clientTypes.d.ts as output;
• the OpenAPI generator, with swagger.json as output and a /swagger route.

Architecture

The project is split into two main areas:

business/
  domains/
    entities/
    aggregates/
    repositories/
  applications/
    ports/
    useCases/

infrastructure/
  adapters/
    ports/
    useCases/
  commands/
  http/
    routes/
  providers/

business/domains

Contains the pure business model.

• entities/: business entities.
• aggregates/: business aggregates.
• repositories/: repository contracts on the domain side.

This layer must not depend on the infrastructure.

business/applications

Contains the application logic.

• useCases/: application use cases.
• ports/: contracts required by the use cases.

Use cases express the business actions of the application. They can depend on the domain and on ports, but not directly on technical implementations.

infrastructure/adapters

Contains the technical implementations used by the application.

• ports/: implementations of application ports.
• useCases/: instantiation of use cases with their dependencies.

The infrastructure/adapters/useCases/index.ts file assembles use cases and ports with C.useCaseInstances.

infrastructure/http

Contains the HTTP interface.

• main.ts: creates the DuploJS hub, plugs in plugins, registers routes, and starts the server.
• routes/: HTTP route declarations.

Routes should remain focused on HTTP transport: parameter extraction, validation, use case calls, and response formatting.

infrastructure/providers

Contains shared technical providers, such as environment variable loading.

infrastructure/providers/envs.ts loads .env and currently validates:

ENVIRONMENT: "DEV" | "PROD"

infrastructure/commands

Area intended for executable commands outside HTTP: business scripts, jobs, administration tasks, or one-off processing.

TypeScript Aliases

Each subproject has its own tsconfig.json and exposes the aliases useful in its context:

• @domains/*
• @applications/*
• @adapters/*
• @providers/*
• @http/*
• @commands/*

The root tsconfig.json references all subprojects to allow a full check with npm run test:types.

Quality and Git Hooks

The project uses:

• TypeScript in strict mode;
• ESLint with the @duplojs/eslint configuration;
• Husky;
• Commitlint with the @commitlint/config-conventional convention.

A pre-push hook runs:

npm run test:types
npm run test:lint

A commit-msg hook checks the commit message format.

Adding a Feature

Recommended flow:

1. Add business objects in business/domains.
2. Define ports and use cases in business/applications.
3. Implement ports in infrastructure/adapters.
4. Expose the feature through a route in infrastructure/http/routes.
5. Check with npm run test:types and npm run test:lint.