Skip to content
Browse documentation
guides

Build and deployment

Prepare and review a native application payload, deploy exact bytes, and verify the selected target deliberately.

Choose the native deployment target

These examples use Smoothie Starter. Its default host is a long-running Bun/Elysia process serving built browser assets. Its optional Cloudflare lane prepares one Worker and static assets using the application's pinned Wrangler. That lane does not qualify SSR, authentication, databases, queues, other Starters, or arbitrary Wrangler configurations. Deployment can incur provider costs and requires separate explicit authority.

bash
bun run build
bun run start

For local production-like checks, keep the server running at http://127.0.0.1:42741 and follow Testing and verification. The CLI does not choose a remote host or deploy merely because a local build succeeds.

Prepare an immutable Cloudflare payload

From the adopted app, install dependencies and use its Cloudflare configuration and typecheck scripts. Build plans inspect metadata only. Replace the placeholder with the returned data.planId before executing the same plan. Use a new output directory whose parent exists; do not reuse a previously prepared payload directory.

bash
smoothie project build . --target cloudflare --output ../prepared-a --format json
smoothie project build . --target cloudflare --output ../prepared-a \
  --run --expect-plan <build-plan-id>

Execution delegates to native tools and records the Worker/assets inventory. Build scripts are trusted code and can read local values or contact services. Review the prepared files for embedded secrets and intended behavior. Build plans do not fingerprint every application source file; deployment approval binds the resulting artifact instead.

bash
smoothie project preview ../prepared-a --project . --format json
smoothie project preview ../prepared-a --project . --run --expect-plan <preview-plan-id>

Review the first preview result before replacing its placeholder. Preview runs a temporary copy through local Wrangler, normally at http://127.0.0.1:8787. It neither rebuilds nor uploads. Keep it running while testing; Ctrl-C stops the session. This is native execution of trusted Worker code, not a sandbox or proof of remote compatibility.

Review identity and authorize the exact upload

bash
smoothie project connect . --target cloudflare
smoothie project connect . --target cloudflare --run

The first command plans; the second queries through native Wrangler authentication. If native OAuth login or renewed consent is required, explicitly add --login to the run command. Wrangler owns the credential session. Login establishes identity, not permission to upload. Select the intended account and Worker name yourself.

bash
smoothie project deploy ../prepared-a --project . \
  --account <account-id> --name <worker-name> --expect-target absent \
  --output ../attempt-a --format json

Replace the account/name placeholders before planning. Use absent for a new Worker or present for an existing one, including updates. Review the offline plan, then repeat the exact command with --run --expect-plan <deployment-plan-id>. Execution checks the target expectation and uploads the reviewed bytes without rebuilding. A refusal requires investigation and a new review, not automatic switching of the expectation.

For scoped-token automation, add --auth token to both plan and execution and supply CLOUDFLARE_API_TOKEN through secure environment configuration. Do not put token values in arguments, files, or chat. OAuth remains the default; an ambient token is not a fallback. Every deployment needs a fresh attempt directory. Keep it as operation evidence.

Distinguish submission, traffic, and application health

bash
smoothie project status ../attempt-a
smoothie project verify --attempt ../attempt-a
smoothie project verify --attempt ../attempt-a --run

Status without --run reads retained evidence only. Verification first plans, then on explicit execution queries the recorded version and runs the application's declared test:deployment script only when that version is observed at 100% traffic. Keep the same --auth token choice if used for deployment. Missing scripts, denied queries, partial traffic, or ambiguous URLs block checks. Install the app's Playwright browser beforehand.

If the upload outcome is unknown, inspect the attempt and provider history before retrying. A status query can be requested with project status and an explicit --run; it never retries uploads. A failed application check does not undo deployment. Restoring an older retained payload requires a new reviewed deployment with --expect-target present; it does not restore databases, secrets, or other remote state.