cdk2env (@heiwa4126/cdk2env)

Convert AWS CDK outputs.json to shell-sourceable export file. Provides both CLI tool and programmatic API with dual ESM/CJS support.

Quick Start

Typical workflow with AWS CDK (TypeScript):

// lib/my-stack.ts
import * as cdk from "aws-cdk-lib";
import * as s3 from "aws-cdk-lib/aws-s3";
import * as apigateway from "aws-cdk-lib/aws-apigateway";

export class MyStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const bucket = new s3.Bucket(this, "MyBucket");
    const api = new apigateway.RestApi(this, "MyApi");

    // Export values as CDK outputs
    new cdk.CfnOutput(this, "BucketName", {
      value: bucket.bucketName,
      description: "S3 Bucket Name",
    });

    new cdk.CfnOutput(this, "ApiEndpoint", {
      value: api.url,
      description: "API Gateway Endpoint",
    });
  }
}

# 1. Deploy CDK stack and save outputs
cdk deploy --outputs-file var/outputs.json

# 2. Convert outputs to shell format
npx @heiwa4126/cdk2env

# 3. Load environment variables
source var/outputs.sh

# 4. Use in your scripts
aws s3 ls s3://$CDK_MYSTACK_BUCKETNAME
curl $CDK_MYSTACK_APIENDPOINT

Features

• 🚀 CLI & Library: Use as a command-line tool or programmatic API
• 📦 Dual Module Support: Works with both ES Modules and CommonJS
• 🔒 Shell-Safe: Automatic escaping prevents shell injection attacks
• ⚡ Zero Dependencies: Built with Node.js standard library only
• 📝 TypeScript: Full type definitions included
• ✅ Well Tested: Comprehensive test coverage

Installation

Global (CLI)

npm install -g @heiwa4126/cdk2env
# or
pnpm add -g @heiwa4126/cdk2env

Local (Library)

npm install --save-dev @heiwa4126/cdk2env
# or
pnpm add -D @heiwa4126/cdk2env

Usage

CLI

# Default: var/outputs.json → var/outputs.sh
cdk2env

# Custom input file
cdk2env path/to/outputs.json

# Custom input and output
cdk2env path/to/outputs.json path/to/exports.sh

# Show help
cdk2env --help

# Show version
cdk2env --version

Using with npx/pnpx (without installation)

# Run directly with npx
npx @heiwa4126/cdk2env

# Or with pnpm
pnpx @heiwa4126/cdk2env

# With custom paths
npx @heiwa4126/cdk2env path/to/outputs.json path/to/exports.sh

Library API

ES Modules

import { convertOutputsToShell } from "@heiwa4126/cdk2env";

await convertOutputsToShell({
  inputPath: "var/outputs.json",
  outputPath: "var/outputs.sh",
});

CommonJS

const { convertOutputsToShell } = require("@heiwa4126/cdk2env");

await convertOutputsToShell({
  inputPath: "var/outputs.json",
  outputPath: "var/outputs.sh",
});

TypeScript

import { convertOutputsToShell, type ConvertOptions } from "@heiwa4126/cdk2env";

const options: ConvertOptions = {
  inputPath: "var/outputs.json",
  outputPath: "var/outputs.sh",
  prefix: "APP_", // Custom prefix (default: 'CDK_')
};

await convertOutputsToShell(options);

Example Workflow

# 1. Deploy CDK and generate outputs
cdk deploy --outputs-file var/outputs.json

# 2. Convert to shell format
cdk2env

# 3. Source the generated file
source var/outputs.sh

# 4. Use environment variables
echo $CDK_MYSTACK_APIENDPOINT
curl $CDK_MYSTACK_APIENDPOINT/health

Input/Output Format

Input: CDK outputs.json

{
  "MyStack": {
    "ApiEndpoint": "https://abc123.execute-api.us-east-1.amazonaws.com",
    "BucketName": "my-bucket-abc123"
  }
}

Output: Shell export file

#!/usr/bin/env bash
# Auto-generated from CDK outputs.json. Do not edit manually.

export CDK_MYSTACK_APIENDPOINT='https://abc123.execute-api.us-east-1.amazonaws.com'
export CDK_MYSTACK_BUCKETNAME='my-bucket-abc123'

Variable Naming Convention

• Prefix: CDK_ (customizable via API)
• Format: CDK_STACKNAME_OUTPUTKEY (uppercase)
• Special characters → _
• Example: MyStack.ApiEndpoint → CDK_MYSTACK_APIENDPOINT

Security

All values are wrapped in single quotes with proper escaping:

// Input
{
  "Stack": {
    "Message": "It's a test! $(whoami)"
  }
}

// Output (safe)
export CDK_STACK_MESSAGE='It'\''s a test! $(whoami)'

Development

# Install dependencies
pnpm install

# Build (tsup generates ESM + CJS)
pnpm run build

# Test (vitest)
pnpm test
pnpm run test:watch  # Watch mode

# Lint & Format (Biome)
pnpm run lint
pnpm run format

# Smoke test (verify all module formats work)
pnpm run smoke-test

# All checks before publish
pnpm run prepublishOnly

Project Structure

• Package manager: pnpm (uses workspace for monorepo-friendly setup)
• Build tool: tsup (fast TypeScript bundler)
• Test framework: vitest (fast, TypeScript-native)
• Linter/Formatter: Biome (ESLint + Prettier replacement)
• CI/CD: GitHub Actions with npm Trusted Publishing (OIDC)

Documentation

See docs/SPEC.md for complete specification.

License

MIT