Skip to content

v0.55.0

Choose a tag to compare

@baronunread baronunread released this 13 Nov 16:44
· 14 commits to main since this release
ab09748

Added

  • sproutboat init --template <name> writes a starter, with the shape of npm create cloudflare. Four starters, each standard Workers TypeScript that runs unchanged on workerd, with a README, tests (Node's own test runner, npm test), a tsconfig.json and a current worker-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) and jobs (a cron trigger that enqueues, a queue consumer with retries and idempotence, KV for state). --list-templates prints them. In a terminal init asks 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-install and --git / --no-git decide the two steps, and without a terminal nothing runs that a flag did not ask for. --git makes a first commit and does nothing inside an existing repository. init without --template is the hello starter it always was. The starters are embedded in the CLI as text (src/templates-embedded.ts, about 90 KiB, rewritten by bun run templates:embed), so the compiled executable needs no network or files beside it.
  • sproutboat dev --ip <address>. dev listens on 127.0.0.1 as before; --ip 0.0.0.0 makes it reachable from other machines, as wrangler dev --ip does.
  • A project with assets and no main is a Worker with only static assets, as in Wrangler. check, dev, build and deploy write a small entry into .sproutboat/assets-only.js that answers any request no file matched with env.<binding>.fetch(request), so not_found_handling (the single-page app shell, the nearest 404 page, or a plain 404) applies as it does on Cloudflare. The assets binding is assets.binding, or ASSETS when the config names none. Nothing else in the config changes: a project with a main is untouched, and one with neither still gets main must be a relative entry point under src/.
  • domains list works against a Cloud. It prints the app's routes from its record, marked built-in (under sproutboat.app) or custom. domains add, verify and delete on 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. domains takes --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, upload and the harness library moved to test/fixtures/; kitchen-sink and quote-service, which are deployed on Sproutboat Cloud and check every generation swap, moved to dogfood/. Their deployed names and the bun run kitchen-sink scripts are unchanged.

  • sproutboat types writes worker-configuration.d.ts, like wrangler types. The file declares interface Env (and Cloudflare.Env, which import { env } from "cloudflare:workers" reads) with a type per binding, so a handler is typed as export default { ... } satisfies ExportedHandler<Env> and env.KV, env.DB and the rest autocomplete and are checked. Vars are literal types (--strict-vars=false makes them string); a Durable Object binding is typed with its class when the entry is TypeScript, so await env.COUNTER.getByName("a").increment() is checked. The command takes Wrangler's positional (the file to write), --env-interface, --strict-vars, --include-runtime, --include-env and --check, which exits 1 when the file is missing or out of date by the hash in its header. --include-runtime references 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, DurableObjectNamespaceAsync with RPC stubs and getByName, DurableObjectStorageAsync with sql, FetcherAsync, R2ObjectBodyAsync.writeHttpMetadata, and a cloudflare:workers module (DurableObject, WorkerEntrypoint, RpcTarget, env). A project at or after compatibility date 2026-09-28 gets no global env; earlier ones still do. dev and deploy refresh the default file when a plain sproutboat types wrote it and the config has moved on, and leave one made with other flags alone.

  • deploy to a Cloud sends every binding. KV, D1, R2, queues, Analytics Engine, Durable Objects, rate limiters, the secret names, the assets binding and triggers.crons now go to the Cloud in the app record, in a build deploy and a module deploy alike, so examples/kitchen-sink runs 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 (DB is db; a queue's is its queue name), and d1 execute --remote and r2 object address the binding name as before. Every queue is also a queue consumer (max_batch_size, max_batch_timeout in milliseconds, max_retries, dead_letter_queue, with Cloudflare's defaults). An account-level id in 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 a durable_objects class the entry module does not export. --dry-run prints every binding, consumer and cron. A queue's retry_delay rides in the binding's config; the record has no field for it yet.

  • sproutboat dev relays 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 under dev. Before, the upgrade went through a plain fetch and the client got a protocol error. Stopping dev closes open sockets instead of waiting for them.

  • examples/kitchen-sink is 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 to quote-service, and secret names. Latency is measured in the worker with performance.now() and returned in Server-Timing; sizes are measured at build time. The Astro UI is gone; sproutboat.standalone.jsonc builds 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 extend DurableObject and are called over RPC (env.COUNTERS.getByName(name).increment()), a WorkerEntrypoint with 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 generated worker-configuration.d.ts. bun run examples:workerd translates each sproutboat.jsonc into a wrangler.jsonc, typechecks the entry against the runtime types wrangler types generates (no Sproutboat declaration in the program), runs it under workerd with wrangler dev and sends the same requests bun run examples sends the standalone binary; bun test runs it (so the CI check job does), and bun run examples:types verifies every worker-configuration.d.ts is current and typechecks, also under bun test. What is skipped is printed with its reason: analytics (query() is a Sproutboat extension) and outbound-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 with crypto.scryptVerify, the async echo, the egress refusals, /admin/stats, the direct-transfer tickets, the service-binding probe) moved out of examples/kitchen-sink/src/index.js into a worker of their own, with its own checks on both backends (bun run conformance, bun run conformance:standalone: 34 and 37 checks). kitchen-sink is the demo only: the dashboard's API, its limits, the chat room and its cron jobs (77 and 75 checks), no binary-fixture.bin in the deployed site, no ViewCounter or QUOTE_URL. Its routes under /api, /healthz and the chat (/api/chat, the ?probe=1 probe, the 96 KiB history cap) are unchanged. bun run kitchen-sink and kitchen-sink:standalone still exist and run the demo's checks and then the conformance fixture's. Both harness pairs now share examples/lib/backends.ts.

  • kitchen-sink is Workers-style and runs on workerd. Its entry points take env as an argument (fetch(request, env), scheduled(controller, env), queue(batch, env)), ChatRoom extends DurableObject, 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 a worker-configuration.d.ts and JSDoc types for env; the entry stays JavaScript because the Code panels excerpt it and the harness compiles it as it is.

Fixed

  • deploy to a Cloud no longer unroutes a custom domain. A deploy used to write the app's whole hosts list as just <project>.<team>.sproutboat.app, so a domain an operator had routed (sbcloud route add risulta.dev, or --host in tools/sbcloud-deploy) was dropped by the next sproutboat deploy, silently. It now sends hosts_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, as wrangler deploy leaves dashboard routes alone when the config declares none. Against a Cloud that predates hosts_patch the 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 types writes worker-configuration.d.ts, not sproutboat-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 tsconfig include. The old file declared env as a global for every date; the new one declares Env, and env only for dates before 2026-09-28, where it is the only way to reach the bindings.