Repository navigation
v0.55.0
Added
sproutboat init --template <name>writes a starter, with the shape ofnpm create cloudflare. Four starters, each standard Workers TypeScript that runs unchanged on workerd, with a README, tests (Node's own test runner,npm test), atsconfig.jsonand a currentworker-configuration.d.ts:realtime-room(a chat room on a Durable Object with hibernating WebSockets:acceptWebSocket, tags,serializeAttachment, presence, history),api-d1(a JSON API on D1 with a migration, validation and keyset pagination),site-api(static assets plus/api/*routes and KV in one Worker) andjobs(a cron trigger that enqueues, a queue consumer with retries and idempotence, KV for state).--list-templatesprints them. In a terminalinitasks for the template, the directory, whether to install dependencies and whether to use git (both default to yes);-y(--yes,--accept-defaults) takes every default,--install/--no-installand--git/--no-gitdecide the two steps, and without a terminal nothing runs that a flag did not ask for.--gitmakes a first commit and does nothing inside an existing repository.initwithout--templateis the hello starter it always was. The starters are embedded in the CLI as text (src/templates-embedded.ts, about 90 KiB, rewritten bybun run templates:embed), so the compiled executable needs no network or files beside it.sproutboat dev --ip <address>.devlistens on 127.0.0.1 as before;--ip 0.0.0.0makes it reachable from other machines, aswrangler dev --ipdoes.- A project with
assetsand nomainis a Worker with only static assets, as in Wrangler.check,dev,buildanddeploywrite a small entry into.sproutboat/assets-only.jsthat answers any request no file matched withenv.<binding>.fetch(request), sonot_found_handling(the single-page app shell, the nearest 404 page, or a plain 404) applies as it does on Cloudflare. The assets binding isassets.binding, orASSETSwhen the config names none. Nothing else in the config changes: a project with amainis untouched, and one with neither still getsmain must be a relative entry point under src/. domains listworks against a Cloud. It prints the app's routes from its record, markedbuilt-in(undersproutboat.app) orcustom.domains add,verifyanddeleteon a Cloud say that custom domains are added by an operator for now and that deploys keep them, instead of calling Community's/api/projects/<name>/domains, which a Cloud does not have.domainstakes--account <team>.
Changed
-
examples/holds only what a person reads. The conformance, stress, runtime-comparison, workers-verbatim and workers-contract fixtures, the Cloudflare pattern ports (cf-*),request,uploadand the harness library moved totest/fixtures/;kitchen-sinkandquote-service, which are deployed on Sproutboat Cloud and check every generation swap, moved todogfood/. Their deployed names and thebun run kitchen-sinkscripts are unchanged. -
sproutboat typeswritesworker-configuration.d.ts, likewrangler types. The file declaresinterface Env(andCloudflare.Env, whichimport { env } from "cloudflare:workers"reads) with a type per binding, so a handler is typed asexport default { ... } satisfies ExportedHandler<Env>andenv.KV,env.DBand the rest autocomplete and are checked. Vars are literal types (--strict-vars=falsemakes themstring); a Durable Object binding is typed with its class when the entry is TypeScript, soawait env.COUNTER.getByName("a").increment()is checked. The command takes Wrangler's positional (the file to write),--env-interface,--strict-vars,--include-runtime,--include-envand--check, which exits 1 when the file is missing or out of date by the hash in its header.--include-runtimereferences the runtime types the CLI ships instead of copying them in, and there is no--include-main-module. The ambient types gain the Workers shapes the runtime already had:ExportedHandler,ScheduledController,DurableObjectNamespaceAsyncwith RPC stubs andgetByName,DurableObjectStorageAsyncwithsql,FetcherAsync,R2ObjectBodyAsync.writeHttpMetadata, and acloudflare:workersmodule (DurableObject,WorkerEntrypoint,RpcTarget,env). A project at or after compatibility date 2026-09-28 gets no globalenv; earlier ones still do.devanddeployrefresh the default file when a plainsproutboat typeswrote it and the config has moved on, and leave one made with other flags alone. -
deployto a Cloud sends every binding. KV, D1, R2, queues, Analytics Engine, Durable Objects, rate limiters, the secret names, the assets binding andtriggers.cronsnow go to the Cloud in the app record, in a build deploy and a module deploy alike, soexamples/kitchen-sinkruns there with all its bindings. The warning that they were "not sent to the Cloud by the CLI yet" is gone. Each app's Cloud storage is private to it, so the record's resource id is the binding name in lowercase (DBisdb; a queue's is its queue name), andd1 execute --remoteandr2 objectaddress the binding name as before. Every queue is also a queue consumer (max_batch_size,max_batch_timeoutin milliseconds,max_retries,dead_letter_queue, with Cloudflare's defaults). An account-levelidin a binding is ignored with a warning. Before anything is uploaded the deploy refuses more than 16 crons, 16 queue consumers or 64 bindings (service bindings included), a cron or resource name the Cloud would refuse, and adurable_objectsclass the entry module does not export.--dry-runprints every binding, consumer and cron. A queue'sretry_delayrides in the binding's config; the record has no field for it yet. -
sproutboat devrelays WebSockets. The stable port now forwards an upgrade to the sprout and passes frames both ways, so a browser can use a WebSocket or a Durable Object chat underdev. Before, the upgrade went through a plainfetchand the client got a protocol error. Stoppingdevcloses open sockets instead of waiting for them. -
examples/kitchen-sinkis a dashboard. Every tile calls its real binding: a KV counter, a D1 guestbook that shows the SQL it ran, R2 upload and list, a Durable Object chat over WebSocket (hibernation API), a queue and cron feed read from D1, a service binding toquote-service, and secret names. Latency is measured in the worker withperformance.now()and returned inServer-Timing; sizes are measured at build time. The Astro UI is gone;sproutboat.standalone.jsoncbuilds the same app as a standalone binary. -
Every example is a standard Cloudflare Worker, and CI says so.
examples/*are rewritten as TypeScript in the Workers style:export default { async fetch(request, env, ctx) } satisfies ExportedHandler<Env>,scheduled(controller, env, ctx),queue(batch, env, ctx), Durable Objects that extendDurableObjectand are called over RPC (env.COUNTERS.getByName(name).increment()), aWorkerEntrypointwith an RPC method, every binding call awaited,await request.json(),Response.json(), and a schema created once instead of on every request. All are at compatibility date 2026-11-18, and each has a README (what it shows, run, deploy, curl lines) and a generatedworker-configuration.d.ts.bun run examples:workerdtranslates eachsproutboat.jsoncinto awrangler.jsonc, typechecks the entry against the runtime typeswrangler typesgenerates (no Sproutboat declaration in the program), runs it under workerd withwrangler devand sends the same requestsbun run examplessends the standalone binary;bun testruns it (so the CI check job does), andbun run examples:typesverifies everyworker-configuration.d.tsis current and typechecks, also underbun test. What is skipped is printed with its reason:analytics(query()is a Sproutboat extension) andoutbound-fetch(the private-address refusal is Sproutboat policy) send only the requests Workers can answer. examples/README.md states the two rules the examples follow: standard Workers style, and no test-only code in examples. -
examples/conformance: the binding conformance suite has its own fixture. The routes and vectors that existed only for tests (login and notes, the crypto vectors withcrypto.scryptVerify, the async echo, the egress refusals,/admin/stats, the direct-transfer tickets, the service-binding probe) moved out ofexamples/kitchen-sink/src/index.jsinto a worker of their own, with its own checks on both backends (bun run conformance,bun run conformance:standalone: 34 and 37 checks).kitchen-sinkis the demo only: the dashboard's API, its limits, the chat room and its cron jobs (77 and 75 checks), nobinary-fixture.binin the deployed site, noViewCounterorQUOTE_URL. Its routes under/api,/healthzand the chat (/api/chat, the?probe=1probe, the 96 KiB history cap) are unchanged.bun run kitchen-sinkandkitchen-sink:standalonestill exist and run the demo's checks and then the conformance fixture's. Both harness pairs now shareexamples/lib/backends.ts. -
kitchen-sinkis Workers-style and runs on workerd. Its entry points takeenvas an argument (fetch(request, env),scheduled(controller, env),queue(batch, env)),ChatRoomextendsDurableObject, and its tables are created once per process instead of on every request. Running it under workerd found two bugs that Sproutboat's runtime had hidden, both fixed:env.SESSIONS.list("")(the pre-2026-10-25 argument, which throws on Workers) and a chat broadcast that sent to a socket already closing. It has aworker-configuration.d.tsand JSDoc types forenv; the entry stays JavaScript because the Code panels excerpt it and the harness compiles it as it is.
Fixed
deployto a Cloud no longer unroutes a custom domain. A deploy used to write the app's wholehostslist as just<project>.<team>.sproutboat.app, so a domain an operator had routed (sbcloud route add risulta.dev, or--hostintools/sbcloud-deploy) was dropped by the nextsproutboat deploy, silently. It now sendshosts_patch: { add: [that name] }, which the Cloud merges into the live list when the record is written (for a deploy from source, when the build is applied, so a domain added while it builds is kept too). Routes the deploy did not add stay, aswrangler deployleaves dashboard routes alone when the config declares none. Against a Cloud that predateshosts_patchthe CLI merges the live routes itself and says so. Needs no Cloud change to work, and is atomic once the Cloud has it.
Changed
sproutboat typeswritesworker-configuration.d.ts, notsproutboat-env.d.ts, and its positional is the output file. A positional that is an existing directory is still read as the project directory. The old file is removed when it is still exactly as the old command generated it; commit the new one and add it to your tsconfiginclude. The old file declaredenvas a global for every date; the new one declaresEnv, andenvonly for dates before 2026-09-28, where it is the only way to reach the bindings.