tako-sdk-js

Imported from tako-sh/tako (.agents/skills/tako-sdk-js/SKILL.md). Install upstream with npx skills add tako-sh/tako --skill tako-sdk-js. Copyright stays with the author.

Tako SDK (tako.sh)

Runtime SDK for JavaScript/TypeScript apps deployed with Tako.

CRITICAL: The tako.sh package is required — it provides the entrypoint binaries that tako-server launches to run your app. Tako v0 uses plain ES modules everywhere — no Tako global. Runtime state (env, secrets, logger, build info) is accessed through the tako object from tako.sh; channels and workflows are imported from their own files.

CRITICAL: Framework helpers are opt-in. Use tako.sh/vite for Vite-based SSR frameworks (TanStack Start, Nuxt, SolidStart) and tako.sh/nextjs for Next.js standalone builds. Plain fetch-handler apps do not need either helper.

Core Concept: The Fetch Handler

Tako apps export a standard fetch handler as the default export:

// src/index.ts — this is a complete Tako app, no SDK import needed
export default function fetch(request: Request, env: Record<string, string>) {
  return new Response("Hello World!");
}

The handler signature is:

type FetchHandler = (request: Request, env: Record<string, string>) => Response | Promise<Response>;

Two export forms are supported:

// Form 1: default export is the fetch function
export default function fetch(req: Request, env: Record<string, string>) {
  return new Response("OK");
}

// Form 2: default export is an object with a fetch method
export default {
  fetch(req: Request, env: Record<string, string>) {
    return new Response("OK");
  },
};

Package Exports

Runtime state: tako.sh + tako.d.ts

tako generate emits a project-local tako.d.ts that augments tako.sh with typed environment names, typed tako.secrets keys, typed tako.storages names, channel metadata, workflow metadata, and user-defined env vars on process.env / import.meta.env. Tako-owned runtime values are typed through tako.sh exports such as tako.env, tako.build, and tako.dataDir, not through generated env-var globals. It keeps an existing declaration in app/, src/, or the project root; otherwise it writes to the first existing app/ or src/ directory, falling back to the project root. tako gen and tako g are aliases. When <app_root>/channels/ or <app_root>/workflows/ already exists, it also scaffolds empty definition dirs/files so they default-export defineChannel("<file-stem>") or defineWorkflow(...) stubs. Generated channel stubs use the file stem as the initial name, but tako generate does not rewrite existing explicit names. Generated TakoChannels entries use the declared name as the key and import("tako.sh").InferChannel<typeof import("./channels/<file>").default> for params, messages, and transport metadata. App code imports tako from tako.sh for project runtime state:

import { tako } from "tako.sh";

export default function fetch(request: Request) {
  tako.logger.info("request", { env: tako.env, build: tako.build });
  return new Response(
    `env=${tako.env} build=${tako.build} db=${tako.secrets.DATABASE_URL ? "ok" : "missing"}`,
  );
}

Surface

Secrets

tako.secrets is a Proxy that:

• Reads from a mutable store populated via fd 3 at startup (before user module is imported)
• Individual access works: tako.secrets.MY_KEY returns the string value
• Resists bulk serialization: toString(), toJSON() return "[REDACTED]"
• Is typed — the TakoSecrets interface augmentation in tako.d.ts lists every key present in .tako/secrets.json

The generated declaration file is type-only and is not imported by app code. In the browser, use tako.sh/client for channels, or tako.sh/react for channel hooks.

Cache

Server-side JavaScript can cache JSON-serializable values with explicit get/put/delete calls:

import { tako } from "tako.sh";

const profile = await tako.cache.get<Profile>(`profile:${userId}`);
if (!profile) {
  const fresh = await fetchProfile(userId);
  await tako.cache.put(`profile:${userId}`, fresh, { ttl: 60_000 });
}

await tako.cache.delete(`profile:${userId}`);

get(key) returns undefined for missing or expired keys. put(key, value, { ttl }) stores a JSON-serializable value; ttl is milliseconds. delete(key) removes one key. Native dev and deploy runtimes store cache entries in Tako-managed local SQLite outside app backups. Container releases do not expose TAKO_DATA_DIR in v0, so the cache helper is unavailable there.

Images

JavaScript can create public optimized image URLs with imageUrl:

import { imageUrl } from "tako.sh";

const photo = imageUrl("/photos/p_123.jpg");
const url = imageUrl("/avatars/u_123.png", { width: 640 });
const avifUrl = imageUrl("https://cdn.example.com/uploads/avatars/u_123.png", {
  width: 640,
  format: "avif",
});

