migrating-to-toolkit-recipe

Migrate to Andercore Toolkit

Quick Reference

Step	Action	File
Install	pnpm add @andercore/toolkit	package.json
Bootstrap	Replace main.ts with bootstrap()	main.ts
Config	Replace ConfigModule with AndercoreToolkitModule	app.module.ts
Logging	Replace Logger with toolkit Logger	**/*.ts
Metrics	Replace Datadog with MetricsModule	app.module.ts
Tracing	Add @Trace() decorators	service/**/*.ts
HTTP	Replace axios with HttpClientModule	app.module.ts

When to Use

Toolkit integration | Datadog migration | logger replacement | bootstrap setup | observability migration

Migration Workflow

Execute in order - NO parallel steps:

1. Install toolkit
2. Replace main.ts with bootstrap()
3. Migrate configuration
4. Replace loggers
5. Migrate metrics (Datadog → MetricsModule)
6. Migrate tracing (Datadog → @Trace)
7. Replace HTTP clients (optional)
8. Test & validate
9. Remove old dependencies

Step 1: Install Toolkit

pnpm add @andercore/toolkit
pnpm add -D @types/node

Verify:

pnpm list @andercore/toolkit

Step 2: Replace main.ts

BEFORE:

import { NestFactory } from '@nestjs/core'
import { ValidationPipe } from '@nestjs/common'
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  app.enableCors()
  app.useGlobalPipes(new ValidationPipe())
  app.enableVersioning({ type: VersioningType.URI })

  const config = new DocumentBuilder().setTitle('API').build()
  const document = SwaggerModule.createDocument(app, config)
  SwaggerModule.setup('api-docs', app, document)

  await app.listen(3000)
}
bootstrap()

AFTER:

import { bootstrap } from '@andercore/toolkit'
import { AppModule } from './app.module'

bootstrap({
  appModule: AppModule,
  cors: { origin: '*', credentials: true },
  versioning: { type: 'uri', prefix: 'v' },
  swagger: { title: 'API', description: 'Description', version: '1.0.0' }
})

→ See bootstrap-recipe

Step 3: Migrate Configuration

BEFORE:

import { ConfigModule } from '@nestjs/config'

@Module({
  imports: [ConfigModule.forRoot({ validationSchema })]
})

AFTER:

import { AndercoreToolkitModule } from '@andercore/toolkit'

@Module({
  imports: [
    AndercoreToolkitModule.forRoot({
      config: { schema: configSchema, envFilePath: '.env' }
    })
  ]
})

→ See configuration-recipe

Step 4: Replace Loggers

See logger-migration.md for:

• Find & replace patterns
• NestJS Logger → toolkit Logger
• console.log removal
• Buffered vs standalone logging
• Testing logger mocks

Step 5: Migrate Metrics

See metrics-migration.md for:

• Datadog StatsD → MetricsModule
• hot-shots → @Metric() decorator
• Metric naming (SemConv)
• Cardinality control
• Testing metrics

Step 6: Migrate Tracing

See tracing-migration.md for:

• Datadog APM → @Trace()
• Manual spans → TracingService
• Instrumentation setup
• SemConv attributes
• Testing traces

Step 7: Replace HTTP Clients (Optional)

BEFORE:

import axios from 'axios'

const response = await axios.get(url, { headers: { Authorization: token } })

AFTER:

import { HttpClientModule, InjectHttpClient, HttpClient } from '@andercore/toolkit'

@Injectable()
export class ApiService {
  constructor(@InjectHttpClient('api') private http: HttpClient) {}

  getData(): Task<Data, ApiError> {
    return this.http.get('/data')
      .map(res => res.data)
  }
}

→ See http-client-recipe

Step 8: Testing

Unit tests:

// Mock Logger
const loggerMock = { info: jest.fn(), error: jest.fn(), debug: jest.fn(), warn: jest.fn() }

// Mock Metrics
const counterMock = { add: jest.fn() }
provide: 'METRIC_user.created', useValue: counterMock

// Mock HttpClient
const httpMock = { get: jest.fn(() => Task.succeed({ data: {} })) }
provide: 'HTTP_CLIENT_user-api', useValue: httpMock

Integration tests:

import { Test } from '@nestjs/testing'

const module = await Test.createTestingModule({
  imports: [
    AndercoreToolkitModule.forRoot({ config: { schema: testSchema } }),
    MetricsModule.forRoot({ metrics: testMetrics }),
    HttpClientModule.forRoot({ clients: testClients })
  ]
}).compile()

→ See typescript-services:test-code-recipe

Step 9: Cleanup

pnpm remove dd-trace hot-shots @datadog/datadog-api-client axios @nestjs/config

git rm -r src/config/  # If using toolkit config
git rm -r src/logging/  # If using toolkit logger
git rm -r src/metrics/  # If using toolkit metrics
git rm -r src/tracing/  # If using toolkit tracing

grep -r "dd-trace\|hot-shots\|datadog" src/
# Should return empty

Validation Workflow

1. Run migration steps 1-9
2. Execute tests → All pass?
3. Run application locally → Observability signals exported?
4. Check OTLP collector → Metrics/traces/logs received?
5. Remove old code → Verify no imports remain

PASS → Commit migration | FAIL → Debug step

Common Issues

Issue	Cause	Fix
Metrics not exported	Missing --require instrumentation.js	Add to package.json start script
Logger not buffering	Missing LoggerInterceptor	Add to controllers
Config validation fails	Incomplete schema	Add all env vars to configSchema
Tests fail	Old mocks	Update mock patterns
Tracing not working	Missing OTEL_EXPORTER_OTLP_ENDPOINT	Add to .env
HTTP requests fail	Wrong client name	Match @InjectHttpClient() with clients[].name

Migration Rollback

If migration fails:

git checkout main -- main.ts app.module.ts
pnpm add dd-trace hot-shots axios @nestjs/config
pnpm remove @andercore/toolkit

Incremental rollback:

Revert component by component (reverse order):
HTTP clients → Tracing → Metrics → Logging → Config → Bootstrap

Reference

Toolkit modules:

• bootstrap() - Unified app initialization
• AndercoreToolkitModule - Configuration management
• MetricsModule - OpenTelemetry metrics
• HttpClientModule - Resilient HTTP clients
• Logger - Structured logging
• @Trace() - Method tracing

Replaces:

• @nestjs/config → AndercoreToolkitModule
• @nestjs/common Logger → toolkit Logger
• dd-trace → @Trace() + TracingService
• hot-shots/statsd → MetricsModule + @Metric()
• axios → HttpClientModule
• Manual Swagger setup → bootstrap({ swagger })

Related recipes:

• andercore-toolkit-services:bootstrap-recipe
• andercore-toolkit-services:configuration-recipe
• andercore-toolkit-services:observability-recipe
• andercore-toolkit-services:http-client-recipe
• andercore-toolkit-services:swagger-recipe