Quickstart
Install the CLI, scaffold a project and deploy it.
Prerequisites
- Node.js 18 or later, or Bun, with a package manager: npm, pnpm, Bun or Yarn. The
sproutboatpackage resolves a self-contained native binary for your platform. - An account on a platform you or your admin run. See Install the platform to run one, or Get access to join one. For a standalone binary you need neither.
The CLI compiles with the local C toolchain when there is one, and falls back to its own Zig otherwise, so a C compiler is optional.
Install the CLI
Install Sproutboat locally, in each of your projects. The CLI is the compiler, so pinning its version in package.json means a project builds the same way on every machine and in CI, and you choose when to update.
npm i -D sproutboatpnpm add -D sproutboatbun add -d sproutboatyarn add -D sproutboatBecause it is a local install, run it through your package manager: npx sproutboat <command>, or a package.json script such as npm run deploy. sproutboat init (below) adds the dependency and the dev, deploy and check scripts for you. To update, run the install command again with @latest; npx sproutboat --version shows what a project uses.
If you only want a few commands outside any project, such as sproutboat init, login or whoami, install it globally. A global install is not pinned to anything, so keep project builds on the local one. yarn global add is Yarn 1 only.
npm i -g sproutboatpnpm add -g sproutboatbun add -g sproutboatyarn global add sproutboatZero to deployed
Scaffold a project
npx sproutboat init hellopnpm dlx sproutboat init hellobunx sproutboat init helloyarn dlx sproutboat init helloyarn dlx needs Yarn 2 or later; with Yarn 1, run npx sproutboat init hello. It writes sproutboat.jsonc, src/index.js and a package.json that lists sproutboat in devDependencies with the dev, deploy and check scripts, under ./hello. An existing package.json keeps its fields, and a script with the same name is never overwritten. Then install:
cd hello\nnpm installcd hello\npnpm installcd hello\nbun installcd hello\nyarn installSign in once, from a browser
npx sproutboat login --api-url https://control.example.compnpm sproutboat login --api-url https://control.example.combunx sproutboat login --api-url https://control.example.comyarn sproutboat login --api-url https://control.example.comThis is the only step that needs a browser tab where you are signed in to the dashboard. It writes a long-lived token to ~/.config/sproutboat/credentials.json.
Edit the handler
Open src/index.js and make your changes. See The handler for the contract. dev runs it on this machine with real bindings and rebuilds on save.
npm run devpnpm run devbun run devyarn devDeploy
npm run deploypnpm run deploybun run deployyarn deploydeploy prints the URL and waits until it serves. Deploying an unchanged artifact is a no-op. npx sproutboat deploy does the same without the script.
Use TypeScript
The starter creates JavaScript. To use TypeScript, rename src/index.js to src/index.ts and set main in sproutboat.jsonc to "src/index.ts". The same dev, build and deploy commands work. Sproutboat bundles the file and removes TypeScript syntax before native compilation.
Run sproutboat types to generate binding types for your editor. To make type errors fail a build, add a tsconfig.json and run your own type check; sproutboat check checks runtime compatibility, not types. See Generated types.