WebKit

Infrastructure-as-code framework for full-stack web applications

Documentation · Getting Started · Examples ·

WebKit

WebKit is a CLI tool that transforms a single app.json manifest into production-ready infrastructure and CI/CD pipelines. It generates Terraform configurations, GitHub Actions workflows, and project files - all without cluttering your project repository with infrastructure code.

Key Features:

• Single source of truth: Define apps, resources, and environments in app.json
• Clean repositories: No infra/ folder needed - workflows contain everything
• Infrastructure as code: Automated Terraform generation with centralized modules
• Secrets management: Built-in SOPS/Age encryption with environment-specific decryption
• CI/CD automation: GitHub Actions workflows for plans, deploys, and drift detection
• Developer experience: Idempotent updates, local testing, and zero-config defaults

Note: For user documentation and guides, visit webkit.ainsley.dev

Packages

• 
• 
• 

Installation

Quick install:

curl -sSL https://raw.githubusercontent.com/ainsleydev/webkit/main/bin/install.sh | sh

Or download binaries from the latest release.

Verify installation:

webkit version

Development Setup

Run the following to get setup with webkit.

make setup

Prerequisites

• Go 1.23 or higher
• pnpm (for task runners and local workflow testing)
• act (for testing GitHub Actions locally)
• age (for secrets encryption)

Project Structure

webkit/
├── cmd/webkit/          # CLI entry point
├── internal/
│   ├── appdef/          # App manifest parsing and validation
│   ├── cmd/             # CLI command implementations
│   │   ├── cicd/        # GitHub Actions workflow generation
│   │   ├── env/         # Environment variable management
│   │   ├── docs/        # Documentation generation
│   │   ├── files/       # Project file generation
│   │   ├── infra/       # Terraform infrastructure commands
│   │   └── secrets/     # SOPS encryption/decryption
│   ├── infra/           # Terraform wrapper and state management
│   ├── manifest/        # File tracking and manifest source tagging
│   ├── scaffold/        # Template scaffolding system
│   ├── secrets/         # SOPS/Age integration
│   ├── templates/       # Embedded project templates
│   └── util/            # Shared utilities
└── platform/            # Terraform modules (separate infra repository)
    ├── providers/       # Provider-specific modules (DO, B2, etc.)
    └── modules/         # Orchestration modules (apps, resources)

Architecture Overview

Key Components:

• appdef: Defines the structure of app.json and handles unmarshaling with validation
• scaffold: Template rendering engine with file tracking and idempotent updates
• manifest: Tracks which files are generated and their sources (app/resource/project)
• secrets: SOPS integration for encrypting/decrypting environment variables
• infra: Terraform wrapper that manages state and tfvars generation

Local Workflow Testing

You can simulate GitHub Actions workflows locally using act. act runs from your local computer, whatever files are currently in your working directory, including any uncommitted changes.

# Test lint workflow
pnpm act:lint

# Test test workflow
pnpm act:test

# Dry-run release workflow (shows what would run without executing)
pnpm act:release

Releasing

For maintainers only

WebKit uses GoReleaser for automated releases. The release process is triggered by creating and pushing a git tag.

Quick Release

Use the interactive tag tool:

pnpm tag

This will guide you through:

1. Choosing between creating or deleting a tag.
2. Selecting the version bump type (patch, minor, or major).
3. Confirming the version.
4. Creating and pushing the tag.

When a tag is pushed, the version will be injected then GitHub Actions automatically triggers the GoReleaser workflow, builds binaries for each platform and creates a GitHub release with the binaries attached.

Semantic Versioning

WebKit follows Semantic Versioning.

• Patch (v1.0.1): Bug fixes and minor changes
• Minor (v1.1.0): New features, backwards compatible
• Major (v2.0.0): Breaking changes

Publishing npm packages

WebKit uses Changesets for automated package versioning and publishing. When merging changes to npm packages in the packages/ directory, create a changeset to document the change and specify the version bump type. See packages/README.md for detailed instructions.

Copyright

You may not, except with our express written permission, distribute or commercially exploit the content found within this repository or any written text within this repository. Nor may you transmit it or store it in any other website or other form of electronic retrieval system.

Any redistribution or reproduction of part or all of the contents in any form is prohibited other than the following:

• You may print or download to a local hard disk extracts for your personal and non-commercial use only.
• You may copy the content to individual third parties for their personal use, but only if you acknowledge the website as the source of the material,

License

Code Copyright 2023 ainsley.dev. Code released under the BSD-3 Clause.