Hyphen
Log In

Builds

Learn how Hyphen CLI handles container and static site builds, from local file packaging and Docker image creation to artifact uploading and registry management.

The Hyphen CLI supports container images and static sites. Container builds use Docker and upload images to your project's container registries. Static builds upload a directory of finished website files to your project's site registries. GitHub setup is optional for local builds.

Table of Contents

How Builds Work

Use hx build to prepare a build for a later deployment. Use hx deploy to prepare a build and start a deployment. A dashboard deployment uses uploaded builds; it does not build files from your computer.

The --type flag selects the local build type:

Type Input Destination
docker (default) Source files and a Dockerfile, which Hyphen can generate. Every ready Container Registry on the project.
static A directory of finished website files. Every ready Site Registry on the project.

Static Site Builds

Build your frontend with its own build command first. Then supply the output directory as the final argument:

hx build --type static ./dist

Replace ./dist with your output directory. The directory must contain the files that the website serves, such as HTML, CSS, JavaScript, and images. For a site with no build step, supply the directory that contains those files.

The CLI does not run a frontend build tool for --type static. It does not require Docker or a Dockerfile. The directory must contain at least one regular file. The CLI rejects archives, individual files, and symbolic links as the directory argument. It also rejects symbolic links within the directory.

The static build process has these steps:

  1. The CLI reads the files and calculates their checksums.
  2. The CLI uploads the files to each ready Site Registry on the project.
  3. Hyphen records one Static build with an artifact for each registry after all uploads succeed.

A failed upload prevents build registration and deployment. Each provider applies its own file and size limits.

Site Registries

A static build requires at least one ready Site Registry connection on the project. Cloudflare supports site registries. A project can have one active Site Registry per provider.

Open the project's Settings → Integrations to check the registry status. For Cloudflare, add a Site Registry through this project connection flow. Hyphen creates a private R2 bucket for the site's builds.

The deployment must select a static provider with a matching build artifact. In the deployment form, select Static as the app type. Then select Cloudflare Workers under Deploy to. Static sites do not require a Container Registry or Cloud Workspace.

Deploy a Static Build

To upload the finished files and deploy the production environment, run:

hx deploy --env production --type static ./dist

To deploy an uploaded build, run:

hx deploy --env production --no-build --sites website:latest

Replace website with your app ID or alternate ID. --no-build does not need a local output directory. --sites selects static apps; --apps selects container apps. See the CLI reference for deployments with both app types and specific build selections.

Container Build Process

With the default --type docker, Hyphen:

  1. Locates your Dockerfile in the app folder
  2. If no Dockerfile exists, Hyphen Code generates one automatically based on your application's code
  3. Builds a Docker image using your Dockerfile
  4. Inspects the image to detect exposed ports
  5. Lists the project's container registries
  6. Authenticates with each registry and pushes the image
  7. Registers the build with Hyphen (one Docker artifact per pushed image)

The CLI reports build stages. Use --verbose when you need Docker build output for troubleshooting.

Finding Your Dockerfile

Hyphen automatically searches your app folder for a Dockerfile. If no Dockerfile is found, Hyphen Code will automatically generate one for you based on your application's code and dependencies. The generation process:

  • Analyzes your codebase and detects the programming language, framework, and build system
  • Creates an optimized Dockerfile tailored to your application
  • Saves the generated Dockerfile and .dockerignore locally (allowing you to review before committing)

Building the Docker Image

The Docker build process uses your Dockerfile to create a container image. Hyphen builds images targeting the linux/amd64 platform by default, ensuring compatibility with the most common cloud container services including AWS ECS, Azure Container Apps, and Google Cloud Run.

The image is tagged with your app alternate ID and the current Git commit SHA, shortened to 7 characters. Without Git history, the CLI uses 0000000. This metadata does not change the source of the build: it uses the current local files, including uncommitted changes allowed by your Docker build context.

Port Detection

