import "reflect-metadata";
import { AppFactory } from "./core";

4. Module resolution - If you alias @core, configure tsconfig-paths or module-alias so the runtime resolves it. For plain tsc output, use relative paths or tsconfig-paths/register.

5. Environment - ServerEnvironment.Development / ServerEnvironment.Production are the two valid env values. Set your environment at app creation time, not via a bare string.

Public API

AppFactory

class AppFactory {
  static create(
    container: AppContainer,
    middlewarePipeline: Array<express.RequestHandler>,
    environment?: ServerEnvironment
  ): Promise<void>;
}

Bootstrap entry point. Call AppFactory.create once in your application entry file, passing a configured AppContainer, your Express middleware array, and an optional server environment. It wires the DI container to an Express application and starts listening.

AppContainer

class AppContainer {
  create(
    modules: Array<ContainerModule>,
    options?: interfaces.ContainerOptions
  ): Container;
}

Wraps the Inversify Container. Use AppContainer to assemble one or more ContainerModule groups before passing the result to AppFactory. Keeps container configuration declarative and separate from bootstrap logic.

CreateModule

function CreateModule(
  bindings: Array<interfaces.Newable<unknown>>,
  scope?: BindingScopeEnum
): ContainerModule;

Factory that converts an array of injectable classes into an Inversify ContainerModule. Pass the resulting module to AppContainer.create. The optional scope argument (from the exported scope object) overrides the default binding scope for every class in the array.

ServerEnvironment

enum ServerEnvironment {
  Development = "development",
  Production = "production",
}

Typed enum controlling framework behavior (logging verbosity, error detail). Pass to AppFactory.create; never use raw strings.

Console

class Console {
  messageServer(port: number, env: ServerEnvironment, msg: string): void;
  log(message: IConsoleMessage): void;
}

Structured logger that formats output consistently. Use messageServer inside your app's serverShutdown / serverListen hooks for uniform startup banners.

Working examples

Scenario - Minimal application bootstrap

A single-module application with one injectable service, wired end-to-end.

import "reflect-metadata";
import { AppContainer, AppFactory, ServerEnvironment, CreateModule } from "./core";
import { injectable } from "./core"; // re-exported from di/inversify

@injectable()
class GreetService {
  greet(): string {
    return "Hello from ExpressoTS";
  }
}

async function bootstrap() {
  const container = new AppContainer();

  const appModule = CreateModule([GreetService]);

  const app = container.create([appModule]);

  await AppFactory.create(app, [], ServerEnvironment.Development);
}

bootstrap();

Scenario - Multiple scoped modules

Group bindings by feature domain and control lifetime with the scope helper.

import "reflect-metadata";
import {
  AppContainer,
  AppFactory,
  CreateModule,
  ServerEnvironment,
  scope,
} from "./core";
import { injectable } from "./core";

@injectable()
class UserRepository {}

@injectable()
class OrderRepository {}

@injectable()
class AuthService {}

async function bootstrap() {
  const container = new AppContainer();

  const userModule = CreateModule([UserRepository], scope.Request);
  const orderModule = CreateModule([OrderRepository], scope.Request);
  const authModule = CreateModule([AuthService], scope.Singleton);

  const app = container.create([userModule, orderModule, authModule]);

  await AppFactory.create(app, [], ServerEnvironment.Production);
}

bootstrap();

Scenario - Structured console logging on startup

Use Console to emit a typed startup message after the application initialises.

import "reflect-metadata";
import {
  AppContainer,
  AppFactory,
  ServerEnvironment,
  CreateModule,
  Console,
} from "./core";

const logger = new Console();

async function bootstrap() {
  const container = new AppContainer();
  const app = container.create([CreateModule([])]);

  await AppFactory.create(app, [], ServerEnvironment.Development);

  logger.messageServer(3000, ServerEnvironment.Development, "App is running");
}

bootstrap();

File walkthrough

• index.ts - Barrel that re-exports every sub-module; import from here in application code.
• application/ - Contains AppFactory (bootstrap), AppContainer (DI wiring), and ServerEnvironment enum.
• console/ - Console class for formatted terminal output; IConsoleMessage interface from @expressots/shared.
• container-module/ - CreateModule factory and scope constants for grouping and scoping bindings.
• decorator/ - Scope-binding decorators built on top of Inversify annotations.
• di/ - Internalized Inversify DI engine: annotations (inject, injectable, named, etc.), container, bindings, planner, resolver, and syntax builders.
• error/ - Application-level typed error classes used by the framework's error handling pipeline.
• middleware/ - Express middleware registration utilities integrated with the DI container.
• provider/ - Provider base classes for wrapping third-party services in the DI graph.

Common pitfalls and fixes

• reflect-metadata not first - Decorator metadata is undefined at runtime; fix: import "reflect-metadata" must be the absolute first line of your entry file, before any other import.
• emitDecoratorMetadata missing - @injectable() silently fails or throws "missing required @injectable annotation"; fix: set both experimentalDecorators: true and emitDecoratorMetadata: true in tsconfig.json.
• ESM/CJS interop - reflect-metadata is CJS; if your project targets ESM ("module": "ESNext", "type": "module"), use a bundler (esbuild, webpack) or switch module to commonjs.
• Duplicate reflect-metadata - Multiple packages bundling their own copy causes metadata keying conflicts; fix: deduplicate via npm dedupe or a bundler alias.
• @expressots/shared missing - console/index.ts re-exports IConsoleMessage from @expressots/shared; install it explicitly even though it is a transitive dep.
• Scope constant misuse - Passing a raw string like "singleton" instead of scope.Singleton produces a binding that silently falls back to transient; always use the exported scope object.

Vibe-coding prompt template

I have purchased the ExpressoTS Core Framework block. The source lives at
`src/core/` in my project, and the integration guide is `USAGE.md` alongside it.
The upstream package is `@expressots/core@3.0.0`.

Please integrate this source into my existing Node.js + TypeScript + Express project
step by step:

1. Read USAGE.md and `src/core/index.ts` to understand all public exports.
2. Update my `tsconfig.json` to enable `experimentalDecorators` and `emitDecoratorMetadata`.
3. Add `import "reflect-metadata"` as the first line of my entry file.
4. Replace any existing Express bootstrap code with `AppFactory.create`, using
   `AppContainer` and `CreateModule` to register my services.
5. Migrate my injectable classes to use the `@injectable()` decorator from `src/core`.
6. Wire my middleware array into `AppFactory.create`.
7. Use `Console.messageServer` for startup logging.
8. Show me the final entry file and one example module file.
Do not invent any API not present in USAGE.md or the source files.

License and credit

Distributed under the MIT License. See the LICENSE.md in the upstream repository for full terms.

Upstream package: @expressots/core by the ExpressoTS organization. Source repository: https://github.com/expressots/expressots.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

NestJS Progressive Node.js Backend Framework

Automation, Utilities & Developer Tools

Free