Publishing

What one sf publish actually does, which files it sends, how change-only uploads work, and what the receipt tells you.

After this page you can publish a folder from the CLI, the dashboard, or the API, predict which files make it and which get dropped, and read a receipt well enough to know whether your site is live.

The mental model

One publish is four steps.

1. Declare. The client lists every file it wants the version to hold, with a size and usually a sha256.
2. Upload. The server answers with upload targets for the bytes it does not already have. Everything else is reused.
3. Finalize. The version compiles into its served form and becomes ready.
4. Promote. The live pointer moves to it.

sf publish runs all four and prints a URL. POST /v1/publish collapses all four into one request and returns a receipt. The steps are separately addressable when you need them, which is how a resumed upload and a promote-later flow work.

Publish

CLIDashboardAPI

sf publish ./dist

With no argument it publishes the current directory, building it first if it detects a project. --message records a changelog entry on the version. --target preview creates a ready version without moving live.

sf publish ./dist --message "Fix pricing table"
sf publish --target preview --json

Drop takes a folder, a .zip, or a single index.html. Drag it onto the window, or use Choose a folder or Choose files. Pick a Team, a Destination of New space or Existing space, and for an existing Space either Add & update or Replace all. Progress runs Prepare → Upload → Build → Go live.

For a Space you already have open, the topbar Publish button asks How do you want to publish? and offers Publish from Git, Drop files, Use the Spacefast CLI, or an agent.

curl -X POST https://api.spacefast.com/v1/publish \
  -H "Authorization: Bearer sfa_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/zip" \
  --data-binary @site.zip

createPublish also takes a JSON manifest, multipart form data, a single HTML document, or raw bytes for one file.

What gets uploaded

Publishing walks the directory and builds a manifest. Three things can happen to a path.

Dropped without complaint

Some paths are never worth failing a whole publish over, so they are dropped and counted instead. Exact names at any depth:

.DS_Store  .gitignore  .npmrc  .netrc
.env  .env.local  .env.production  .env.development  .env.test
_routes.json  .spacefast/state.json  .stattic/state.json

Whole directories at any depth: .git, .hg, .svn, .ssh, .aws, .cache, .turbo, .vercel, .netlify, .wrangler, node_modules, and .next/cache.

Anything that looks like a credential is dropped the same way: names starting .env., SSH private keys (id_rsa, id_ed25519, and friends), files named like a private key, and any .pem, .key, .p12, or .pfx.

Symlinks are skipped, not followed. The CLI prints Warning: skipped symlink <path> (symlinks are not published). for each one.

_headers and _redirects are convention files and always publish.

Rejected with an error

These fail the publish rather than getting dropped, because silently ignoring them would change what your site does.

Two artifacts claiming the same request route also stop the publish, so a lookup-order coin flip never decides which one visitors get.

Size and count

The file count is a platform ceiling: every claimed plan gets the same 100,000. Anonymous publishes run a tighter table.

Only changed bytes travel

Every declared file carries a sha256. The server compares your declaration against the version you are replacing, keeps the bytes it already has, and asks for the rest. The upload instructions come with a summary counting exactly that:

{ "upload": 3, "reused": 41, "ignored": 0 }

Deleting a file means leaving it out of the declaration. There is no delete list. That has one consequence worth knowing:

sf publish defaults to snapshot. POST /v1/publish defaults to additive. Set it with --publish-mode or the publishMode field.

Nothing changed

If your declaration reproduces the live version byte for byte, no version is created. The response comes back with a null version id and one info diagnostic:

oop_publish

That diagnostic is the only signal. There is no separate boolean.

One catch. A file declared without a sha256 cannot prove it is unchanged, so a manifest missing any hash always materializes a new version.

Waiting, or not

A publish holds one HTTP request open while the work runs, up to a 240 second ceiling. Past that the receipt degrades to next.action of poll and the work carries on in the background. You did not lose the publish.

Add ?async=1 to skip the wait and get an operation handle immediately. Only async=1 and async=true do that. async=0, async=false, and leaving it off all wait.

Reading the receipt

The parts you actually read:

next.action is the field to branch on. done means there is nothing left to do, and the hint says why, for example Live. Nothing left to do. An unpromoted outcome with done means the version is ready and you need to promote it yourself.

What the API accepts

POST /v1/publish sniffs the content type.

Static zip or a build

An archive takes one of two paths, decided from the file names alone without unpacking it.

A zip publishes directly as static files when it contains an index.html and no build markers. A build marker is a lockfile, a workspace root file, a framework config file, or a vercel.json, netlify.toml, or wrangler.toml. A package.json next to your index.html is enough to make it a build.

Everything else becomes a Build that installs and builds your project, then publishes the output. Tar and tar.gz are always builds, only zip has the static path.

When a publish fails