A microservice is a self-contained module that runs as its own process. Unlike a regular feature module — which is registered into AppModule or SharedModule and served by the API — a microservice has its own entrypoint, its own start hook, its own Dockerfile, and its own port. The generator creates all of that and wires the service into your project’s config so it is reachable from day one.
The microservice:create command does the heavy lifting: it scaffolds the module folder, picks a free port, and updates the app config, env config, tsconfig aliases, and commitlint config so nothing is left dangling.
What it does
- Scaffolds a standalone module under
modules/<kebab-name>/ with everything it needs to boot on its own.
- Picks a free port. Port
3000 is the API; microservices start at 3001 and the generator takes the next free port.
- Wires the networking. The service is declared in the app module config and the root env so other parts of the system can resolve its URL.
- Stays out of the registry. A microservice is never registered into
AppModule or SharedModule — it runs standalone.
Command
ooneex microservice:create [options]
Examples
# Interactive: prompts for the microservice name
ooneex microservice:create
# Provide the name as a flag
ooneex microservice:create --name=billing
# Run against a specific project directory
ooneex microservice:create --name=billing --cwd=/path/to/project
Options
| Option | Description | Default |
|---|
--name | Microservice name. Normalized to PascalCase with any trailing Module stripped; the module folder uses its kebab-case form. | Prompted if omitted |
--cwd | Project directory the microservice is created in. | Current working directory |
--silent | Suppress prompts and success output. | false |
What gets generated
Running the command against a name like billing creates a complete module under modules/billing/:
| File | Purpose |
|---|
src/index.ts | The microservice entrypoint — its own boot, distinct from the API. |
src/OnAppStart.ts | Start hook that runs when the service comes up. |
src/BillingModule.ts | The module class (<PascalName>Module). |
Dockerfile | Container build for running the service standalone. |
.env.yml | Service-local env, bound to the free port the generator picked. |
roles.yml | Role definitions for the service. |
package.json | Module package, named @module/<kebab>. |
tsconfig.json | TypeScript config for the module. |
billing.yml | Module manifest with type: "microservice". |
tests/BillingModule.spec.ts | A mirrored test for the module class. |
Networking it wires
Because a microservice runs as its own process, the rest of the system needs to know how to reach it. The generator wires that up automatically, updating these files when they exist:
| Target | What changes |
|---|
modules/app/app.yml | Adds the service to the microservices: list, with its URL read from the MICROSERVICE_<SNAKE>_URL env var. |
Root .env.yml | Adds the service to the microservices: map. |
Root tsconfig.json | Adds the path aliases for the new module. |
| Commitlint config | Registers the new module as a valid commit scope. |
MICROSERVICE_BILLING_URL), so each environment can point at a different host without code changes. See Networking for how services discover and call one another.
Next: compose the service
The scaffold gives you a running, reachable shell. The next step is to fill it with artifacts — controllers, services, repositories, and the rest — so the microservice actually does its work. Generators like the controller and service commands target the new module by name, the same way they target any other module.
See Composition for building out the service with artifacts.
Start and stop the microservice
A microservice runs as its own process. Start it from the project root with app:start; the --microservice flag narrows the run to microservice modules:
# Start every microservice
ooneex app:start --microservice
# Start just one by name
ooneex app:start --microservice=billing
# Start several named services at once
ooneex app:start --microservice=billing,payments
# Run the microservice alongside the api it serves
ooneex app:start --api --microservice
app:start brings up the shared Docker stack first, then serves each selected microservice’s entrypoint with hot reload. To stop the running services, interrupt the process with Ctrl+C.
app:stop brings down the app module’s shared Docker stack. A microservice is stopped through the same command only when it ships its own docker-compose.yml, in which case the flag narrows the stop to it:
ooneex app:stop --microservice=billing # bring down a microservice's own Docker stack
Running ooneex app:start with no flag starts every api, microservice,
and spa module together — the simplest way to bring the whole system up.
Use with Claude and Codex
The generator ships a matching microservice:create skill. It runs the scaffold and then guides your AI agent through the follow-up: confirming the networking wiring and composing the service with its first artifacts. Initialize the skills once for your agent:
Then ask Claude in natural language — it maps the request to the generator and runs it:Create a billing microservice.
Then ask Codex in natural language — it maps the request to the generator and runs it:Create a billing microservice.
microservice:create --name=billing, scaffolds the standalone module on the next free port, and wires it into the app config, env, and tsconfig aliases.
