Quick Start

SoapJS is a lightweight, framework-agnostic library for building applications with clean architecture — entities, use cases, repositories, CQRS, auth — with minimal boilerplate. There is no scaffolding CLI: the framework is convention-driven, so you (or your AI assistant) simply follow the patterns.

The canonical, always-up-to-date reference is the Comics Universe demo: github.com/soapjs/soap-node-demo — a full app from simple CRUD to event-driven CQRS with WebSockets.

1. Install

# core + HTTP + MongoDB
npm install @soapjs/soap @soapjs/soap-express @soapjs/soap-node-mongo reflect-metadata express

# optional: auth
npm install @soapjs/soap-auth bcryptjs

Current versions: @soapjs/soap 0.10, @soapjs/soap-express 0.3, @soapjs/soap-node-mongo 0.7, @soapjs/soap-auth 0.4.

2. Enable decorators

SoapJS uses decorators, so enable them in tsconfig.json and import reflect-metadata once at your entry point:

{
  "compilerOptions": {
    "target": "ES2021",
    "module": "commonjs",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "esModuleInterop": true
  }
}

3. A minimal app

import 'reflect-metadata';
import { bootstrap, Controller, Get } from '@soapjs/soap-express';
import { Request, Response } from 'express';

@Controller('/hello')
class HelloController {
  @Get('/')
  async hello(_req: Request, res: Response): Promise<void> {
    res.json({ message: 'Hello from SoapJS' });
  }
}

bootstrap({
  port: 3000,
  controllers: [HelloController],
  middleware: { cors: true, helmet: true, logging: true },
  healthCheck: true,
});

bootstrap() wires Express, middleware, routing, optional auth and CQRS in one call. Run it and hit http://localhost:3000/hello.

4. Follow the pattern

SoapJS doesn't generate code for you — it gives you the building blocks and a clear structure to follow. Organize features by dependency direction:

src/
├── config/        ← env + composition root (dependency wiring)
├── common/        ← shared-kernel + cross-cutting
└── features/
    └── <feature>/
        ├── domain/        ← entities, value objects, domain events
        ├── application/   ← use cases, commands/queries, ports
        ├── data/          ← adapters: repository impls, mappers
        └── api/           ← controllers, event consumers, sockets

Pick the ceremony that fits each feature: a plain controller → use case → repository for simple CRUD, or full CQRS with commands, queries, events and read-model projections for complex domains. The demo shows both side by side.

Next steps

• Components — entities, repositories, controllers, and more

• Database Interaction Strategies — Where, RepositoryQuery, native queries

• Plugins — MongoDB, Express, auth, and others