@breadstone/archipel-platform-bootstrap

Application composition layer for NestJS backends built with Archipel. It centralizes startup concerns that usually drift into app-level bootstrap.ts files: API defaults, Express middleware, security, sessions, OpenAPI setup, and test helpers.

The package is intentionally consumed through subpath exports so applications only import the runtime pieces they use.

Entry Points

| Import | Purpose | | -------------------------------------------------------- | ---------------------------------------------------- | | @breadstone/archipel-platform-bootstrap | Core builder, API step, config keys | | @breadstone/archipel-platform-bootstrap/composition | Stage-aware module composition context | | @breadstone/archipel-platform-bootstrap/server/express | Express-compatible body parsing and compression | | @breadstone/archipel-platform-bootstrap/security | CORS, Helmet, content-security-policy, rate limiting | | @breadstone/archipel-platform-bootstrap/session | Express-compatible session middleware | | @breadstone/archipel-platform-bootstrap/openapi | Archipel multi-document OpenAPI setup | | @breadstone/archipel-platform-bootstrap/testing | Lightweight bootstrap testing helpers |

Quick Start

Keep NestJS application creation in your app entrypoint and let Archipel compose the rest:

import { ConsoleLogger } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { ExpressAdapter, NestExpressApplication } from '@nestjs/platform-express';
import { PlatformApplication, useApi } from '@breadstone/archipel-platform-bootstrap';
import { useExpressServer } from '@breadstone/archipel-platform-bootstrap/server/express';
import { useSecurity } from '@breadstone/archipel-platform-bootstrap/security';
import { useSession } from '@breadstone/archipel-platform-bootstrap/session';
import { useOpenApi } from '@breadstone/archipel-platform-bootstrap/openapi';
import { AppModule } from './AppModule';

async function main(): Promise<void> {
    const app = await NestFactory.create<NestExpressApplication>(AppModule, new ExpressAdapter(), {
        logger: new ConsoleLogger({ prefix: 'API', colors: true, forceConsole: true, compact: true, sorted: true }),
    });

    await PlatformApplication.from(app)
        .use(useApi({ prefix: 'api' }))
        .use(useExpressServer({ json: { limit: '1mb' }, urlEncoded: { extended: true, limit: '1mb' } }))
        .use(useSecurity({ contentSecurityPolicy: 'swagger-compatible' }))
        .use(useSession())
        .use(useOpenApi())
        .listenFromConfig({ fallbackPort: 3000 });
}

void main();

Configuration Entries

Use the exported config entries with ConfigModule.register() so startup fails early when required values are missing.

| Entry | Keys | | ---------------------------------- | ---------------------------------------------------------------------------- | | PLATFORM_SERVER_CONFIG_ENTRIES | PORT | | PLATFORM_SECURITY_CONFIG_ENTRIES | APP_CORS_ORIGIN, APP_RATE_LIMIT_WINDOW_MS, APP_RATE_LIMIT_MAX_REQUESTS | | PLATFORM_SESSION_CONFIG_ENTRIES | AUTH_SESSION_SECRET, AUTH_SESSION_SECURE, AUTH_SESSION_MAX_AGE |

listenFromConfig() resolves ports in this order by default: PORT, then APP_PORT, then the provided fallback.

Stage-Aware Composition

For applications that need to select infrastructure modules based on environment or configuration, use the composition subpath:

import { PlatformApplicationBuilder, useApi, CompositionImport } from '@breadstone/archipel-platform-bootstrap';
import { ExpressAdapter, NestExpressApplication } from '@nestjs/platform-express';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './AppModule';

async function main(): Promise<void> {
    const builder = await PlatformApplicationBuilder.createWithComposition<NestExpressApplication>(
        async (context) => {
            const imports: CompositionImport[] = [AppModule];

            const driver = context.tryGetConfigValue({ key: 'MAIL_DRIVER' }, 'log');
            if (driver === 'smtp') {
                const { MailModule } = await import('@breadstone/archipel-platform-mailing');
                const { SmtpDeliveryStrategy } = await import('@breadstone/archipel-platform-mailing/delivering/smtp');
                imports.push(MailModule.register({ deliveryStrategy: SmtpDeliveryStrategy }));
            }

            return imports;
        },
        {
            appFactory: (module) => NestFactory.create<NestExpressApplication>(module, new ExpressAdapter()),
        },
    );

    await builder.use(useApi({ prefix: 'api' })).listenFromConfig({ fallbackPort: 3000 });
}

The composition context bootstraps a lightweight NestJS context with only configuration services, reads environment values, and returns the modules to import. The context is automatically closed after composition completes.

For more complex scenarios, create a custom CompositionResolver class that encapsulates all provider selection logic.

Design Notes

• PlatformApplication.from(app) wraps an existing NestJS app, which keeps NestFactory and platform adapters visible in the consuming main.ts.
• Bootstrap functions are named use* and return PlatformBootstrapStep instances. They compose the application pipeline and can be tested independently.
• Express-specific middleware lives in server/express so future server integrations can be added without forcing extra dependencies into the root import.

Local Development

yarn nx run platform-bootstrap:build
yarn nx run platform-bootstrap:test