How it works
shipzy is a command-line tool and a small set of resources in your AWS account. Here is what exists, what happens on a deploy, and how a visitor gets your site.
Three pieces
- The CLI (and the optional dashboard) runs on your machine. It reads your AWS profile, builds your project if you ask it to, and writes to your account.
- A stack in your AWS account, created by
shipzy init: storage for your sites, a CDN, a build project, and two small functions. You can see all of it in the AWS console. - A routing table at the edge that says which deploy each hostname should serve. Going live and rolling back are single writes to this table.
There is no fourth piece. We do not run a server, a database or a control plane.
What shipzy init creates
| Resource | What it is for |
|---|---|
| S3 bucket (private) | Every deploy of every project, and each project’s history |
| CloudFront distribution | Serves your sites over HTTPS, and is the only reader of the bucket |
| CloudFront Function and KeyValueStore | The router, and the routing table it reads on every request |
| CodeBuild project | Runs builds in your account (remote and GitHub deploys) |
| Two Lambda functions | One receives GitHub webhooks, one publishes a finished build |
| Secrets Manager (two secrets) | The webhook signing secret and your GitHub token |
| Parameter Store (on demand) | Your projects’ build-time environment variables, encrypted |
| Three IAM roles | Build, engine and webhook, each limited to this stack’s own resources |
Each project’s first deploy adds one more small stack: a CloudFront distribution that gives the project its own dxxxx.cloudfront.net address. A custom domain adds another, with its certificate and DNS records.
What happens when you deploy
- Detect and build. shipzy works out what kind of project it is (Vite, Create React App, or a static Next.js export), runs the install and build, and finds the output folder. If the project cannot be deployed, you get the reason before anything is built.
- Upload. The output goes to a brand-new folder in S3, named
my-app/d-20261031T130907-a6373d/. Nothing already in the bucket is touched. - Go live. The routing table entry for the hostname is pointed at the new folder. A failed deploy cleans up after itself and never changes what is live.
- Record. The deploy is added to the project’s history, and old ones beyond the newest ten (that are not live) are removed.
A remote or GitHub deploy does steps 1 and 2 inside CodeBuild, in your account, then asks the publish function to do steps 3 and 4. The webhook that starts a GitHub deploy checks GitHub’s signature before it does anything.
How a visitor’s request is served
- The request reaches CloudFront, and the router function runs at the edge.
- The router looks up the hostname in the routing table and gets something like
my-app/d-20261031T130907-a6373d. - It rewrites the path to that folder and S3 returns the file. Files with a hashed name are cached for a year; HTML is always revalidated.
How a path maps to a file depends on the kind of site. A single-page app answers every path with index.html. A static Next.js export answers /about with about.html, and an unknown path gets a real 404 with the site’s own 404 page. Each deploy remembers which style it uses, so rolling back across the two kinds works.
Rollback, previews and domains
- Rollback points the hostname at an older folder. No build, no upload, and it takes effect at the edge in about 30 seconds.
- Pull request previews are extra hostnames, such as
my-app-pr-12.preview.example.com, served from a wildcard domain. They are rebuilt on every push and removed when the PR closes, and only PRs from the same repository are built. - Custom domains get a free ACM certificate and a distribution of their own. If the domain is in Route 53, the DNS records are created for you; otherwise you get the exact records to add.
What it does not do yet
shipzy serves files. Server-rendered Next.js, API routes and long-running servers are not supported yet. They are on the roadmap, and the routing design already leaves room for them. See limits and roadmap.