The helper returns /_tako/image?src=...&w=... and is synchronous. Explicit URL quality values must also match [images].qualities (default [75]); SDK validation alone does not make a variant server-allowed. Width must be one of 320, 640, 960, 1200, 1920; quality is 1..100; format is webp or avif. Omit format for the optimizer default; Tako defaults to WebP, and format: "avif" is only valid when the app's [images].formats allows AVIF. Local public paths are available by default. Remote URLs must match [images].remote_patterns in tako.toml. Sources may be JPEG, PNG, GIF, WebP, or AVIF; animated GIF and WebP sources keep animation for optimized resize and crop URLs when emitted as WebP. AVIF output is available for still images; animated sources that request AVIF fall back to WebP. The server verifies the app's configured image guardrails before fetching or transforming.

Storage

Attach S3-compatible storage with the CLI, then use tako.storages.<name> from server-side app code:

tako storages add uploads \
  --provider s3 \
  --bucket app-uploads \
  --endpoint https://<account>.r2.cloudflarestorage.com \
  --region auto

import { tako } from "tako.sh";

const downloadUrl = await tako.storages.uploads.createDownloadUrl("receipts/r_123.png", {
  expiresInSeconds: 3600,
});

const uploadUrl = await tako.storages.uploads.createUploadUrl("avatars/u_123.png", {
  contentType: "image/png",
});

Storage URLs are private by default and signed with SigV4. createImageUrl(key, { public: true, width }) uses the storage public_base_url and the public image optimizer. Private storage image transforms are not implemented yet; use createDownloadUrl for private direct object URLs.

Vite Plugin

For SSR framework builds (TanStack Start, Nuxt, SolidStart, etc.):

// vite.config.ts
import { defineConfig } from "vite";
import { tako } from "tako.sh/vite";

export default defineConfig({
  plugins: [tako()],
});

On vite build: Emits <outDir>/tako-entry.mjs — a wrapper that normalizes the compiled server module into a default-exported fetch handler. Point main in tako.toml at this file.

On vite dev: Adds .test / .tako.test to allowed hosts and binds to 127.0.0.1. The bound port is reported to tako dev over fd 4.

Next.js Adapter

For Next.js standalone builds:

// next.config.mjs
import { withTako } from "tako.sh/nextjs";

export default withTako({});

withTako() sets output = "standalone" and points adapterPath at the Tako adapter shipped in the SDK.

On next build, the adapter:

• copies public/ into .next/standalone/public/ when standalone output exists
• copies .next/static/ into .next/standalone/.next/static/ when standalone output exists
• writes .next/tako-entry.mjs

The generated wrapper prefers .next/standalone/server.js when it exists. Otherwise it falls back to next start.

Point your Tako deploy main at .next/tako-entry.mjs, or use the nextjs preset so that default is provided for you.

Enabling .enqueue() / signal() / channel publish inside Next.js routes

The Tako Next.js adapter spawns next start as a child process and proxies to it, so the Tako SDK boot hook that runs in the parent process never fires inside your Next.js routes. Add a Next.js instrumentation.ts at your project root to install the runtime once per server process:

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { initServerRuntime } = await import("tako.sh/internal");
    initServerRuntime();
  }
}

After this, server-side routes and server actions can call defineWorkflow(...).enqueue(payload), signal(event, payload), and channel .publish(...) normally. Without it, those calls throw TakoError("TAKO_UNAVAILABLE", "Workflow runtime not installed. ...").

Types

import type { FetchHandler, TakoStatus } from "tako.sh/internal";

// FetchHandler = (request: Request, env: Record<string, string>) => Response | Promise<Response>

// TakoStatus — returned by the internal health endpoint
interface TakoStatus {
  status: "healthy" | "starting" | "draining" | "unhealthy";
  app: string;
  version: string;
  instance_id: string;
  pid: number;
  uptime_seconds: number;
}

Channels

Durable pub-sub routes with SSE and WebSocket transport, plus a bounded replay window. Channels are broadcast streams, not work queues: all authorized subscribers to the same channel read the same messages, and each subscriber keeps its own cursor. Production stores replay by deployed app id ({name}/{env}); local dev keeps replay in memory for the current daemon process.

Defining channels (file-based)

