Starter

The class dedicated to start the project. It automatically mount env configuration and it's the main point of the application.

StarterOptions

The StarterOptions object is used to configure the behavior of the Starter class. It defines how the Express app is initialized, which routers and plugins are used, and other important runtime options.

export type StarterOptions = {
    plugins?:Array<any>,
    routers?:Array<RouterWrapper>,
    clientPath?:string,
    swagger?:boolean,
    projectConfig:ProjectConfigs,
    beforeStartListening?:(app:Express, httpServer?:http.Server, socketIoServerInstance?:Server) => void,
    backgroundServices?:Array<BackgroundService>
    sockets?: {
        wrappers:Array<SocketWrapper>,
        options?:Partial<ServerOptions>
    },
    tokenOptions?: {
        tokenInstance: Token,
        api?:TokenApiOptions
    }
    db?:{
        entities:MixedList<Function | string |EntitySchema>,
        migrations?:string[],
        sync?:boolean,
        afterDbConnection?:() => Promise<void>
    },
}

export type TokenApiOptions = { 
    path?:string, 
    callback:(req:Request, res:Response) => Promise<void> 
}

Properties

plugins?: Array<any>

An array of Express-compatible plugins that will be applied to the app before any routing logic.

routers?: Array<RouterWrapper>

A list of RouterWrapper instances. Check the related section on this doc

Each wrapper defines a group of routes (typically per resource or feature), which will be automatically registered by the framework.

You can think of a RouterWrapper as a module encapsulating route definitions, handlers, and optional middleware.

clientPath?: string

If provided, the given path will be used to serve a static client (e.g., a SPA) on the root route (/).

Additionally, the following utility routes will be mounted:

  • GET /apiUrl — returns the value of the API_URL environment variable.

  • If tokenOptions.api is defined:

    • GET /api/auth (or a custom path) — serves a callback for retrieving authentication-related metadata or performing client login.

swagger?: boolean

If true (or not explicitly set), Swagger UI will be automatically served at:

  • /swagger-ui — the interactive Swagger documentation

  • /swagger — the raw OpenAPI JSON schema

Be sure to set this variable to false in production (use arguments or what you want)

projectConfig: ProjectConfigs

An instance of ProjectConfigs, used to define essential runtime configurations like environment variables, API base paths, service URLs, and more.

Chek the dedicated section of this documetation for env variables

In the template, this is an object with all the process.env.LIB_VAR.

If you need to start a project from scratch without the template, keep using this methods as it automatically hide your secrets from plan code and .env file is required anyway.

This object is required, and it can be extended to include custom environment variables or project-specific configuration values.

The framework relies on this configuration to set up the base environment and connect other internal utilities.

sockets?: {
    wrappers:Array<SocketWrapper>,
    options?:Partial<ServerOptions>
},

Expresso-macchiato uses socket-io for socket comunication.

If undefined nothing happens, but if you want to mount some socket you can use the SocketWrapper class (check the related section on this guide) and mounting and array of those instances in the wrapper prop.

Use the options for the classic socket-io options

beforeStartListening?:(app:Express, httpServer?:http.Server, socketIoServerInstance?:Server) => void,

A callback function that is executed just before the server starts listening.

This is useful if you need to perform any custom-operation you want.

The Express app instance is passed to the callback, allowing full control over the server setup.

If you specifiy sockets prop in the constructor, there will be also passed the last two params for any custom operation

tokenOptions?: {
  tokenInstance: Token,
  api?: TokenApiOptions
}

Defines the authentication strategy based on a Token class instance.

  • tokenInstance: a required instance of your Token class (described in detail in a dedicated section).

  • api: optional configuration to expose a custom token-based authentication endpoint.

If the api field is defined:

  • A route will be mounted at the specified path (defaulting to /api/auth if none is given).

  • The provided callback will be executed when the route is hit, just like a normal Express handler.

If api is not provided, no authentication route is exposed by default.

db?: {
  entities: MixedList<Function | string | EntitySchema>,
  migrations?: string[],
  sync?: boolean,
  afterDbConnection?: () => Promise<void>
}

Database configuration options for setting up the connection and managing entities.

  • entities: required list of database entities, expressed as class constructors, paths, or EntitySchema objects.

  • migrations: optional list of migration script paths.

  • sync: if true, the schema is automatically synchronized at startup and the migrations are ignored (not recommended in production).

  • afterDbConnection: optional callback executed after the database connection is established, allowing custom setup logic like seeding or logging.

backgroundServices?:Array<BackgroundService>

You can use the simple BackgroundService class of this framework to create some background services. (check the related section of this guide)

PreviousUtilitiesNextRouterWrapper

Last updated