Quickstart
Create a task and a project, deploy it and hand the task off, all from one TypeScript file. About five minutes.
Install the SDK
The SDK is open source and typed end to end. It needs Node 20 or later.
npm install @scaffold-llc/sdkYou should see
added 1 package.ship.mtsimport { readFile } from "node:fs/promises";import { Scaffold } from "@scaffold-llc/sdk";Create a token
Create one with Write access in Settings, then Apps and tokens, and copy the workspace id beside it. The token is shown once, so save both to your environment now.
export SCAFFOLD_TOKEN=scf_live_7Hq2vN9xKc41PzT8mLw3RbYeD0aJexport SCAFFOLD_WORKSPACE=ws_01jbz5m8q6e4w3r2t1y0v9h8g7ship.mts// Reads SCAFFOLD_TOKEN from the environmentconst scaffold = new Scaffold();const workspace_id = process.env.SCAFFOLD_WORKSPACE!;Put the work on the board
Create the task first so the rest of the work links back to it. The response includes its key, like
PIN-142.ship.mts// Plan: put the work on the boardconst task = await scaffold.task.create({ workspace_id, title: "Ship the booking page", status: "doing", labels: ["launch"],});console.log(`Task ${task.key} is on the board`);Create the project
A project is the app the work ships as. It starts from the empty template, which every plan can use, and a Free workspace holds 2 projects. Its name must be new in the workspace, so change
pinecrest-webbefore you run the file again.ship.mts// Project: create the project the work ships inconst project = await scaffold.project.create({ workspace_id, name: "pinecrest-web",});console.log(`Project ${project.slug} is ready`);Zip the app
Zip the files in the app's folder, not the folder itself, so they sit at the zip's root. Run this in the app's folder; it writes
pinecrest-web.zipbeside it, where you run the file.- A static site has
index.htmlat the root, with its other files beside it. - A Node app has
package.jsonat the root, with astartscript or amainfile. Leave outnode_modulesand build output, as the deploy installs and builds it. With nostartscript, a build that makesindex.htmlindist,buildoroutdeploys as a static site.
# macOS and Linuxzip -r ../pinecrest-web.zip . -x 'node_modules/*' '.git/*'# Windows PowerShelltar.exe -a -cf ..\pinecrest-web.zip --exclude node_modules --exclude .git *ship.mtsconst archive = await readFile("pinecrest-web.zip");- A static site has
Deploy the project
Static sites deploy on every plan: Free deploys 15 times in any 24 hours and builds for 120 minutes a month. Server code needs the Paid plan, which builds for 1,000 minutes a month. Upload the app's code as a zip, then deploy it: it goes live once it accepts connections on
PORTwithin 30 seconds, and every deploy gets its own address. One that never starts fails and the live one keeps serving.- An app with no web page, like a queue consumer, is a worker: add
"scaffold": { "kind": "worker" }to its package.json. A worker needs the Paid plan, never sleeps and goes live once it builds, after its release command if it has one. On Free it stops until the workspace upgrades. - The app answers at its project's address under
scaffold.host. Untilscaffold.hostis on the Public Suffix List, browsers count every app there as one site, so don't rely on cookies shared acrossscaffold.host: one your app sets withDomain=scaffold.hostis dropped before it reaches the browser, but a page on another app can still set one from its scripts. Set cookies without aDomainand with the__Host-prefix, which no other app can set or replace. A custom domain is its own site, so an app there can set cookies for its whole domain. - The first deploy of server code creates the app's own Postgres database, which it reads from
DATABASE_URL; past its plan's quota it turns read-only, and past twice the quota the app cannot connect. - Before each deploy first starts, the database is dumped. A release command, like a migration, runs after that dump and before the deploy goes live; if it fails, the live one keeps serving. To undo a deploy that went live, roll back to the one before it, without a rebuild, and put back the database from that dump if you want, which shows the maintenance page until it is back. The five newest deploys that were live stay ready for a rollback; older ones are deleted from the host.
- To deploy from GitHub instead, connect a repository with
github.connect: each push to its branch uploads and deploys that commit, running the release commandgithub.release_command_setsets.
ship.mts// Deploy: upload the app's code and deploy itconst archive = await readFile("pinecrest-web.zip");await scaffold.source.upload({ project_id: project.id, archive });const deploy = await scaffold.deploy.create({ project_id: project.id });const build = await scaffold.deploy.logs({ deploy_id: deploy.id, kind: "build" });for (const line of build.lines) console.log(line.text);- An app with no web page, like a queue consumer, is a worker: add
Hand it off
Move the task to review. The move shows in the activity rail as yours, with Undo.
ship.mts// Hand off: move the task to reviewawait scaffold.task.move({ task_id: task.id, column: "review" });console.log("The task is in review");Run it
Run the file with your token and workspace in the environment. The task, the project and the move all show in the console's activity rail as yours.
npx tsx ship.mtsTerminalPress Run to see what it prints.You should see four lines. On the board, the task is now in review.
import { readFile } from "node:fs/promises";import { Scaffold } from "@scaffold-llc/sdk"; // Reads SCAFFOLD_TOKEN from the environmentconst scaffold = new Scaffold();const workspace_id = process.env.SCAFFOLD_WORKSPACE!; // Plan: put the work on the boardconst task = await scaffold.task.create({ workspace_id, title: "Ship the booking page", status: "doing", labels: ["launch"],});console.log(`Task ${task.key} is on the board`); // Project: create the project the work ships inconst project = await scaffold.project.create({ workspace_id, name: "pinecrest-web",});console.log(`Project ${project.slug} is ready`); // Deploy: upload the app's code and deploy itconst archive = await readFile("pinecrest-web.zip");await scaffold.source.upload({ project_id: project.id, archive });const deploy = await scaffold.deploy.create({ project_id: project.id });const build = await scaffold.deploy.logs({ deploy_id: deploy.id, kind: "build" });for (const line of build.lines) console.log(line.text); // Hand off: move the task to reviewawait scaffold.task.move({ task_id: task.id, column: "review" });console.log("The task is in review");