@fnd-platform/pipeline

CDK Pipeline constructs for automated CI/CD deployments in fnd-platform applications. Provides CodePipeline integration with multi-stage deployment, caching, and build metrics.

Installation

npm install @fnd-platform/pipeline
# or
pnpm add @fnd-platform/pipeline

Quick Start

import * as cdk from 'aws-cdk-lib';
import {
  FndPipeline,
  createGitHubSource,
  createDevStage,
  createProdStage,
} from '@fnd-platform/pipeline';

const app = new cdk.App();

const pipeline = new FndPipeline(app, 'Pipeline', {
  appName: 'my-app',
  source: createGitHubSource({
    owner: 'my-org',
    repo: 'my-repo',
    branch: 'main',
    connectionArn: 'arn:aws:codestar-connections:...',
  }),
});

// Add deployment stages
pipeline.addStage(
  createDevStage({
    env: { account: '111111111111', region: 'us-east-1' },
  })
);

pipeline.addStage(
  createProdStage({
    env: { account: '222222222222', region: 'us-east-1' },
    manualApproval: true,
  })
);

Features

• CodePipeline Integration - Native AWS CI/CD with CDK
• Multi-Stage Deployment - Dev, staging, production environments
• Source Providers - GitHub (OAuth, CodeStar) and CodeCommit
• Build Caching - pnpm store, NX cache, and Docker layer caching
• Build Metrics - CloudWatch metrics and alarms
• Manual Approvals - Production gate approvals
• Post-Deploy Validation - Smoke tests and health checks

Source Configuration

GitHub with CodeStar Connection

import { createGitHubSource } from '@fnd-platform/pipeline';

const source = createGitHubSource({
  owner: 'my-org',
  repo: 'my-repo',
  branch: 'main',
  connectionArn: 'arn:aws:codestar-connections:us-east-1:123456789:connection/xxx',
});

GitHub with OAuth

const source = createGitHubSource({
  owner: 'my-org',
  repo: 'my-repo',
  branch: 'main',
  oauthToken: cdk.SecretValue.secretsManager('github-token'),
});

CodeCommit

import { createCodeCommitSource } from '@fnd-platform/pipeline';

const source = createCodeCommitSource({
  repositoryName: 'my-repo',
  branch: 'main',
});

Multi-Stage Deployment

Using Stage Helpers

import {
  createDevStage,
  createStagingStage,
  createProdStage,
  withManualApproval,
  withSmokeTest,
} from '@fnd-platform/pipeline';

// Dev stage - auto deploys
pipeline.addStage(
  createDevStage({
    env: { account: '111111111111', region: 'us-east-1' },
  })
);

// Staging with smoke tests
pipeline.addStage(
  createStagingStage({
    env: { account: '111111111111', region: 'us-east-1' },
    ...withSmokeTest({ endpoint: 'https://staging.example.com/health' }),
  })
);

// Production with manual approval
pipeline.addStage(
  createProdStage({
    env: { account: '222222222222', region: 'us-east-1' },
    ...withManualApproval({ approvers: ['[email protected]'] }),
  })
);

Custom Stage

import { FndDeploymentStage } from '@fnd-platform/pipeline';

const customStage = new FndDeploymentStage(app, 'CustomStage', {
  stageName: 'custom',
  env: { account: '333333333333', region: 'eu-west-1' },
  environmentVariables: {
    FEATURE_FLAG_X: 'true',
  },
});

pipeline.addStage(customStage);

Build Configuration

Custom Build Commands

import { getBuildCommands } from '@fnd-platform/pipeline';

const pipeline = new FndPipeline(app, 'Pipeline', {
  appName: 'my-app',
  source: source,
  buildCommands: getBuildCommands({
    install: ['pnpm install --frozen-lockfile'],
    build: ['pnpm build', 'pnpm test'],
    synth: ['cd packages/infra && pnpm cdk synth'],
  }),
});

Build Defaults

import {
  DEFAULT_INSTALL_COMMANDS,
  DEFAULT_BUILD_COMMANDS,
  DEFAULT_TEST_COMMANDS,
  DEFAULT_SYNTH_COMMANDS,
} from '@fnd-platform/pipeline';

// Defaults:
// Install: ['pnpm install --frozen-lockfile']
// Build: ['pnpm build']
// Test: ['pnpm test']
// Synth: ['pnpm cdk synth']

