@flusys/nestjs-core

Foundation infrastructure for NestJS applications — environment config, TypeORM migrations, and Swagger setup.

Installation

npm install @flusys/nestjs-core
npm install typeorm typeorm-naming-strategies dotenv
npm install -D ts-node tsconfig-paths

1. Environment Config

Access typed environment variables via the envConfig singleton — no class instantiation needed.

import { envConfig } from '@flusys/nestjs-core';

const port    = envConfig.getPort();           // number
const db      = envConfig.getTypeOrmConfig();  // { host, port, username, password, database }
const jwt     = envConfig.getJwtConfig();      // { secret, expiration, refreshSecret, ... }
const origins = envConfig.getOrigins();        // string[]
const isProd  = envConfig.isProduction();      // boolean
 public tryGetValue(key: string, throwOnMissing = false): string // get env value

2. Migrations

Create src/persistence/migration.config.ts

import { createMigrationDataSource, IMigrationConfig } from '@flusys/nestjs-core';
import { envConfig } from '@flusys/nestjs-core/config';
import { getAuthEntitiesByConfig } from '@flusys/nestjs-auth';
import { getIAMEntitiesByConfig } from '@flusys/nestjs-iam';

const bootstrapConfig = {
  databaseMode: 'single' as const,
  enableCompanyFeature: true,
  permissionMode: 'FULL' as const,
};

export const migrationConfig: IMigrationConfig = {
  defaultDatabaseConfig: envConfig.getTypeOrmConfig(),
  bootstrapAppConfig: bootstrapConfig,
  migrationsPath: `${__dirname}/migrations`,
  migrationsTableName: 'migrations',
  entities: [
    ...getAuthEntitiesByConfig(bootstrapConfig),
    ...getIAMEntitiesByConfig(bootstrapConfig),
  ],
};

// Required for TypeORM CLI
export default createMigrationDataSource({
  config: migrationConfig,
  tenantId: process.env.TENANT_ID,
});

Add scripts to package.json

{
  "scripts": {
    "migration":          "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/migration/cli --config=src/persistence/migration.config.ts",
    "migration:generate": "npm run migration -- generate",
    "migration:run":      "npm run migration -- run",
    "migration:revert":   "npm run migration -- revert",
    "migration:status":   "npm run migration -- status",
    "migration:run:all":    "npm run migration -- run:all",
    "migration:revert:all": "npm run migration -- revert:all",
    "migration:status:all": "npm run migration -- status:all"
  }
}

Run

# Single database
npm run migration:generate -- --name=CreateUsersTable
npm run migration:run
npm run migration:revert
npm run migration:status

# Tenant-specific (prefix with TENANT_ID)
TENANT_ID=tenant-1 npm run migration:generate -- --name=CreateUsersTable
TENANT_ID=tenant-1 npm run migration:run
TENANT_ID=tenant-1 npm run migration:revert
TENANT_ID=tenant-1 npm run migration:status

# All tenants at once
npm run migration:run:all
npm run migration:revert:all
npm run migration:status:all

3. Swagger

setupSwaggerDocs and setupModuleSwaggerDocs accept the same IModuleSwaggerOptions shape.

import { NestFactory } from '@nestjs/core';
import { setupSwaggerDocs, setupModuleSwaggerDocs } from '@flusys/nestjs-core/docs';
import { AuthModule } from '@flusys/nestjs-auth';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // All available options (one entry showing every field)
  setupModuleSwaggerDocs(app, [
    {
      title: 'Auth API',               // required
      description: 'Auth endpoints',   // required
      version: '1.0',                  // optional, default '1.0'
      path: 'api/docs/auth',           // required — URL where docs are served
      bearerAuth: true,                // adds Authorization header to Swagger UI
      modules: [AuthModule],           // scope to specific NestJS modules only

      // Exclude controllers by @ApiTags name
      excludeTags: ['Internal', 'Health'],

      // Exclude specific paths (supports * and ** wildcards)
      excludePaths: ['/api/auth/internal/*', '/api/health'],

      // Exclude properties from a DTO schema
      excludeSchemaProperties: [
        { schemaName: 'CreateUserDto', properties: ['passwordHash', 'salt'] },
      ],

      // Exclude query parameters from specific endpoints
      excludeQueryParameters: [
        { pathPattern: '/api/auth/*', method: 'post', parameters: ['debug'] },
      ],

      // Exclude named examples from responses
      excludeExamples: [
        { pathPattern: '/api/auth/login', examples: ['AdminExample'] },
      ],

      // Add a custom header to every request in Swagger UI
      globalHeaders: [
        { name: 'x-tenant-id', description: 'Tenant identifier', required: false, example: 'tenant-1' },
      ],
    },

    // Minimal entry
    { title: 'IAM API', description: 'Roles and permissions', path: 'api/docs/iam' },
  ]);

  await app.listen(3000);
}

License

MIT © FLUSYS