Cloud & Infrastructure

Maturity: Partial and integration-dependent · verified against Stacks source ce19440

Stacks.js includes:

@stacksjs/cloud helpers;
@stacksjs/deploy workflows;
typed config/cloud.ts integration;
a dependency on @stacksjs/ts-cloud;
AWS-oriented DNS, resource, and deployment helpers;
application deploy hooks and environment configuration.

The installed ts-cloud version is a moving companion dependency. Provider lists, service counts, preset counts, and topology maturity must be taken from that exact version’s source and tests. This page does not repeat them as timeless Stacks guarantees.

Configuration boundary

Stacks source exposes a tsCloud configuration that is checked against the ts-cloud CloudConfig type:

import type { CloudConfig as TsCloudConfig } from '@stacksjs/ts-cloud'

export const tsCloud: TsCloudConfig = {
  project: {
    name: 'my-app',
    slug: 'my-app',
    region: 'us-east-1',
  },
  cloud: {
    provider: 'hetzner',
  },
  mode: 'server',
  environments: {
    production: {
      type: 'production',
      deployBranch: 'main',
      region: 'us-east-1',
      variables: {
        NODE_ENV: 'production',
        LOG_LEVEL: 'info',
      },
    },
  },
  infrastructure: {
    compute: {
      instances: 1,
      size: 'small',
      disk: { size: 20, type: 'ssd', encrypted: true },
    },
  },
}

Use the options accepted by your installed @stacksjs/ts-cloud version. Do not copy a configuration from another release without typechecking and planning it.

Push-to-deploy branch mapping

deployBranch declares which source branch is allowed to update an environment. A provider-native deployment workflow SHOULD trigger only for that branch and SHOULD fail closed when a manual run selects a different ref. Keep the workflow trigger and cloud configuration aligned; an environment name alone does not prove that the intended source branch is being deployed.

This white paper currently defines one deployment environment: main maps to production. Its GitHub Actions workflow is generated by @stacksjs/ts-cloud 0.7.53 or newer, triggers on pushes to main, rejects a manual run from another ref, and deploys the whitepaper site through cloud deploy. Run bun run deploy:workflow to regenerate the workflow from cloud.config.ts. Adding staging or development later requires an explicit environment-to-branch mapping and matching generated workflow.

Stacks cloud helpers

The Stacks cloud package includes helpers for operations such as:

deployment-state checks;
security group and instance discovery;
jump-box add/remove paths;
Route53 hosted-zone and name-server operations;
selected cleanup flows;
domain workflows;
deployment hooks.

These helpers are provider-specific implementation surfaces, not protocol-level portable APIs.

Verification-first workflow

# Inspect installed command behavior.
buddy deploy --help
buddy cloud --help
buddy doctor

# Build and test the application before touching infrastructure.
buddy test
buddy test:types
buddy build

# Use the installed tool's plan/diff option before apply.
# Exact flags are version-specific; confirm with --help.

The protocol requires a reviewable plan for Complete conformance. If the installed provider path cannot show additions, updates, replacements, and removals before apply, treat that path as non-conformant for this requirement.

Deployment checklist

Version and provider

pin Stacks, Bun, and ts-cloud;
record the exact source/package revisions;
verify provider, region, architecture, and quotas;
test credentials and least-privilege permissions;
confirm which services have integration or deployment tests.

State and change safety

locate the source of truth for deployed state;
review replacement and deletion behavior;
protect data stores from accidental teardown;
define rollback for application and infrastructure changes;
make destructive commands require explicit confirmation in human workflows.

Secrets

inject secrets through a reviewed secret store;
avoid relying on the experimental environment-file public/private-key construction as a security boundary;
prevent secrets from entering client bundles, logs, plans, shell history, or build artifacts;
rotate and revoke credentials during incident exercises.

Data

run migration previews;
back up and restore-test databases;
verify connection limits and pooling for serverless/concurrent workloads;
define retention, encryption, and deletion policies;
test queue retry/idempotency behavior across deploys.

Operations

verify liveness and readiness from the load balancer’s perspective;
make request IDs visible in logs;
test alerting, log access, and incident rollback;
set cost and quota alarms;
smoke-test from outside the provider network.

Server, serverless, and hybrid language

The Stacks configuration and ts-cloud dependency discuss multiple deployment modes. A mode name is not proof that every combination of runtime, provider, data service, queue worker, scheduler, VPC, or custom domain has been tested together.

Publish a deployment matrix such as:

Provider	Mode	Runtime	Database	Queue	Tested revision	Result
example	server	Bun	SQLite/Postgres	database/Redis	commit	pass/fail

Until such a matrix exists, describe the integration as capability-specific rather than broadly production-ready.