Caching

Default Cache Paths

import { DEFAULT_CACHE_PATHS, getCachePaths } from '@fnd-platform/pipeline';

// Default cache paths include:
// - node_modules/.cache
// - .nx/cache
// - pnpm store

const cachePaths = getCachePaths({
  mode: 'full', // 'minimal' | 'full'
  includeDocker: true,
});

NX Cloud Integration

const pipeline = new FndPipeline(app, 'Pipeline', {
  appName: 'my-app',
  source: source,
  nxCloud: {
    accessToken: cdk.SecretValue.secretsManager('nx-cloud-token'),
  },
});

Build Metrics

Automatic Metrics

import { FndBuildMetrics } from '@fnd-platform/pipeline';

const metrics = new FndBuildMetrics(this, 'Metrics', {
  pipelineName: 'my-pipeline',
  alarmOnFailure: true,
  failureThreshold: 3,
  notificationEmail: '[email protected]',
});

Metric Defaults

import { DEFAULT_METRICS_NAMESPACE, DEFAULT_FAILURE_THRESHOLD } from '@fnd-platform/pipeline';

// Namespace: 'FndPipeline'
// Failure threshold: 3 consecutive failures

API Reference

See the full API documentation for detailed type definitions and examples.

Main Construct

import { FndPipeline } from '@fnd-platform/pipeline';

Source Utilities

import {
  createGitHubSource,
  createCodeCommitSource,
  isGitHubSource,
  isCodeCommitSource,
} from '@fnd-platform/pipeline';

Build Commands

import {
  getBuildCommands,
  getPrimaryOutputDirectory,
  DEFAULT_PNPM_STORE_CONFIG,
  DEFAULT_INSTALL_COMMANDS,
  DEFAULT_BUILD_COMMANDS,
  DEFAULT_TEST_COMMANDS,
  DEFAULT_SYNTH_COMMANDS,
  DEFAULT_PRIMARY_OUTPUT_DIRECTORY,
} from '@fnd-platform/pipeline';

Caching

import { DEFAULT_CACHE_PATHS, DOCKER_CACHE_PATHS, getCachePaths } from '@fnd-platform/pipeline';

Metrics

import {
  FndBuildMetrics,
  DEFAULT_METRICS_NAMESPACE,
  DEFAULT_FAILURE_THRESHOLD,
} from '@fnd-platform/pipeline';

Multi-Stage Deployment

import {
  FndDeploymentStage,
  // Stage creation helpers
  createDevStage,
  createStagingStage,
  createProdStage,
  // Stage modifiers
  withManualApproval,
  withPostDeployValidation,
  withSmokeTest,
  // Utilities
  isStandardStageName,
  validateStageConfig,
  mergeStageOptions,
  addFndStage,
  configureMultiStagePipeline,
  // Stage defaults
  DEV_STAGE_DEFAULTS,
  STAGING_STAGE_DEFAULTS,
  PROD_STAGE_DEFAULTS,
} from '@fnd-platform/pipeline';

Types

import type {
  // Pipeline types
  FndPipelineProps,
  BuildCommandsConfig,
  // Source types
  FndSourceConfig,
  GitHubSourceConfig,
  GitHubConnectionSourceConfig,
  GitHubOAuthSourceConfig,
  CodeCommitSourceConfig,
  // Cache types
  CacheMode,
  FndCacheConfig,
  FndNxCloudConfig,
  // Metrics types
  FndBuildMetricsConfig,
  FndBuildMetricsProps,
  // Stage types
  StandardStageName,
  StageName,
  StageEnvironmentVariables,
  StageEnvironmentConfig,
  StackBuilderCallback,
  FndDeploymentStageProps,
  StageConfig,
  MultiStagePipelineConfig,
  AddFndStageOptions,
  StageConfigValidationError,
  StageConfigValidationResult,
  ManualApprovalOptions,
  PostDeployValidationOptions,
  SmokeTestOptions,
} from '@fnd-platform/pipeline';

Requirements

• Node.js 20+
• AWS CDK v2
• AWS CLI configured with credentials
• CodeStar Connection (for GitHub)

Related

• @fnd-platform/constructs - CDK constructs
• @fnd-platform/api - API package
• AWS CDK Pipelines

License

MIT