DocsConnect

Quickstart

Create a task and a project, deploy it and hand the task off, all from one TypeScript file. About five minutes.

  1. Install the SDK

    The SDK is open source and typed end to end. It needs Node 20 or later.

    npm install @scaffold-llc/sdk

    You should see added 1 package.

    ship.mts
    import { readFile } from "node:fs/promises";import { Scaffold } from "@scaffold-llc/sdk";
  2. 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_01jbz5m8q6e4w3r2t1y0v9h8g7
    ship.mts
    // Reads SCAFFOLD_TOKEN from the environmentconst scaffold = new Scaffold();const workspace_id = process.env.SCAFFOLD_WORKSPACE!;
  3. 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`);
  4. 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-web before 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`);
  5. 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.zip beside it, where you run the file.

    • A static site has index.html at the root, with its other files beside it.
    • A Node app has package.json at the root, with a start script or a main file. Leave out node_modules and build output, as the deploy installs and builds it. With no start script, a build that makes index.html in dist, build or out deploys 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.mts
    const archive = await readFile("pinecrest-web.zip");
  6. 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 PORT within 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. Until scaffold.host is on the Public Suffix List, browsers count every app there as one site, so don't rely on cookies shared across scaffold.host: one your app sets with Domain=scaffold.host is dropped before it reaches the browser, but a page on another app can still set one from its scripts. Set cookies without a Domain and 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 command github.release_command_set sets.
    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);
  7. 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");
  8. 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.mts
    Terminal
    Press Run to see what it prints.

    You should see four lines. On the board, the task is now in review.

ship.mts
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");