Drop one file per channel in <app_root>/channels/*.ts that default-exports defineChannel("<name>", ...).$messageTypes<M>(). The first argument is the wire channel name; generated files conventionally use the file stem, but discovery trusts the explicit name and rejects duplicate declared names. Server code imports the file directly to publish.

// <app_root>/channels/chat.ts
import { defineChannel } from "tako.sh";

interface ChatMessages {
  msg: { text: string; userId: string };
  typing: { userId: string };
}

export default defineChannel("chat", {
  paramsSchema: (t) => t.Object({ roomId: t.String({ minLength: 1 }) }),
  auth: {
    headerName: "authorization",
    async verify(input) {
      // input.params.roomId is typed; operation = "subscribe" | "publish" | "connect"
      const userId = await getUserId(input.header);
      if (!userId) return false;
      return { subject: userId };
    },
  },
  transport: "ws",
  replayWindowMs: 24 * 60 * 60 * 1000,
  inactivityTtlMs: 0,
  keepaliveIntervalMs: 25_000,
  maxConnectionLifetimeMs: 2 * 60 * 60 * 1000,
}).$messageTypes<ChatMessages>();

• The first argument is the channel name. defineChannel("chat") maps to /_tako/channels/chat; generated files conventionally use the file stem as the initial name.
• paramsSchema serializes to JSON Schema; tako-server validates query params before app auth. Params do not partition stored messages or fanout: all authorized roomId bindings above receive the same chat stream. Never use params as a room or tenant isolation boundary.
• .$messageTypes<M>() is a type-level narrower that declares the message map — runtime no-op. Omit for channels with no typed messages.
• auth is optional. Omit or set false for public channels.
• transport: "ws" enables WebSocket; the default is receive-only SSE. WebSocket frames are stored and broadcast as sent. Handle application mutations in your app's HTTP endpoints.
• Every publish is stored before delivery. Messages are not claimed or removed when one subscriber receives them. replayWindowMs defaults to 10 minutes and can be overridden per channel.
• SSE subscriptions reconnect until closed. React useChannel reconnects WebSockets with the latest replay cursor. Lower-level Channel.connect() returns a single socket, so non-React callers must implement WebSocket reconnection.

Auth return values: false deny · true allow anonymously · { subject } allow with identity.

Publishing messages (server-side)

Import the channel module. The export is a typed handle (unparameterized) or a callable taking its params (parameterized). publish payloads are type-checked against the declared message map.

// Unparameterized channel: direct surface
import status from "../channels/status";
await status.publish({ type: "ping", data: { at: Date.now() } });

// Channel with params: bind params, then publish
import chat from "../channels/chat";
await chat({ roomId: "room1" }).publish({
  type: "msg",
  data: { text: "hello", userId },
});

Subscribing / connecting (client-side)

In the browser, use the Channel class from tako.sh/client with the declared channel name and optional params. subscribe() returns an EventSource-shaped subscription; connect() returns a WebSocket-shaped socket.

import { Channel } from "tako.sh/client";

// SSE channel — listen to the raw EventSource
const status = new Channel("status");
const token = await getToken();
const sub = status.subscribe({ authorization: token });
(sub.raw as EventSource).addEventListener("message", (e) => {
  const msg = JSON.parse(e.data) as { type: string; data: unknown };
  // ...
});
sub.close();

// WebSocket channel with params
const room = new Channel("chat", "ws", { roomId: "room1" });
const socket = room.connect({ authorization: token });
(socket.raw as WebSocket).addEventListener("message", (e) => {
  const msg = JSON.parse(e.data);
  // ...
});
socket.send({ type: "typing", data: { userId: "me" } });

authorization is optional. Omit it for public or cookie-auth channels; use headers.Authorization when the app expects a custom authorization value.

For React apps, prefer useChannel from tako.sh/react — it wraps Channel with buffered state, reconnects, and an onMessage callback.

React

tako.sh/react exposes a single useChannel hook. SSE is the default; pass transport: "ws" for WebSocket.

import { useChannel } from "tako.sh/react";

function ChatRoom({ room, token }: { room: string; token?: string }) {
  const { messages, status, error } = useChannel<{ body: string }>("chat", {
    params: { roomId: room },
    authorization: token,
  });
  if (error) return <p>error: {error.message}</p>;
  return (
    <ul>
      {messages.map((m) => (
        <li key={m.id}>{m.data.body}</li>
      ))}
    </ul>
  );
}

WebSocket with send:

const { messages, send } = useChannel("chat", {
  params: { roomId: room },
  transport: "ws",
});

Return shape (ChannelConnection<T>): messages (capped at 500, oldest-first), status ("connecting" | "open"), error, clear(), and send(data) on WebSocket only.

Reacting to messages imperatively

Pass an onMessage handler when you want to fire a side effect on each incoming message (toast, external store, ref update) without wiring a useEffect around the messages array. The hook uses a latest-ref internally, so the handler does not need to be memoized and swapping it does not reconnect:

useChannel("notifications", {
  onMessage: (msg) => toast(msg.data.text),
});

Sharing one connection across components

Each useChannel call opens its own SSE/WebSocket. When multiple components in the same tree need the same channel, call the hook once in a provider and fan out via context:

const BroadcastCtx = createContext<ChannelConnection<Msg> | null>(null);

export function BroadcastProvider({ children }: { children: React.ReactNode }) {
  const ch = useChannel<Msg>("demo-broadcast");
  return <BroadcastCtx.Provider value={ch}>{children}</BroadcastCtx.Provider>;
}

export function useBroadcast() {
  const ctx = useContext(BroadcastCtx);
  if (!ctx) throw new Error("useBroadcast outside BroadcastProvider");
  return ctx;
}

One connection, one buffer, any number of consumers.

Network routes

Workflows

Durable background tasks with retries, schedules, and step checkpointing.

Authoring workflows

Drop a file in <app_root>/workflows/<name>.ts with a default export. The first arg is the workflow name (conventionally the kebab-case file basename), the second is a WorkflowOpts object with handler plus optional runtime settings:

// <app_root>/workflows/send-email.ts
import { defineWorkflow } from "tako.sh";

export default defineWorkflow<{ userId: string; to: string }>("send-email", {
  retries: 3, // retries after first attempt (default 2)
  schedule: "0 9 * * *", // cron: daily at 9am (5-field)
  worker: "email", // worker group; omitted means "default"
  local: true, // optional per-server local storage/cron for multi-server deploys
  backoff: { base: 1_000, max: 3_600_000 }, // exponential backoff
  handler: async (payload, ctx) => {
    ctx.logger.info("send-email started");
    const user = await ctx.run("fetch-user", (step) => {
      step.logger.info("fetching user");
      return db.users.find(payload.userId);
    });
    await ctx.run("send", (step) => {
      step.logger.info("sending email");
      return sendEmail(user, payload.to);
    });
  },
});

Use local: true only when per-server local queues and cron are intentional. Multi-server workflows require the encrypted postgres_url credential unless every JavaScript workflow is local. Multi-server channels always require postgres_url so all servers share publish and replay state.

Enqueuing

Import the workflow module. The default export is a typed handle with .enqueue(payload, opts?) — payload is constrained to the declared P.

import sendEmail from "../workflows/send-email";

await sendEmail.enqueue({ userId: "u1", to: "a@b.c" });

await sendEmail.enqueue(payload, {
  runAt: new Date(Date.now() + 60_000), // delay
  retries: 9, // override workflow default
  id: "digest:2026-04-14", // the actual run ID
});

Omit id to generate a new run ID. A supplied ID reuses the retained run in any status when the workflow and payload match. A different workflow or payload conflicts. IDs are unique within the app and environment, must contain 1–255 bytes with no NUL characters, and remain reserved until history is deleted. Finished history is retained for 184 days by default; [workflows].retention can override it or use "forever".

No generated file is needed for workflow enqueue typing — the types flow from the workflow module itself.

Workflow context (ctx)

The handler's second argument is the workflow context. Use ctx in examples.

ctx.run options:

• retries?: number — in-step retry attempts (default 0)
• backoff?: { base?, max? } — in-step backoff
• retry: false — any throw inside fn immediately fails the run

The ctx.run(name, fn, opts?) callback receives a step context named step.

ctx.waitFor options:

• timeout?: number — ms until the step resolves to null (default: park indefinitely)

Signals

// Wake all waitFor("approval:order-abc") calls with a payload
import { signal } from "tako.sh";
await signal("approval:order-abc", { approved: true });

Run lifecycle

pending → running → succeeded | cancelled | dead

• Throwing a regular error triggers the run-level retry path (exponential backoff).
• ctx.bail() → cancelled, no retries.
• ctx.fail() → dead, no retries.

tako.toml configuration

Production starts one scale-to-zero process per JavaScript worker group, selected by worker: "name". Each process receives runtime concurrency (currently 500) and exits after 300 seconds idle. Worker counts, concurrency, and per-server overrides in tako.toml are parsed but not yet applied by production supervision.

[workflows]                # parsed desired base settings
workers = 1                # not applied by production supervision yet
concurrency = 10

[workflows.email]          # parsed desired group override
workers = 2

[servers.lax.workflows]    # parsed desired server override
concurrency = 20

[servers.lax.workflows.email]
workers = 4

• The current production lane starts when runnable work appears and exits after 300 seconds idle.
• The precedence model is parsed and tested, but it is not connected to production worker supervision.

Common Mistakes

1. CRITICAL: Adding Vite to a plain fetch-handler app

// WRONG — plain fetch handler app doesn't need the Vite plugin
// vite.config.ts with tako() plugin + src/index.ts with a fetch handler

// CORRECT — omit Vite for a plain fetch-handler app; Vite dev servers need the plugin for readiness
// For plain apps, just export a fetch handler and set main in tako.toml

2. HIGH: Forgetting the Next.js helper for standalone deploys

// WRONG — plain Next config without the Tako helper
export default {};

// CORRECT — let Tako configure standalone output and adapterPath
import { withTako } from "tako.sh/nextjs";

export default withTako({});

3. HIGH: Serializing the secrets object

import { tako } from "tako.sh";

// WRONG — bulk access is redacted
console.log(JSON.stringify(tako.secrets)); // "[REDACTED]"

// CORRECT — access individual secrets by name
const dbUrl = tako.secrets.DATABASE_URL;