Version: 4.0.0-preview

Templates

ExpressoTS CLI uses a dynamic template system that allows the community to contribute and customize templates for CI/CD pipelines, Docker configurations, Kubernetes manifests, and migration guides.

Overview

The template system features:

Remote Templates: Automatically fetched from GitHub
Local Caching: Templates cached locally for offline usage
Community Contributions: Anyone can contribute templates
Version Management: Templates are versioned independently
Embedded Fallback: CLI works offline with embedded templates
Customizable: Use your own template repository

Template Sources

Templates are fetched in the following order:

Local Cache (~/.expressots/cache/templates/) - 24-hour TTL
Remote Repository (GitHub: expressots/templates)
Embedded Fallback (Built into CLI)

This ensures the CLI always works, even offline.

Available Templates

CI/CD Pipelines

Generate CI/CD pipelines for multiple platforms:

expressots cicd generate github --strategy basic
expressots cicd generate gitlab --strategy comprehensive
expressots cicd generate circleci --strategy security-focused

Supported Platforms:

GitHub Actions
GitLab CI
CircleCI
Jenkins
Bitbucket Pipelines
Azure DevOps

Strategies:

basic - Lint, test, build
comprehensive - Adds security scanning, E2E tests, Docker builds
security-focused - Maximum security with Trivy, Snyk, OWASP checks

Docker Templates

Generate Docker configurations:

expressots containerize docker --env production
expressots containerize docker --env development

Templates:

Dockerfile (production)
Dockerfile.development
docker-compose.yml
docker-compose.development.yml

Kubernetes Templates

Generate Kubernetes manifests:

expressots containerize k8s

Templates:

Deployment
Service
ConfigMap
Ingress

Migration Templates

Generate migration guides and configurations:

expressots migrate generate --from heroku --to railway

Supported Migrations:

Heroku → Railway/Render/Fly.io
Docker Compose → Kubernetes
Generic migrations to major cloud providers

Managing Templates

List Available Templates

# List all templates
expressots templates list

# Filter by category
expressots templates list --category cicd

# Filter by platform
expressots templates list --platform github

Update Template Cache

Fetch the latest templates from the remote repository:

expressots templates update

This command:

Fetches the latest manifest.json from GitHub
Downloads updated templates
Caches them locally for 24 hours
Shows update summary

Clear Template Cache

Remove all cached templates:

expressots templates clear

Show Template Information

# Show info for a specific category
expressots templates info cicd

# Show info for a specific platform
expressots templates info cicd github

Check Template System Status

expressots templates status

Displays:

Online/offline status
Cache statistics
Template source (remote or embedded)
Cache age and location

Custom Template Repositories

Using a Custom Repository

Point the CLI to your own template repository:

# Set custom repository
expressots templates repo set https://github.com/myorg/templates

# With specific branch
expressots templates repo set https://github.com/myorg/templates dev

# Reset to default
expressots templates repo reset

Local Development

Test templates locally before publishing:

# Use local directory
expressots templates repo set file:///path/to/local/templates

# Update cache
expressots templates update

# Test template generation
expressots cicd generate github

# Reset when done
expressots templates repo reset

Template Syntax

Templates use Mustache-like syntax for variable substitution:

Simple Variables

name: {{projectName}}
version: {{version}}

Conditional Blocks

