Package Exports

@fnd-platform/pipeline
@fnd-platform/pipeline/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@fnd-platform/pipeline) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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: ['admin@example.com'] }),
  })
);

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: 'ops@example.com',
});

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)

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

License

MIT