Structure

A module is a self-contained unit of your application that lives under modules/<name>/. Running talos module:create scaffolds a fixed set of files: a definition that lists the module’s artifacts, a config file, a workspace package.json, a tsconfig.json, and a mirrored test. Everything you generate afterward (controllers, entities, services, middleware) lands in predictable subfolders under src/. This page walks through that layout file by file. See Overview for what a module is and Composition for how modules combine.

Layout

A freshly created billing module looks like this:

modules/billing/
├── billing.yml                    # module config (type)
├── package.json                   # workspace package: @module/billing
├── tsconfig.json                  # TypeScript config
├── src/
│   ├── BillingModule.ts           # module definition (ModuleType)
│   ├── controllers/               # @decorator.controller() classes
│   ├── services/                  # injectable services
│   ├── repositories/              # data-access repositories
│   ├── entities/                  # database entities
│   └── middlewares/               # IMiddleware / ISocketMiddleware classes
├── tests/
│   └── BillingModule.spec.ts      # asserts the ModuleType arrays exist
└── bin/                           # optional: seeds and runnable commands

The artifact subfolders under src/ (controllers/, services/, repositories/, entities/, middlewares/) are created on demand as you generate artifacts into the module. A new module starts with just src/<Pascal>Module.ts. The bin/ folder is optional and holds seeds and runnable commands for modules that need them.

Generated files

`src/<Pascal>Module.ts` — the module definition

The heart of the module. It exports a single ModuleType object whose arrays declare what the module contributes to the application. You register each artifact you create by adding it to the matching array.

import type { ModuleType } from "@talosjs/module";

export const BillingModule: ModuleType = {
  controllers: [],
  entities: [],
  middlewares: [],
  cronJobs: [],
  events: [],
};

Each array maps to a kind of artifact and the src/ subfolder where those artifacts live:

`ModuleType` array	Artifact	Lives under
`controllers`	HTTP / WebSocket controllers	`src/controllers/`
`entities`	Database entities	`src/entities/`
`middlewares`	Request middleware	`src/middlewares/`
`cronJobs`	Scheduled jobs	`src/` (cron job classes)
`events`	Event listeners	`src/` (event classes)

Services and repositories are dependency-injected and resolved through the container, so they live under src/services/ and src/repositories/ without a dedicated ModuleType array. See Controller and Entity for those artifact types, and Middleware for the middleware pipeline.

`<name>.yml` — module config

Declares the module’s type. The generator writes type: "module":

type: "module"

The type is one of api, microservice, design, spa, sdk, or module, depending on what kind of unit you scaffold.

`package.json` — workspace package

Each module is its own workspace package named @module/<name>. It starts at version 0.0.1 and ships test, lint, and fmt scripts:

{
  "name": "@module/billing",
  "version": "0.0.1",
  "scripts": {
    "test": "bun test tests",
    "lint": "tsgo --noEmit && bunx biome lint",
    "fmt": "bunx biome check --write"
  }
}

The @module/billing package name doubles as the import-path alias once it is registered in the root tsconfig.json (see Registration).

`tsconfig.json`

The module’s TypeScript configuration, extending the workspace defaults.

`tests/<Pascal>Module.spec.ts` — the mirrored test

Every module ships a test that mirrors the definition and asserts each ModuleType array exists. It guards against a malformed definition by checking that controllers, entities, middlewares, cronJobs, and events are all present on the exported module object. Run it with the package’s test script (bun test tests).

Core modules: `app` and `shared`

Two modules are special and exist in every project:

Module	Role
`app`	The application root. It composes the other modules and is the default destination for generated artifacts that belong to the running app.
`shared`	Cross-cutting code reused across modules: shared services, middleware, and utilities. It is the default target for several generators (for example, `middleware:create` defaults to `shared`).

When you create a module with the app destination, the generator registers it into both AppModule and SharedModule so its artifacts are wired into the application and available to other modules.

Registration

Creating a module is not just file generation. module:create also wires the module into the project:

Registers the module into its destination. For the app destination, it adds the module to AppModule and SharedModule.
Adds the path alias. The @module/<name> import alias is added to the root tsconfig.json, so other code can import the module by its package name.

Next steps

Overview: what a module is and why modules exist.
Composition: how modules are combined into an application.
Create: the module:create command reference.
Controller and Entity: the artifacts you register in the definition.
Middleware: the request pipeline a module contributes to.

Getting Started

AI

Framework

Command Line

Layout

Generated files

`src/<Pascal>Module.ts` — the module definition

`<name>.yml` — module config

`package.json` — workspace package

`tsconfig.json`

`tests/<Pascal>Module.spec.ts` — the mirrored test

Core modules: `app` and `shared`

Registration

Next steps

​Layout

​Generated files

​src/<Pascal>Module.ts — the module definition

​<name>.yml — module config

​package.json — workspace package

​tsconfig.json

​tests/<Pascal>Module.spec.ts — the mirrored test

​Core modules: app and shared

​Registration

​Next steps

Layout

Generated files

`src/<Pascal>Module.ts` — the module definition

`<name>.yml` — module config

`package.json` — workspace package

`tsconfig.json`

`tests/<Pascal>Module.spec.ts` — the mirrored test

Core modules: `app` and `shared`

Registration

Next steps