> For the complete documentation index, see [llms.txt](https://docs.soapjs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soapjs.com/quick-start.md).

# 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](https://github.com/soapjs/soap-node-demo) — a full app from simple CRUD to event-driven CQRS with WebSockets.

### 1. Install

```bash
# 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:

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

### 3. A minimal app

```typescript
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](https://github.com/soapjs/soap-node-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