align-config
Advanced tools
Align is a domain-specific configuration language and toolchain that makes application configuration safe, predictable,
and unified across environments. Replace scattered .env, YAML, JSON, and Kubernetes overrides with a single source of
truth: .align files. Perfect for Angular apps, AWS Lambda, and enterprise CI/CD pipelines.
🏆 Enterprise-Ready Features:
📦 Available on npm • 🏷️ Version 1.0.6
Get started in 30 seconds:
# 1. Install Align
npm install -g align-config
# 2. Create a new project with a template
align init --template=nodejs-api --app-name=myapp
# 3. Validate your configuration
align validate config/base.align --base
# 4. Build your configuration
align build --env=dev --out=./output/config.dev.json
# 5. Analyze your configuration
align analyze --config-dir=./config --env=dev
That's it! You now have a working configuration system. 🎉
Perfect for Angular + AWS Lambda setups:
# Migrate from existing .env files
align migrate-from-env --env-files=config/.env.stage,config/.env.prod
# Generate from Angular environment.ts
align infer-from-angular --src=src/environment.ts
# Build Docker-compatible .env files
align build --env=prod --format=env --out=.env
# Replace CI/CD commands
# Instead of: cp config/.env.prod .env
# Use: align build --env=prod --format=env --out=.env
ENABLE_SIGNUP=true converts properlydev-alpha, dev-bravo, qa, prodsrc/environment.ts# Initialize with a template
align init --template=nodejs-api --app-name=myapp
This creates:
myapp/
├── config/
│ ├── base.align # Shared settings
│ ├── dev.align # Development overrides
│ ├── prod.align # Production overrides
│ └── align.schema.json # Validation rules
└── output/ # Generated configs go here
Edit the generated files:
# config/base.align (shared across all environments)
app_name = "myapp"
port = 3000
database_url = "postgresql://localhost:5432/myapp"
jwt_secret = "your-super-secret-key-that-is-at-least-32-characters-long"
# config/dev.align (development overrides)
debug = true
log_level = "debug"
database_url = "postgresql://localhost:5432/myapp_dev"
# config/prod.align (production overrides)
debug = false
log_level = "error"
database_url = "postgresql://prod-db:5432/myapp_prod"
# Check for errors before deployment
align validate config/base.align --base
This catches:
# Generate config for development
align build --env=dev --out=./output/config.dev.json
# Generate config for production
align build --env=prod --out=./output/config.prod.json
This creates:
// output/config.dev.json
{
"app_name": "myapp",
"port": 3000,
"debug": true,
"database_url": "postgresql://localhost:5432/myapp_dev",
"jwt_secret": "your-super-secret-key-that-is-at-least-32-characters-long"
}
// Instead of process.env everywhere
const config = require('./output/config.dev.json');
// Type-safe and validated!
const port = config.port; // 3000 (number, not string!)
const debug = config.debug; // true (boolean, not string!)
const dbUrl = config.database_url; // Already validated
# For Vercel/Heroku (generates .env file)
align build --env=prod --format=env --out=./.env
# For Docker (JSON config)
align build --env=prod --out=./config.json
# For Kubernetes (ConfigMap)
align build --env=prod --k8s-configmap --out=./configmap.yaml
align init --template=nodejs-api --app-name=myapp.align filesalign validate config/base.align --basebase.align from your current configdev.align, prod.align for different environmentsalign validate config/base.align --basealign.schema.json to enforce standardsalign dry-run --env=prod --key=timeout --value=5000 to test changesalign analyze --config-dir=./config --env=prod for security/performance insightsalign build --env=prod --out=./output/config.prod.jsonalign build --env=prod --k8s-configmapalign diff --env1=dev --env2=prod to verify changesFor platforms that expect .env files (like Vercel), convert .align to .env:
Option 1: Build Script Integration
{
"scripts": {
"build": "align build --env=production --format=env --out=./.env && next build",
"dev": "align build --env=development --format=env --out=./.env && next dev"
}
}
Option 2: Direct .env Output
# Generate .env file directly
align build --env=production --format=env --out=./.env
# Dockerfile
FROM node:18-alpine
COPY package*.json ./
RUN npm install
COPY . .
# Build config during image build
RUN npx align-config build --env=production --format=env --out=./.env
CMD ["npm", "start"]
# Generate ConfigMap from .align files
align build --env=production --k8s-configmap --out=./k8s/configmap.yaml
# Apply to cluster
kubectl apply -f ./k8s/configmap.yaml
Align is a domain-specific configuration language and toolchain that makes application configuration safe, predictable, and unified across environments.
Most applications use scattered configuration files:
.env files (environment variables)config.json (application config)docker-compose.yml (container config)This leads to:
Replace all scattered config files with .align files:
Align replaces .env files with a more powerful, type-safe alternative.
align analyze --env=prod
Finds security issues like:
{
"jwt_secret": {
"type": "string",
"required": true,
"minLength": 32,
"pattern": "^[a-zA-Z0-9!@#$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.<>\\/?]{32,}$"
}
}
Catches:
/my-app/
├── config/
│ ├── base.align # Base configuration
│ ├── dev.align # Development overrides
│ ├── prod.align # Production overrides
│ ├── align.schema.json # Schema validation rules
├── output/
│ └── config.dev.json # Generated config
Required files:
base.align - Base configuration (always loaded first)<env>.align - Environment-specific overrides (e.g., dev.align, prod.align)Optional files:
align.schema.json - Schema validation rulesoutput/ - Directory for generated configurationsFile naming rules:
service_name, database_urldev, prod, staging, testalign.schema.jsonservice_name = "web"
timeout = 3000
auth_required = true
debug = false
port = 8080
database_url = "postgresql://localhost:5432/myapp"
cors_origins = ["http://localhost:3000", "https://myapp.com"]
service_name = "web"
service "auth" {
port = 4000
retries = 3
timeout = 5000
}
service "api" {
port = 8080
cors_enabled = true
rate_limit = 1000
}
database "main" {
url = "postgresql://localhost:5432/myapp"
pool_size = 10
ssl = true
}
"value" or value (quotes optional)3000, 3.14true, false["item1", "item2"] or [1, 2, 3]# comment or // commentNote: After installing with npm install -g align-config, you can use align instead of node index.js.
# Using npm installation
align init --template=nodejs-api --app-name=myapp
# Using source installation
node index.js init --template=nodejs-api --app-name=myapp
# Available templates:
align init --template=nodejs-api --app-name=myapp
align init --template=python-api --app-name=myapp
align init --template=go-api --app-name=myapp
align init --template=react-app --app-name=myapp
align init --template=nextjs-app --app-name=myapp
align init --template=angular-app --app-name=myapp
align init --template=microservices --app-name=myapp
align init --template=database --app-name=myapp
Choose the template that matches your project type:
nodejs-api - Node.js/Express REST APIspython-api - Python/FastAPI/Flask applicationsgo-api - Go microservices and APIsreact-app - React frontend applicationsnextjs-app - Next.js full-stack applicationsangular-app - Angular frontend applicationsmicroservices - Distributed systems with multiple servicesdatabase - Database-focused applications (PostgreSQL, Redis, etc.)Creates a new configuration from a template:
app_name placeholders with your app name# Using npm installation
align validate config/base.align --base
align validate config/dev.align
align validate config/base.align --schema config/align.schema.json
# Using source installation
node index.js validate config/base.align --base
node index.js validate config/dev.align
node index.js validate config/base.align --schema config/align.schema.json
Validates a .align file for:
--base flag)--schema)Note: Use --base flag only for base configuration files that should contain required fields like service_name.
# Using npm installation
align build --env=dev --out=./output/config.dev.json
align build --env=prod --format=yaml --out=./output/config.prod.yaml
align build --env=prod --format=env --out=./.env
# Using source installation
node index.js build --env=dev --out=./output/config.dev.json
node index.js build --env=prod --format=yaml --out=./output/config.prod.yaml
node index.js build --env=prod --format=env --out=./.env
Merges base.align and <env>.align files:
base.align first<env>.align overridesJSON (default):
{
"app_name": "myapp",
"port": 3000,
"debug": true,
"database_url": "postgresql://localhost:5432/myapp_dev"
}
YAML:
app_name: myapp
port: 3000
debug: true
database_url: postgresql://localhost:5432/myapp_dev
Environment Variables (.env):
APP_NAME="myapp"
PORT=3000
DEBUG=true
DATABASE_URL="postgresql://localhost:5432/myapp_dev"
With Inline Comments (--comments flag):
# Build with comments from schema descriptions
align build --env=dev --format=yaml --comments --out=./output/config.dev.yaml
align build --env=prod --format=jsonc --comments --out=./output/config.prod.jsonc
YAML with Comments:
# Generated by Align - Cross-Language Configuration
# YAML format with inline descriptions
# Application name
app_name: "myapp"
# Server port
port: 3000
# Enable debug mode
debug: true
# Database connection URL
database_url: "postgresql://localhost:5432/myapp_dev"
JSONC (JSON with Comments):
{
// Application name
"app_name": "myapp",
// Server port
"port": 3000,
// Enable debug mode
"debug": true,
// Database connection URL
"database_url": "postgresql://localhost:5432/myapp_dev"
}
Note: Standard JSON doesn't support comments. Use --format=jsonc for JSON with comments, or --format=json for valid JSON without comments.
Migrate from existing .env files:
# Convert existing .env files to .align format
align migrate-from-env --env-files=config/.env.stage,config/.env.prod
# This creates:
# - config/align.schema.json (schema from your variables)
# - config/stage.align (converted from .env.stage)
# - config/prod.align (converted from .env.prod)
Generate from Angular environment.ts:
# Extract environment variables from Angular
align infer-from-angular --src=src/environment.ts
# This creates:
# - config/align.schema.json (schema from Angular environment)
# - config/base.align (default values from Angular)
Build Docker-compatible .env files:
# Generate exact .env format for Docker builds
align build --env=prod --format=env --out=.env
# Output format (no quotes, Docker-compatible):
# APP_NAME=myapp
# PORT=3000
# DEBUG=true
# ENABLE_SIGNUP=true
# ENABLE_DARK_MODE=false
Replace CI/CD commands:
# Instead of: cp config/.env.prod .env
# Use: align build --env=prod --format=env --out=.env
# GitHub Actions example:
# - name: Generate .env file
# run: align build --env=${{ github.ref_name }} --format=env --out=.env
# CircleCI example:
# - run: align build --env=$CIRCLE_BRANCH --format=env --out=.env
🐍 Python (.py):
# Generated by Align - Cross-Language Configuration
class Settings:
"""Configuration settings generated from .align files"""
APP_NAME = "myapp"
PORT = 3000
DEBUG = True
DATABASE_URL = "postgresql://localhost:5432/myapp_dev"
@classmethod
def get(cls, key, default=None):
"""Get configuration value with optional default"""
return getattr(cls, key.upper().replace('-', '_'), default)
🦀 TOML (.toml) - Rust/Go:
# Generated by Align - Cross-Language Configuration
app_name = "myapp"
port = 3000
debug = true
database_url = "postgresql://localhost:5432/myapp_dev"
☕ Java Properties (.properties):
# Generated by Align - Cross-Language Configuration
app.name=myapp
port=3000
debug=true
database.url=postgresql://localhost:5432/myapp_dev
🏗️ Terraform HCL (.tf):
# Generated by Align - Cross-Language Configuration
resource "local_file" "align_config" {
filename = "config.json"
content = jsonencode({
app_name = "myapp",
port = 3000,
debug = true,
database_url = "postgresql://localhost:5432/myapp_dev"
})
}
⚙️ INI (.ini):
# Generated by Align - Cross-Language Configuration
[config]
app_name = myapp
port = 3000
debug = true
database_url = postgresql://localhost:5432/myapp_dev
📄 XML (.xml):
<?xml version="1.0" encoding="UTF-8"?>
<!-- Generated by Align - Cross-Language Configuration -->
<config>
<app_name>myapp</app_name>
<port>3000</port>
<debug>true</debug>
<database_url>postgresql://localhost:5432/myapp_dev</database_url>
</config>
Include schema descriptions as comments in your output files - Make your generated configurations self-documenting by including field descriptions from your schema as inline comments.
# Build with comments from schema descriptions
align build --env=dev --format=yaml --comments --out=./output/config.dev.yaml
align build --env=prod --format=jsonc --comments --out=./output/config.prod.jsonc
--comments flag requires a schema file (align.schema.json) with field descriptions{
"timeout": {
"type": "number",
"description": "Timeout in ms for network calls"
},
"debug": {
"type": "boolean",
"description": "Enable debug mode for development"
}
}
Generated YAML with Comments:
# Generated by Align - Cross-Language Configuration
# YAML format with inline descriptions
# Timeout in ms for network calls
timeout: 3000
# Enable debug mode for development
debug: true
Generated JSON with Comments:
{
// Timeout in ms for network calls
"timeout": 3000,
// Enable debug mode for development
"debug": true
}
--env <environment>: Environment name (required)--out <file>: Output file path (default: ./output/config.json)--config-dir <dir>: Configuration directory (default: ./config)--format <format>: Output format (json, jsonc, yaml, env, python, toml, properties, hcl, ini, xml) (default: json)--schema <file>: Schema file path (align.schema.json)--comments: Include field descriptions as comments in output (requires schema)--k8s-configmap: Generate Kubernetes ConfigMap YAML# Using npm installation
align lint --env=dev
align lint --env=prod --strict
align lint --env=dev --fix
# Using source installation
node index.js lint --env=dev
node index.js lint --env=prod --strict
node index.js lint --env=dev --fix
Lints configuration for best practices, unused fields, and potential issues:
--env <environment>: Environment to lint (dev, prod, staging) (default: dev)--config-dir <dir>: Configuration directory (default: ./config)--schema <file>: Schema file path (align.schema.json)--format <format>: Output format (text, json) (default: text)--strict: Treat warnings as errors--fix: Automatically fix fixable issues$ align lint --env=dev
🔍 Linting Configuration: dev environment
📁 Config directory: ./config
📋 Using schema: ./config/align.schema.json
📊 Lint Summary:
Total Issues: 1
Warnings: 1
Suggestions: 4
❌ Issues:
1. Conflicting default values detected
Field: port
Reason: Value conflict between config and schema default
Config: 3001, Schema Default: 3000
💡 Resolve conflicts by using consistent default values
⚠️ Warnings:
1. Overly permissive patterns detected
Field: database_url
Pattern: ^.*$
Description: Matches any string
💡 Consider using more restrictive patterns for better security
💡 Suggestions:
1. JWT secret is too short
Field: jwt_secret
💡 Use a secret with at least 32 characters
Impact: Weak secrets can be easily compromised
# Apply automatic fixes
align lint --env=dev --fix
# Output shows what was fixed
✅ Fixed 3 issues:
- port: 3001 → 3000
- jwt_secret: weak-secret → strong-secret-here
- cors_origins: * → http://localhost:3000,http://localhost:8080
⚠️ 1 issues require manual fixes:
- database_url: Pattern restrictions require manual review
💾 Fixed configuration saved to files.
What gets fixed automatically:
What requires manual review:
Enterprise-grade compliance checking and reporting - Automatically audit your configuration for SOC 2 compliance across all five trust service criteria with detailed reporting and automated fixes.
Generate SOC 2 Compliance Checklist:
# Basic compliance check
align soc2-checklist --env=prod
# Detailed analysis with recommendations
align soc2-checklist --env=prod --detailed
# JSON output for CI/CD integration
align soc2-checklist --env=prod --format=json --output=compliance.json
# Fail CI/CD on violations
align soc2-checklist --env=prod --fail-on-violations
Generate Detailed SOC 2 Reports:
# Generate comprehensive compliance report
align soc2-report --env=prod --format=json --output=report.json
# HTML report for stakeholders
align soc2-report --env=prod --format=html --output=report.html
# Enterprise template with detailed analysis
align soc2-report --env=prod --template=enterprise
Automatically Fix Compliance Issues:
# Show available fixes (dry run)
align soc2-fix --env=prod --dry-run
# Apply all safe fixes automatically
align soc2-fix --env=prod --auto
# Interactive mode - confirm each fix
align soc2-fix --env=prod --interactive
Security Controls (40% weight):
Availability Controls (20% weight):
Processing Integrity (20% weight):
Confidentiality Controls (15% weight):
Privacy Controls (5% weight):
Compliance Checklist:
$ align soc2-checklist --env=prod --detailed
🔒 SOC 2 Compliance Check: prod environment
📁 Config directory: ./config
🔒 SOC 2 Compliance Results
Environment: prod
Overall Score: 85.2%
Status: COMPLIANT
📊 Category Scores:
security: 92.5%
availability: 78.3%
processing_integrity: 85.0%
confidentiality: 87.5%
privacy: 81.3%
❌ Failed Controls:
availability.disaster_recovery: 40%
- No backup configuration found
- No disaster recovery configuration found
💡 Configure automated backups
💡 Configure disaster recovery procedures
💡 Recommendations:
- Configure automated backups
- Configure disaster recovery procedures
- Enable comprehensive monitoring
Detailed Report (JSON):
{
"metadata": {
"environment": "prod",
"timestamp": "2024-01-15T10:30:00.000Z",
"template": "enterprise"
},
"summary": {
"overall_score": 85.2,
"compliance_status": "COMPLIANT",
"total_controls": 20,
"passed_controls": 16,
"failed_controls": 4
},
"details": {
"security": {
"secrets_management": {
"status": "PASS",
"score": 110,
"issues": [],
"recommendations": []
}
}
},
"recommendations": [
"Configure automated backups",
"Configure disaster recovery procedures"
]
}
CI/CD Pipeline:
# GitHub Actions
- name: SOC 2 Compliance Check
run: |
align soc2-checklist --env=prod --fail-on-violations
if [ $? -ne 0 ]; then
echo "SOC 2 compliance violations found!"
exit 1
fi
Pre-deployment Validation:
# Check compliance before deployment
align soc2-checklist --env=prod --fail-on-violations
# Generate compliance report for auditors
align soc2-report --env=prod --format=json --output=audit-report.json
Native Google Cloud Secret Manager integration - Automatically resolve secrets from GCP Secret Manager during build time with environment-specific secret mapping and rotation support.
List and Manage Secrets:
# List all secrets in GCP project
align secrets --gcp --project=my-project --list
# Validate secrets configuration
align secrets --gcp --project=my-project --validate
# Rotate secrets automatically
align secrets --gcp --project=my-project --rotate
Build with GCP Secrets:
# Build configuration with secrets from GCP
align build --env=prod --secrets-from=gcp --project=my-project --out=.env
# Resolve secrets during build
align build --env=prod --gcp-secrets --project=my-project --out=config.json
Secret Rotation and Management:
# Schedule secret rotation
align secrets --gcp --project=my-project --schedule-rotation=db-password
# List rotation schedules
align secrets --gcp --project=my-project --list-rotations
# Validate secret strength
align secrets --gcp --project=my-project --validate-strength
Reference GCP secrets in your .align files:
# config/prod.align
database_password = gcp://db-password
api_key = gcp://api-key
jwt_secret = gcp://jwt-secret
# Secrets are automatically resolved during build
redis_password = gcp://redis-password
Environment-specific secret mapping:
# config/dev.align
database_password = gcp://db-password-dev
api_key = gcp://api-key-dev
# config/prod.align
database_password = gcp://db-password-prod
api_key = gcp://api-key-prod
Automatic Secret Detection:
Secret Rotation Support:
Secret Management:
$ align secrets --gcp --project=my-project --list
🔐 GCP Secret Manager: my-project
📁 Config directory: ./config
📊 Secrets Summary:
Total Secrets: 8
GCP References: 6
Hardcoded Secrets: 2
Weak Secrets: 1
🔐 GCP Secret References:
1. database_password → gcp://db-password
2. api_key → gcp://api-key
3. jwt_secret → gcp://jwt-secret
❌ Issues Found:
1. Hardcoded secret detected
Field: temp_password
💡 Move to GCP Secret Manager
2. Weak secret detected
Field: api_key
💡 Use stronger secret with special characters
Build with Secrets:
$ align build --env=prod --secrets-from=gcp --project=my-project --out=.env
🔐 Resolving GCP secrets...
📁 Loading base config: ./config/base.align
📁 Loading environment config: ./config/prod.align
🔄 Resolving secrets from GCP Secret Manager...
✅ Configuration built successfully!
📄 Output: .env
📊 Keys: 12
🔐 Secrets resolved: 6
CI/CD Pipeline:
# GitHub Actions with GCP authentication
- name: Build with GCP Secrets
run: |
align build --env=prod --secrets-from=gcp --project=${{ secrets.GCP_PROJECT }} --out=.env
env:
GOOGLE_APPLICATION_CREDENTIALS: ${{ secrets.GCP_SA_KEY }}
# CircleCI with GCP authentication
- run: |
align build --env=prod --secrets-from=gcp --project=$GCP_PROJECT --out=.env
environment:
GOOGLE_APPLICATION_CREDENTIALS: $GCP_SA_KEY
Docker Integration:
# Dockerfile with GCP secrets
FROM node:18-alpine
COPY package*.json ./
RUN npm install
COPY . .
# Build config with GCP secrets during image build
RUN align build --env=prod --secrets-from=gcp --project=my-project --out=.env
CMD ["npm", "start"]
Secure handling of sensitive configuration fields - Automatically detect, mask, and validate secrets with optional integration with external secret management systems.
# Using npm installation
align secrets --env=dev --mask
align secrets --env=prod --env-secrets --vault
align explain-secret --key=jwt_secret --mask
# Using source installation
node index.js secrets --env=dev --mask
node index.js secrets --env=prod --env-secrets --vault
node index.js explain-secret --key=jwt_secret --mask
Manages and validates sensitive configuration fields with automatic detection and masking:
--env <environment>: Environment to analyze (dev, prod, staging) (default: dev)--config-dir <dir>: Configuration directory (default: ./config)--schema <file>: Schema file path (align.schema.json)--format <format>: Output format (text, json) (default: text)--mask: Mask sensitive values in output--env-secrets: Check integration with .env.secret file--vault: Check Vault integration--vault-address <address>: Vault server address (default: http://localhost:8200)--vault-token <token>: Vault authentication token--vault-path <path>: Vault secrets path (default: secret)$ align secrets --env=prod --mask
🔐 Secrets Management: prod environment
📁 Config directory: ./config
📊 Secrets Summary:
Sensitive Fields: 3
Issues: 1
Warnings: 2
Suggestions: 4
🔐 Sensitive Fields Detected:
1. jwt_secret
Reason: matches sensitive field pattern
Value: st**********et
2. api_key
Reason: matches sensitive field pattern
Value: sk**********ey
3. database_password
Reason: matches sensitive field pattern
Value: pa**********rd
❌ Security Issues:
1. Secret is too short
Field: jwt_secret
💡 Use secrets with at least 16 characters
Impact: Short secrets are easily compromised
⚠️ Security Warnings:
1. Secret may be too simple
Field: api_key
💡 Use secrets with special characters and mixed case
Impact: Simple secrets are easier to crack
2. Development secret in production
Field: database_password
💡 Use production-appropriate secrets
Impact: Development secrets may not be secure for production
💡 Security Suggestions:
1. Secret available in .env.secret
Field: jwt_secret
💡 Use jwt_secret from .env.secret instead of inline value
Impact: External secret management is more secure
🏦 Vault Integration:
Vault Address: http://localhost:8200
Vault Path: secret
Status: Available for integration
❌ Configuration has security issues that need to be addressed.
Mark fields as sensitive in your schema for automatic detection:
{
"properties": {
"jwt_secret": {
"type": "string",
"description": "JWT signing secret",
"sensitive": true,
"minLength": 32
},
"api_key": {
"type": "string",
"description": "External API key",
"sensitive": true,
"pattern": "^sk_[a-zA-Z0-9]{32,}$"
}
}
}
.env.secret Integration:
# Create .env.secret file
JWT_SECRET=your-super-secret-jwt-key-here
API_KEY=sk_live_1234567890abcdef
DATABASE_PASSWORD=secure-db-password
# Use with align secrets
align secrets --env-secrets
Vault Integration:
# Check Vault integration
align secrets --vault --vault-address=https://vault.company.com
# Mock Vault operations (real implementation would use Vault API)
[MOCK] Getting secret jwt_secret from Vault at https://vault.company.com
[MOCK] Setting secret api_key in Vault at https://vault.company.com
Auto-generate CI/CD configuration for various platforms - Generate ready-to-use CI/CD pipelines that integrate Align configuration validation, building, and security scanning.
# Using npm installation
align ci --platform github
align ci --platform gitlab --environments dev,staging,prod
align ci --platform jenkins --security-scanning --parallel-builds
# Using source installation
node index.js ci --platform github
node index.js ci --platform gitlab --environments dev,staging,prod
node index.js ci --platform jenkins --security-scanning --parallel-builds
Generates CI/CD configuration files for popular platforms with built-in Align integration:
github, github-actions)gitlab, gitlab-ci)jenkins)circleci, circle)azure, azure-devops)--platform <platform>: CI/CD platform (github, gitlab, jenkins, circleci, azure) (default: github)--config-dir <dir>: Configuration directory (default: ./config)--env <environment>: Environment to analyze for generation (default: dev)--output <file>: Output file path (auto-detected by platform)--environments <list>: Comma-separated list of environments (default: dev,prod)--workflow-name <name>: Workflow name (GitHub Actions) (default: align-config)--security-scanning: Include security scanning jobs (default: true)--cache-dependencies: Enable dependency caching (default: true)--matrix-strategy: Use matrix strategy for builds (GitHub Actions) (default: true)--deployment-strategy <strategy>: Deployment strategy (manual, auto, none) (default: manual)--parallel-builds: Enable parallel builds (Jenkins) (default: true)--format <format>: Output format (yaml, json) (default: yaml)$ align ci --platform github --environments dev,prod
🚀 CI/CD Configuration Generator: github
📁 Config directory: ./config
🌍 Environment: dev
✅ CI/CD configuration generated successfully!
📄 Output: .github/workflows/align-config.yml
🏗️ Platform: github
🌍 Environments: dev, prod
🔐 Security scanning included
💾 Dependency caching enabled
📊 Matrix strategy enabled
💡 Next steps:
1. Review the generated .github/workflows/align-config.yml
2. Customize the configuration as needed
3. Commit and push to trigger CI/CD
4. Monitor the pipeline execution
name: align-config
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Validate configuration
run: align validate config/base.align
- name: Lint configuration
run: align lint --env=dev --strict
build-dev:
runs-on: ubuntu-latest
needs: validate
strategy:
matrix:
format: [json, yaml, env]
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build dev configuration
run: align build --env=dev --format=${{ matrix.format }} --out=./dist/config.dev.${{ matrix.format }}
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: config-dev-${{ matrix.format }}
path: ./dist/config.dev.*
build-prod:
runs-on: ubuntu-latest
needs: validate
strategy:
matrix:
format: [json, yaml, env]
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build prod configuration
run: align build --env=prod --format=${{ matrix.format }} --out=./dist/config.prod.${{ matrix.format }}
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: config-prod-${{ matrix.format }}
path: ./dist/config.prod.*
security:
runs-on: ubuntu-latest
needs: validate
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install dependencies
run: npm ci
- name: Security scan
run: align secrets --env=prod --mask --format=json > security-report.json
- name: Upload security report
uses: actions/upload-artifact@v4
with:
name: security-report
path: security-report.json
deploy-dev:
runs-on: ubuntu-latest
needs: build-dev
environment: dev
steps:
- name: Download artifacts
uses: actions/download-artifact@v4
with:
name: config-dev-*
- name: Deploy to dev
run: echo "Deploying configuration to dev environment"
deploy-prod:
runs-on: ubuntu-latest
needs: build-prod
if: github.ref == 'refs/heads/main'
environment: prod
steps:
- name: Download artifacts
uses: actions/download-artifact@v4
with:
name: config-prod-*
- name: Deploy to prod
run: echo "Deploying configuration to prod environment"
GitHub Actions:
GitLab CI:
Jenkins:
CircleCI:
Azure DevOps:
Schema and configuration versioning with migration helpers - Track versions of schemas and configurations, detect compatibility issues, and safely migrate between versions.
# Using npm installation
align version --env=dev
align migrate --to-version=2.0.0 --dry-run
align bump --type=minor --target=schema
# Using source installation
node index.js version --env=dev
node index.js migrate --to-version=2.0.0 --dry-run
node index.js bump --type=minor --target=schema
Manages schema and configuration versions with comprehensive migration support:
align version - Check version information and compatibility:
--env <environment>: Environment to analyze (default: dev)--config-dir <dir>: Configuration directory (default: ./config)--schema <file>: Schema file path (align.schema.json)--format <format>: Output format (text, json) (default: text)align migrate - Migrate configuration to a new version:
--to-version <version>: Target version for migration--dry-run: Show migration plan without applying changes--backup: Create backup before migration (default: true)--env <environment>: Environment to migrate (default: dev)--format <format>: Output format (text, json) (default: text)align bump - Bump version of schema or configuration:
--type <type>: Bump type (major, minor, patch) (default: patch)--target <target>: Target to bump (schema, config, both) (default: both)--dry-run: Show what would be changed without applying--env <environment>: Environment to bump (default: dev)--format <format>: Output format (text, json) (default: text)$ align version --env=prod
📋 Version Management: prod environment
📁 Config directory: ./config
📋 Version Information:
Schema Version: 2.1.0
Config Version: 1.5.2
⚠️ Config version is older than schema version
⚠️ Version Warnings:
1. Configuration is outdated
Current: 1.5.2
Latest: 2.1.0
💡 Run align migrate to update configuration
❌ Configuration has version issues that need to be addressed.
$ align migrate --to-version=2.1.0 --dry-run
🔄 Migration: dev environment
📁 Config directory: ./config
🎯 Target version: 2.1.0
🔄 Migration Plan:
From: 1.5.2
To: 2.1.0
🚨 Breaking Changes:
1. Major version change from 1.5.2 to 2.1.0
Impact: Breaking changes may require manual intervention
✨ New Features:
1. New features available in version 2.1.0
Impact: New optional fields may be available
⚠️ Deprecated Fields:
1. old_field_name
Replacement: new_field_name
📋 Migration Steps:
1. Backup current configuration
Action: Create backup of current config files
2. Validate current configuration
Action: Run align validate to check current state
3. Update schema to latest version
Action: Update align.schema.json to latest version
4. Migrate deprecated field 'old_field_name'
Action: Replace 'old_field_name' with 'new_field_name'
5. Validate migrated configuration
Action: Run align validate to ensure migration was successful
🔍 This was a dry run. No changes were applied.
💡 Run without --dry-run to apply the migration.
Add version information to your schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"version": "2.1.0",
"alignVersion": "1.0.0",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"type": "object",
"properties": {
"app_name": {
"type": "string",
"description": "Application name"
},
"new_field_name": {
"type": "string",
"description": "New field (replaces old_field_name)"
}
},
"deprecated": {
"old_field_name": {
"replacement": "new_field_name",
"since": "2.0.0",
"message": "Use new_field_name instead"
}
}
}
Configurations automatically include version metadata:
{
"app_name": "myapp",
"port": 3000,
"new_field_name": "value",
"_metadata": {
"version": "2.1.0",
"schemaVersion": "2.1.0",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"generatedBy": "align-config"
}
}
# Bump patch version (1.0.0 → 1.0.1)
align bump --type=patch
# Bump minor version (1.0.0 → 1.1.0)
align bump --type=minor
# Bump major version (1.0.0 → 2.0.0)
align bump --type=major
# Bump only schema version
align bump --type=minor --target=schema
# Bump only config version
align bump --type=patch --target=config
Environment-specific guardrails and business rules - Prevent misconfigurations like debug = true in production and encode team policies into your configuration system.
validate far more powerful and applicableAllowed Values:
{
"production": {
"debug": { "allowed": false },
"log_level": { "allowed": ["error", "warn"] }
}
}
Required Values:
{
"production": {
"ssl": { "required": true },
"jwt_secret": { "required": true }
}
}
Numeric Ranges:
{
"production": {
"timeout": { "min": 5000 },
"max_connections": { "max": 100 }
}
}
Pattern Matching:
{
"production": {
"database_url": { "pattern": "^postgresql://.*$" },
"jwt_secret": { "pattern": "^.{32,}$" }
}
}
Validate Policies:
# Validate production config against policies
align validate-policies --env=prod
# Use custom policy file
align validate-policies --env=prod --policy-file=./custom.policies.json
# JSON output for CI/CD
align validate-policies --env=prod --format=json
Generate Policy Suggestions:
# Get suggestions for current config
align suggest-policies --env=prod
# Analyze specific environment
align suggest-policies --env=staging
Create align.policies.json in your project root:
{
"production": {
"debug": {
"allowed": false,
"message": "Debug mode should not be enabled in production"
},
"log_level": {
"allowed": ["error", "warn"],
"message": "Production should use error or warn log level"
},
"ssl": {
"required": true,
"message": "SSL must be enabled in production"
},
"timeout": {
"min": 5000,
"message": "Production timeouts should be at least 5 seconds"
}
},
"staging": {
"debug": {
"allowed": false,
"message": "Debug mode should not be enabled in staging"
},
"log_level": {
"allowed": ["info", "warn"],
"message": "Staging should use info or warn log level"
}
},
"development": {
"debug": {
"allowed": true,
"message": "Debug mode is recommended for development"
},
"log_level": {
"allowed": ["debug", "info"],
"message": "Development should use debug or info log level"
}
}
}
Policy Violations:
🔒 Policy Validation for production:
❌ 3 policy violations found:
1. debug = true
Environment: production
Rule: allowed_value
Message: Debug mode should not be enabled in production
2. log_level = debug
Environment: production
Rule: allowed_values
Message: Production should use error or warn log level
3. ssl = false
Environment: production
Rule: required
Message: SSL must be enabled in production
Policy Suggestions:
💡 Policy Suggestions for production:
1. debug (critical)
Rule: allowed
Suggested: false
Message: Debug mode should be disabled in production
2. log_level (warning)
Rule: allowed
Suggested: ["error", "warn"]
Message: Production should use error or warn log level
CI/CD Pipeline:
# GitHub Actions
- name: Validate Policies
run: |
align validate-policies --env=prod --format=json > policy-results.json
if [ $(jq '.valid' policy-results.json) != "true" ]; then
echo "Policy violations found!"
exit 1
fi
Pre-commit Hook:
#!/bin/bash
# .git/hooks/pre-commit
align validate-policies --env=dev
if [ $? -ne 0 ]; then
echo "Policy violations found. Commit blocked."
exit 1
fi
Make onboarding fast - Automatically generate schemas from existing .align files instead of writing them from scratch.
.align file and run align infer to generate a schema.env or config.json into a typed schemaBasic Inference:
# Infer schema from existing .align files
align infer --config-dir=./config --out=./align.schema.json
# Using source installation
node index.js infer --config-dir=./config --out=./align.schema.json
Advanced Options:
# Mark all fields as required
align infer --mark-all-required
# Infer patterns for URLs and emails (default: true)
align infer --infer-patterns
# Infer min/max ranges for numbers
align infer --infer-ranges
# Output in YAML format
align infer --format=yaml
Input .align file:
service_name = "api"
timeout = 3000
auth_required = true
database_url = "postgresql://localhost:5432/db"
Generated schema:
{
"service_name": {
"type": "string",
"required": false,
"description": "Inferred from service_name",
"default": "api"
},
"timeout": {
"type": "number",
"required": false,
"description": "Inferred from timeout",
"default": 3000
},
"auth_required": {
"type": "boolean",
"required": false,
"description": "Inferred from auth_required",
"default": true
},
"database_url": {
"type": "string",
"required": false,
"description": "Inferred from database_url",
"default": "postgresql://localhost:5432/db",
"pattern": "^https?://.*$"
}
}
Inference Summary:
🧠 Inferring schema from .align files...
📁 Config directory: ./config
📄 Output file: ./align.schema.json
✅ Schema inferred and saved to: ./align.schema.json
📊 Inference Summary:
Total fields: 38
Required fields: 0
String fields: 14
Number fields: 17
Boolean fields: 6
Array fields: 1
Pattern fields: 4
💡 Next Steps:
1. Review the generated schema
2. Adjust required fields and validation rules
3. Add descriptions and documentation
4. Run "align validate" to test the schema
Transform your CLI experience with guided wizards and interactive prompts for better Developer Experience.
Interactive Setup Wizard:
# Start interactive setup
align setup
# Non-interactive mode (fallback)
align setup --interactive false --template nodejs-api --app-name myapp
Interactive Configuration Wizard:
# Start interactive editor
align wizard
# Non-interactive mode
align wizard --interactive false --env dev --key port --value 3000
Interactive Troubleshoot Wizard:
# Start interactive diagnosis
align troubleshoot
# Non-interactive mode
align troubleshoot --interactive false --config-dir ./config --detailed
Interactive Flow:
$ align setup
🛠️ Let's create a new Align config!
? What environment are you targeting? (Use arrow keys)
❯ dev
prod
staging
? Service name: (web)
? Port: (3000)
? Timeout (ms): (3000)
? Require authentication? (Y/n)
? Log level: (Use arrow keys)
❯ info
debug
warn
error
? Database URL (optional):
? Generate schema automatically? (Y/n)
✅ Configuration created successfully!
📁 Config directory: ./config
📄 Base config: ./config/base.align
📄 Environment config: ./config/dev.align
📋 Schema: ./config/align.schema.json
💡 Next steps:
1. Review and customize the generated config
2. Run "align validate" to check your config
3. Run "align build" to generate output files
Interactive Flow:
$ align wizard
📝 Interactive Configuration Editor
? Which environment to edit? (Use arrow keys)
❯ dev
prod
staging
? What would you like to do? (Use arrow keys)
❯ Edit existing key
Add new key
Remove key
View current config
? Which key to edit? (Use arrow keys)
❯ port
timeout
debug
? Value for port: (3000)
✅ Updated port = 3000 in dev.align
Interactive Flow:
$ align troubleshoot
🔍 Interactive Configuration Diagnosis
? What issue are you experiencing? (Use arrow keys)
❯ All of the above
Configuration errors
Security warnings
Performance issues
? Which environment to analyze? (Use arrow keys)
❯ dev
prod
staging
? Show detailed analysis? (Y/n)
🔍 Analyzing configuration...
📊 Analysis Results:
❌ 2 critical issues found:
1. Weak JWT Secret
2. Missing required field: database_url
⚠️ 1 warnings found:
1. Port 3000 is commonly used
💡 Recommendations:
1. Security: Generate a strong JWT secret
2. Configuration: Add database_url to dev.align
3. Best Practice: Consider using a different port
# Using npm installation
align dry-run --env=prod --key=auth_required --value=false
# Using source installation
node index.js dry-run --env=prod --key=auth_required --value=false
Simulates configuration changes without applying them:
# Using npm installation
align explain --key=timeout --env=prod
# Using source installation
node index.js explain --key=timeout --env=prod
Debug configuration values with step-by-step trace:
$ align explain --key=port --env=prod
🔍 Config Trace for key: "port" in env: "prod"
1. base.align → port = 8000
2. prod.align → port = 80 ✅ ACTIVE VALUE
💡 Override detected: Value changed from 8000 to 80
Perfect for:
# Using npm installation
align diff --env1=dev --env2=prod
# Using source installation
node index.js diff --env1=dev --env2=prod
Compares configurations between two environments:
# Using npm installation
align analyze --config-dir=./config --env=prod
align analyze --config-dir=./config --env=prod --detailed
align analyze --config-dir=./config --env=prod --format=json
# Using source installation
node index.js analyze --config-dir=./config --env=prod
node index.js analyze --config-dir=./config --env=prod --detailed
node index.js analyze --config-dir=./config --env=prod --format=json
Comprehensive configuration analysis with:
$ node index.js analyze --config-dir=./config --env=prod --detailed
🔍 Smart Analysis: prod environment
📁 Config directory: C:\dev\align-config\config
📊 Analysis Summary:
Total Issues: 11
Security Issues: 2
Performance Issues: 3
Best Practice Issues: 6
Good Practices: 1
🚨 Critical Security Issues:
1. Insecure HTTP on Port 80
Production environment using HTTP without SSL
Impact: Critical security vulnerability - data transmitted in plain text
Fix: Configure SSL certificate and redirect HTTP to HTTPS
Recommendation: Enable SSL/TLS for production
⚠️ Security Warnings:
1. No JWT Secret Configured
JWT authentication may not work properly
Impact: Authentication may fail
Recommendation: Add a strong JWT secret
⚡ Performance Issues:
1. No Caching Configured
Caching not enabled in production
Impact: Poor performance, unnecessary database queries
Fix: Configure Redis or in-memory caching
Recommendation: Enable caching for better performance
📋 Missing Best Practices:
1. No Health Checks
Health check endpoint not configured
Impact: Difficult to monitor application health
Fix: Enable health_check_enabled and configure health_check_path
Recommendation: Add health check endpoint for monitoring
✅ Good Practices Found:
1. Strong JWT secret configured
Scan your existing configuration files and get a comprehensive analysis of issues and migration paths to Align.
# Using npm installation
align diagnose --config-dir=./config --project-dir=.
align diagnose --detailed --format=json
# Using source installation
node index.js diagnose --config-dir=./config --project-dir=.
node index.js diagnose --detailed --format=json
What it does:
Options:
--config-dir <dir>: Configuration directory to analyze (default: ./config)--project-dir <dir>: Project root directory to scan (default: .)--detailed: Show detailed analysis with file paths--format <format>: Output format (text, json) (default: text)--generate-plan: Generate migration plan for align repairExample Output:
$ align diagnose --detailed
🔍 Diagnosing configuration environment...
📁 Project directory: /path/to/project
📁 Config directory: /path/to/project/config
🚨 Critical Issues:
1. Scattered Configuration
Found 5 different config files across project
Impact: Hard to manage, inconsistent formats
Fix: Consolidate into .align files
⚠️ Warnings:
1. Type Safety Issues
Found quoted numbers in .env files
Impact: Potential runtime errors
Fix: Use proper types in .align files
📋 Recommendations:
1. Run align repair
Automatically fix type safety issues
Command: align repair --auto
📈 Summary:
5 configuration files found
23 configuration keys analyzed
2 environments detected
3 deployment platforms found
Let packages declare their own schemas and use namespaced configuration with full context resolution.
# Using npm installation
align discover-packages --project-dir=.
# Using source installation
node index.js discover-packages --project-dir=.
What it does:
align.schema.json files or package.json "align" fieldExample Output:
$ align discover-packages
📦 Package Schemas Found:
express-auth:
- jwt_secret
- timeout
- max_retries
- session_duration
- enable_refresh
postgres-db:
- url
- max_pool
- timeout
- ssl
- migrations
redis-cache:
- url
- ttl
- max_memory
- enable_clustering
- retry_attempts
# config/base.align
app_name = "myapp"
# Package-provided schemas automatically available
express-auth.jwt_secret = "super-secret-key"
express-auth.timeout = 30000
express-auth.max_retries = 3
postgres-db.url = "postgresql://localhost:5432/myapp"
postgres-db.max_pool = 25
postgres-db.ssl = true
redis-cache.url = "redis://localhost:6379"
redis-cache.ttl = 3600
redis-cache.max_memory = "100mb"
# Using npm installation
align explain --key=express-auth.timeout --env=prod --include-packages
# Using source installation
node index.js explain --key=express-auth.timeout --env=prod --include-packages
What it shows:
Example Output:
$ align explain --key=express-auth.timeout --env=prod --include-packages
🔍 EXPLAIN: Tracing configuration key
Key: express-auth.timeout
Environment: prod
📊 Final value: 45000
📦 Source: package:express-auth
📦 Package: express-auth
🏷️ Namespace: express-auth
🔍 Validation:
Type: number
Required: false
Default: 30000
📁 Base config: 30000
♻️ Environment override: 45000
# Using npm installation
align list-schemas --config-dir=./config --project-dir=.
# Using source installation
node index.js list-schemas --config-dir=./config --project-dir=.
What it shows:
Example Output:
$ align list-schemas
📋 Available Schemas:
📁 Project Schema:
- app_name
- port
- debug
- database_url
📦 Package Schemas:
express-auth:
- jwt_secret
- timeout
- max_retries
- session_duration
- enable_refresh
postgres-db:
- url
- max_pool
- timeout
- ssl
- migrations
Option A: Dedicated Schema File
node_modules/express-auth/align.schema.json
{
"jwt_secret": {
"type": "string",
"required": true,
"minLength": 32
},
"timeout": {
"type": "number",
"default": 30000,
"min": 1000
}
}
Option B: Package.json Integration
{
"name": "express-auth",
"version": "1.0.0",
"align": {
"jwt_secret": {
"type": "string",
"required": true,
"minLength": 32
},
"timeout": {
"type": "number",
"default": 30000
}
}
}
Safely migrate existing configuration to Align with comprehensive safety features.
# Using npm installation
align repair --config-dir=./config --project-dir=.
align repair --interactive --backup
align repair --dry-run --safe-only
# Using source installation
node index.js repair --config-dir=./config --project-dir=.
node index.js repair --interactive --backup
node index.js repair --dry-run --safe-only
Safety Features:
--dry-run shows what would change without applying--backup creates automatic backups before changes--rollback --backup-dir--safe-only only applies low-risk changes--interactive asks for confirmation on each changeOptions:
--config-dir <dir>: Configuration directory to analyze (default: ./config)--project-dir <dir>: Project root directory to scan (default: .)--backup: Create backup before making changes--dry-run: Show what would change without making changes--interactive: Ask for confirmation before each change--auto: Automatically apply all safe fixes--analyze-only: Show detailed migration plan without changes--rollback: Restore from backup (use with --backup-dir)--backup-dir <dir>: Backup directory for rollback--fix-types: Only fix type safety issues--consolidate-configs: Only consolidate scattered configs--fix-security: Only fix security issues--detailed: Show detailed information about changesExample Workflow:
# 1. Analyze current state
$ align diagnose --detailed
🚨 Found 3 scattered config files
⚠️ Found 5 type safety issues
# 2. Preview changes (safe)
$ align repair --dry-run --safe-only
📋 Would fix 5 type safety issues
📁 Would consolidate 3 config files
💡 No risky changes detected
# 3. Apply with backup
$ align repair --auto --backup
📦 Backup created: ./backup/2024-01-15-10-30-45
🔧 Applied 5 type safety fixes
📁 Consolidated 3 config files
✅ Repair completed successfully!
# 4. Rollback if needed
$ align repair --rollback --backup-dir=./backup/2024-01-15-10-30-45
🔄 Restored from backup
✅ Rollback completed successfully!
What it fixes:
Align uses standard exit codes for automation and CI/CD:
0 - Success (validation passed, build completed, etc.)1 - General error (file not found, invalid syntax, etc.)2 - Validation error (missing required fields, type errors, etc.)File not found:
$ align validate config/missing.align
❌ Error: Configuration file not found: config/missing.align
Validation failed:
$ align validate config/base.align --base
❌ Validation failed: Missing required key: service_name
Invalid syntax:
$ align validate config/invalid.align
❌ Invalid syntax on line 2: missing '='
Type error:
$ align validate config/type-error.align --schema config/schema.json
❌ Validation failed: port must be a number, got "abc"
Create align.schema.json to define validation rules:
{
"service_name": {
"type": "string",
"required": true,
"minLength": 1,
"maxLength": 50
},
"timeout": {
"type": "number",
"required": false,
"min": 100,
"max": 30000,
"default": 3000
},
"auth_required": {
"type": "boolean",
"required": false,
"default": true
},
"port": {
"type": "number",
"required": false,
"min": 1,
"max": 65535,
"default": 8080
},
"database_url": {
"type": "string",
"required": false,
"pattern": "^[a-zA-Z]+://.*$"
},
"cors_origins": {
"type": "array",
"items": {
"type": "string"
},
"required": false
}
}
Schema validation is useful for:
For simple projects, you can skip schema validation and use basic validation instead.
Type Validation:
{
"port": { "type": "number" },
"debug": { "type": "boolean" },
"name": { "type": "string" }
}
Required Fields:
{
"service_name": {
"type": "string",
"required": true
}
}
Value Ranges:
{
"port": {
"type": "number",
"min": 1,
"max": 65535
}
}
String Patterns:
{
"email": {
"type": "string",
"pattern": "^[^@]+@[^@]+\\.[^@]+$"
}
}
Array Validation:
{
"cors_origins": {
"type": "array",
"items": { "type": "string" },
"minLength": 1
}
}
Use Align programmatically in your Node.js applications:
const { Align } = require('align-config');
// Initialize Align
const align = new Align('./config');
// Load configuration
const config = align.load('dev');
console.log(config.service_name); // "web"
console.log(config.timeout); // 5000
// Get metadata about the configuration
const metadata = align.getMetadata('dev');
console.log(metadata.environment); // "dev"
console.log(metadata.overriddenKeys); // ['debug', 'port', ...]
// Trace where a value came from
const trace = align.explain('timeout', 'dev');
console.log(trace.source); // "overridden"
console.log(trace.finalValue); // 5000
// Compare environments
const diff = align.diff('dev', 'prod');
console.log(diff.differences.length); // Number of differences
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watch
Comprehensive test suite with 308 tests covering:
Coverage Metrics:
Test Files:
parser.test.js - Core parser functionality (200+ tests)lib.test.js - Library API testing (50+ tests)tests/cli.test.js - CLI command testing (150+ tests)tests/parser.test.js - Additional parser edge casesAlign uses GitHub Actions for continuous integration:
$ node index.js validate config/base.align --base
✅ Validation passed: config is valid!
Found 6 configuration keys
$ node index.js build --env=dev --format=yaml --out=./output/config.dev.yaml
📁 Loading base config: C:\dev\align-config\config\base.align
📁 Loading environment config: C:\dev\align-config\config\dev.align
🔄 Merging configurations...
✅ Configuration built successfully!
📄 Output: C:\dev\align-config\output/config.dev.yaml
📊 Keys: 7
📋 Format: YAML
🔄 Overridden keys: debug, port, database_url, log_level
$ node index.js build --env=dev --format=yaml --comments --out=./output/config.dev.yaml
📋 Using schema: C:\dev\align-config\config\align.schema.json
📁 Loading base config: C:\dev\align-config\config\base.align
📁 Loading environment config: C:\dev\align-config\config\dev.align
🔄 Merging configurations...
✅ Configuration built successfully!
📄 Output: C:\dev\align-config\output/config.dev.yaml
📊 Keys: 7
📋 Format: YAML
💬 Comments: Included from schema descriptions
🔄 Overridden keys: debug, port, database_url, log_level
$ node index.js build --env=dev --format=env --out=./output/config.dev.env
📁 Loading base config: C:\dev\align-config\config\base.align
📁 Loading environment config: C:\dev\align-config\config\dev.align
🔄 Merging configurations...
✅ Configuration built successfully!
📄 Output: C:\dev\align-config\output/config.dev.env
📊 Keys: 7
📋 Format: ENV
🔄 Overridden keys: debug, port, database_url, log_level
$ node index.js build --env=dev --format=env --comments --out=./output/config.dev.env
📋 Using schema: C:\dev\align-config\config\align.schema.json
📁 Loading base config: C:\dev\align-config\config\base.align
📁 Loading environment config: C:\dev\align-config\config\dev.align
🔄 Merging configurations...
✅ Configuration built successfully!
📄 Output: C:\dev\align-config\output/config.dev.env
📊 Keys: 7
📋 Format: ENV
💬 Comments: Included from schema descriptions
🔄 Overridden keys: debug, port, database_url, log_level
$ node index.js build --env=dev --k8s-configmap --out=./output/config.dev.yaml
📁 Loading base config: C:\dev\align-config\config\base.align
📁 Loading environment config: C:\dev\align-config\config\dev.align
🔄 Merging configurations...
✅ Configuration built successfully!
📄 Output: C:\dev\align-config\output/config.dev.yaml
📄 ConfigMap: C:\dev\align-config\output/config.dev.configmap.yaml
📊 Keys: 25
📋 Format: JSON
🔄 Overridden keys: port, log_level, log_format, database_url, database_pool_size, cors_origins, rate_limit_max, metrics_enabled, redis_url, cache_ttl
$ node index.js dry-run --env=prod --key=auth_required --value=false
🔍 DRY RUN: Simulating configuration change
Environment: prod
Key: auth_required
New value: false
🔄 Would change: auth_required
From: true
To: false
📁 Would override base.align value
$ node index.js explain --key=timeout --env=prod
🔍 EXPLAIN: Tracing configuration key
Key: timeout
Environment: prod
📊 Final value: 5000
🧱 Defined in: base.align = 3000
♻️ Overridden by: prod.align = 5000
📁 File: C:\dev\align-config\config\prod.align
$ node index.js diff --env1=dev --env2=prod
🔍 DIFF: Comparing dev vs prod
🔄 timeout:
dev: 3000
prod: 5000
🔄 debug:
dev: true
prod: false
🔄 port:
dev: 3000
prod: 80
🔄 database_url:
dev: "postgresql://localhost:5432/myapp_dev"
prod: "postgresql://prod-db:5432/myapp_prod"
🔄 log_level:
dev: "debug"
prod: "error"
.align syntaxsrc/environment.ts.env files to .align.env format for buildsENABLE_SIGNUP=true converts properlydev-alpha, dev-bravo, qa, prod.env files for deploymentenvironment.ts filesalign-config/
├── index.js # CLI entry point
├── parser.js # Core parsing and validation logic
├── lib.js # Library API for programmatic usage
├── config/ # Example configuration files
├── templates/ # Project templates (8 templates)
├── examples/ # Usage examples and demos
├── tests/ # Test files
└── output/ # Generated configuration outputs
# Install globally for CLI access
npm install -g align-config
# Use the align command
align --help
# Clone the repository
git clone <repository-url>
cd align-config
# Install dependencies
npm install
# Run directly with node
node index.js --help
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watch
ISC License - see LICENSE file for details.
We welcome contributions! Here's how to get started:
# Clone the repository
git clone <repository-url>
cd align-config
# Install dependencies
npm install
# Run tests to ensure everything works
npm test
git checkout -b feature/your-feature-namenpm testThanks to all contributors and the open source community for making this project possible!
Align - Making configuration safe, predictable, and unified across environments. 🚀
Overview:
Module-Specific Configuration lets you extract, validate, and export only the configuration keys needed by a specific module or package. This is perfect for microservices, plugin architectures, or any codebase where different parts of the system should only see the config they actually use.
Why it matters:
How it works:
config/modules/<module>/align.schema.json (or use package schemas)# List all modules with schemas
yarn align list-modules
# Output only the config for a module (JSON, YAML, or ENV)
yarn align module-config --module auth --env dev --format json
yarn align module-config --module email --format yaml
yarn align module-config --module database --format env
# Validate a module's config
yarn align validate-module --module auth --env dev
Suppose you have this config:
{
"service_name": "user-api",
"db_url": "postgres://...",
"auth_required": true,
"rate_limit": 100,
"email_smtp": "smtp://...",
"email_from": "noreply@yourapp.com"
}
auth_required, rate_limitemail_smtp, email_fromdb_urlExtract just what each module needs:
yarn align module-config --module auth
# { "auth_required": true, "rate_limit": 100 }
yarn align module-config --module email
# { "email_smtp": "smtp://...", "email_from": "noreply@yourapp.com" }
yarn align module-config --module database
# { "db_url": "postgres://..." }
Create a file like config/modules/auth/align.schema.json:
{
"type": "object",
"properties": {
"auth_required": { "type": "boolean" },
"rate_limit": { "type": "number" }
},
"required": ["auth_required", "rate_limit"]
}
You can use this for both local modules and package schemas (from node_modules).
⚠️ CRITICAL: .align files are NOT protected by .cursorignore
When migrating from .env files to .align files, secrets may become visible to AI tools like Cursor:
.env files are typically protected by .cursorignore.align files are NOT protected and can be read by AI assistantsalign repair or migrate-from-env copies secrets from .env to .align filesOption 1: Exclude Sensitive Fields (Recommended)
# Skip passwords, keys, tokens when migrating
align migrate-from-env --exclude-sensitive --env-files=.env,.env.prod
# Or use repair with exclusion
align repair --exclude-sensitive --auto
Option 2: Secrets-Only Migration
# Only migrate sensitive fields to separate secret management
align migrate-from-env --secrets-only --env-files=.env,.env.prod
Option 3: Explicit Consent (Use with Caution)
# Explicitly allow copying secrets (knowing the risks)
align migrate-from-env --include-secrets --env-files=.env,.env.prod
--exclude-sensitive when migrating existing projects.align files before committing.align files to .cursorignore if they contain secrets--protect-cursor to automatically update .cursorignore# Automatically create/update .cursorignore to protect .align files
align protect-cursor
# Or combine with migration
align migrate-from-env --exclude-sensitive --protect-cursor --env-files=.env,.env.prod
.cursorignore Addition:# Protect .align files that may contain secrets
config/*.align
config/align.schema.json
FAQs
Align - A domain-specific configuration language and toolchain
The npm package align-config receives a total of 0 weekly downloads. As such, align-config popularity was classified as not popular.
We found that align-config demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.