tako-sh/tako/tako-sdk-js

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 TanStack Start or another Vite build whose server entry exports a fetch handler, and tako.sh/nextjs for Next.js. Vite alone does not establish framework compatibility. Plain fetch-handler apps do not need either helper. Select the matching guide at https://tako.sh/docs/framework-guides/.

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, store 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 realtime clients, or tako.sh/react for 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.

Use imageSrcSet for responsive public images. It returns { src, srcSet, sizes } for an <img> element:

import { imageSrcSet } from "tako.sh";
const hero = imageSrcSet("/images/hero.jpg", {
  width: 1200,
  layout: "constrained",
});
export function Hero() {
  return <img {...hero} alt="Application overview" />;
}

Layouts are constrained (the default), full-width, and fixed. Override widths and sizes for custom responsive markup; each width must be supported by the helper and allowed by the app's image configuration.

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. S3-compatible bindings use SigV4; local bindings use signed app-local GET/PUT routes under /_tako/storages/<binding>/<key>. createImageUrl(key, { public: true, width }) uses the storage public_base_url and the public image optimizer. createImageSrcSet(key, { public: true, width, layout }) returns responsive public image attributes. Private storage image transforms are not implemented yet; use createDownloadUrl for private direct object URLs.

Vite Plugin

For TanStack Start and other Vite builds with a fetch-compatible server entry:

// 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