{{#includeSecurity}}
security:
  - run: npm audit
{{/includeSecurity}}

Negative Conditionals

{{^isProduction}}
dev-tools:
  - nodemon
{{/isProduction}}

Loops

{{#each services}}
  - name: {{.}}
{{/each}}

Contributing Templates

Process Overview

Fork the expressots/templates repository
Edit template files
Update manifest.json with new version
Test locally
Submit pull request

Example: Adding a New CI Strategy

Let's say you want to add a "performance-testing" strategy for GitHub Actions:

Create the template file:

# templates/cicd/github/performance-testing.yml
name: Performance Testing CI

on:
  push:
    branches: [{{branch}}]

jobs:
  performance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
      - name: Install dependencies
        run: {{installCmd}}
      - name: Run performance tests
        run: npm run test:performance

Update manifest.json:

{
  "version": "1.1.0",
  "templates": {
    "cicd": {
      "github": {
        "performance-testing": {
          "path": "cicd/github/performance-testing.yml",
          "version": "1.0.0",
          "description": "Performance-focused testing pipeline"
        }
      }
    }
  }
}

Test locally:

expressots templates repo set https://github.com/YOUR_USERNAME/templates
expressots templates update
expressots cicd generate github --strategy performance-testing

Submit PR to expressots/templates

Versioning Guidelines

Patch (1.0.1):

Bug fixes
Typo corrections
Comment improvements

Minor (1.1.0):

New features
New variables added (backward compatible)
Enhanced functionality

Major (2.0.0):

Breaking changes
Removed variables
Changed template structure

Available Variables

When creating templates, you can use these variables:

CI/CD Templates:

{{projectName}}      - Project name
{{nodeVersion}}      - Node.js version
{{packageManager}}   - npm, yarn, or pnpm
{{strategy}}         - CI strategy name
{{branch}}           - Git branch
{{installCmd}}       - Install command (npm ci, etc.)
{{testCmd}}          - Test command
{{buildCmd}}         - Build command
{{lintCmd}}          - Lint command
{{dockerRegistry}}   - Docker registry URL
{{deployTarget}}     - Deployment target
{{port}}             - Application port

# Conditionals
{{#includeSecurity}}...{{/includeSecurity}}
{{#includeE2E}}...{{/includeE2E}}
{{#includeCoverage}}...{{/includeCoverage}}

Docker Templates:

{{nodeVersion}}           - Node.js version
{{packageManager}}        - Package manager
{{entryPoint}}            - Application entry point
{{port}}                  - Application port
{{healthCheckEndpoint}}   - Health check path
{{projectName}}           - Project name
{{installCommand}}        - Install command
{{buildCommand}}          - Build command

# Conditionals
{{#hasLocalDeps}}...{{/hasLocalDeps}}

Kubernetes Templates:

{{appName}}          - Application name
{{namespace}}        - K8s namespace
{{port}}             - Application port
{{replicas}}         - Number of replicas
{{memory}}           - Memory limit
{{cpu}}              - CPU limit
{{healthCheckPath}}  - Health check endpoint

Configuration

Template settings are stored in ~/.expressots/config.json:

{
  "templates": {
    "repository": "expressots/templates",
    "branch": "main",
    "cacheTTL": 86400
  }
}

Options:

repository - GitHub repository (format: owner/repo)
branch - Git branch to use
cacheTTL - Cache time-to-live in seconds (default: 24 hours)

Troubleshooting

Templates Not Updating

# Clear cache and force update
expressots templates clear
expressots templates update

Offline Usage

The CLI automatically falls back to embedded templates when offline. You'll see:

Source: (embedded fallback)

Custom Repository Issues

If your custom repository isn't working:

Check repository format: owner/repo (without https://github.com/)
Verify branch exists: Default is main
Ensure manifest.json is valid: Must be valid JSON at root
Check file structure: Must match expected paths in manifest

# Debug: Check current config
expressots templates status

# Reset to default if needed
expressots templates repo reset

Template Variables Not Rendering

If variables aren't being substituted:

Check variable names match exactly (case-sensitive)
Verify conditional syntax uses {{#var}} not {{if var}}
Test template locally before submitting PR

Best Practices

For Template Users

Keep cache updated: Run expressots templates update monthly
Use appropriate strategies: Start with basic, upgrade as needed
Review generated files: Always check outputs before committing
Test in CI/CD: Verify pipelines work in your environment

For Template Contributors

Document variables: Add comments explaining each variable
Test thoroughly: Test on multiple Node versions and platforms
Follow conventions: Match existing template style
Keep it simple: Start basic, add features incrementally
Include descriptions: Add helpful descriptions in manifest.json
Maintain backward compatibility: Don't remove existing variables

Examples

Generate GitHub Actions with Security

expressots cicd generate github \
  --strategy comprehensive \
  --security \
  --e2e \
  --coverage

Use Custom Templates for Organization

# One-time setup
expressots templates repo set mycompany/expressots-templates

# Team members automatically get company templates
expressots cicd generate github

Create Organization-Specific Templates

Fork expressots/templates
Add company-specific configurations
Update Docker registry URLs, deployment targets
Share repository with team
Everyone uses: expressots templates repo set mycompany/templates

expressots cicd - Generate CI/CD pipelines
expressots containerize - Generate Docker/K8s configs
expressots migrate - Generate migration guides
expressots costs - Pricing data management

Overview​

Template Sources​

Available Templates​

CI/CD Pipelines​

Docker Templates​

Kubernetes Templates​

Migration Templates​

Managing Templates​

List Available Templates​

Update Template Cache​

Clear Template Cache​

Show Template Information​

Check Template System Status​

Custom Template Repositories​

Using a Custom Repository​

Local Development​

Template Syntax​

Simple Variables​

Conditional Blocks​

Negative Conditionals​

Loops​

Contributing Templates​

Process Overview​

Example: Adding a New CI Strategy​

Versioning Guidelines​

Available Variables​

Configuration​

Troubleshooting​

Templates Not Updating​

Offline Usage​

Custom Repository Issues​

Template Variables Not Rendering​

Best Practices​

For Template Users​

For Template Contributors​

Examples​

Generate GitHub Actions with Security​

Use Custom Templates for Organization​

Create Organization-Specific Templates​

Related Commands​

Next Steps​