After building the image, Hyphen inspects it to automatically detect which ports your application exposes. This information is used to configure networking and load balancing when your application is deployed.

Ports are detected from the EXPOSE directive in your Dockerfile.

Pushing to Container Registries

Once built, the image is pushed to every ready container registry configured on the project. Hyphen handles authentication automatically, logging in with the credentials configured when you set up each container registry connection.

The image is tagged appropriately for each registry type:

  • AWS ECR: Uses : as the separator with tag format registry:image-tag
  • Azure ACR: Uses / as the separator with tag format registry/image:tag
  • Google Artifact Registry: Uses / as the separator with tag format registry/image:tag

After each push completes, Hyphen logs out of that registry to avoid leaving credentials in your local Docker configuration.

Registering the Build

Builds can be associated with an environment or preview. A normal CLI deployment uses the build just created for the local app and uploaded builds for other included apps. Dashboard deployments and --no-build reuse uploaded builds for the selected deployment target.

Additional metadata is recorded with each build:

  • Artifacts for each project registry the image was pushed to (image URI and cloud target)
  • Exposed ports
  • Git commit SHA, or a fallback value when no commit exists
  • Build timestamp
  • Associated app and environment

This build record can be viewed in the Hyphen Dashboard and is used to track your deployment history. During a deployment run, each cloud instance uses only the artifact whose target matches that cloud.

Build Triggers

Builds can be triggered in several ways:

Via CLI

With the default build type, hx deploy builds your Docker image locally before it starts the deployment. For a static site, add --type static and the finished website directory. Add --verbose to see build details.

hx deploy

Plain hx deploy selects the environment of type development in the project linked in your app folder's .hx file. Use hx deploy --env production for an explicitly selected environment in that project.

Use Copy CLI command in the menu beside Deploy to copy the selected environment and organization. Run it from the app folder whose .hx file links to the project shown in the menu.

For more details on using the CLI for deployments, see Deployment Run Methods.

Via GitHub Actions

In GitHub Actions, the build runs on the workflow runner. The Hyphen/setup-hx-action installs the Hyphen CLI. For a static site, run your frontend build command before hx build --type static ./dist or hx deploy --type static ./dist.

For a detailed guide on setting up automated deployments with GitHub Actions, see GitHub Actions Deployment.

Container Registries

Build artifacts (Docker images) are stored in your project's container registries. Each registry is created in a connected cloud provider and is dedicated to your project.

A container build requires at least one ready Container Registry on the project. Container deployments also require a ready registry and Cloud Workspace on each target cloud. See the Deploy Quickstart for setup instructions.

When the project has registries on more than one cloud, a single build produces one artifact per registry and uploads each image accordingly. The build's details in the dashboard list every artifact.

Requirements

Initialize your app with hx init before either build type. Then check the requirements for your build type:

Requirement Container Static site
Local input Source files; Docker must be available in PATH and active. A directory of finished website files.
Build connection At least one ready Container Registry. At least one ready Site Registry.
Deployment connections A ready Container Registry and Cloud Workspace for each target cloud. A ready Site Registry and a matching artifact for each selected static provider.

GitHub integration and a Git commit are not required for a local build.

For container builds, Hyphen uses your Dockerfile if one exists. Otherwise, Hyphen Code generates one. --dockerfile cannot accompany --type static.

Skipping Builds

Use --no-build to deploy uploaded container or static builds:

hx deploy --env production --no-build

This is useful when you want to:

  • Redeploy the same build to a different environment
  • Retry a failed deployment without rebuilding
  • Test deployment configuration changes without code changes

When using --no-build, Hyphen reuses uploaded builds for the selected deployment target. It does not upload local changes. For a preview, retain both --preview and --prefix in the command.

Standalone Builds

Use hx build to prepare container images or static files for a later deployment. For static files, use hx build --type static ./dist.

For more information about the build command, see CLI documentation.

Next Steps