Getting Started

Prerequisites

You need a Cloudflare account with the Workers Paid plan enabled.
Set compatibility_date to 2025-11-17 or later.

Installation

pnpm create cloudflare@latest my-jobs --type=hello-world
cd my-jobs
pnpm add tsumugi

Setup

npx tsumugi init

When you run init in a new project, it creates the required Cloudflare resources and generates wrangler.jsonc, src/index.ts, src/performers/, and .dev.vars.
Finally, it applies the database migrations and exits.
If a step fails partway through, it prints a warning along with the command to run again.

If a wrangler configuration file already exists, init does not rewrite it and instead prints the content you need to add.
In this case, migrations are not applied either.
After you edit the configuration file, apply the migrations by following the printed steps.
The options and generated files are described in CLI.

The TSUMUGI_METRICS binding is optional.
If you do not set it, metrics are not recorded, but nothing else changes.
If you use Flow and scheduled execution, set additional bindings.
The configuration is described in wranglerのbinding, Flowの設定, and 定期実行の設定.

performer

You define job processing as a performer.
src/performers/hello.ts, generated by init, is the smallest example.
Rewrite the perform logic and the payload type to suit your use case.

// src/performers/hello.ts
import { Performer } from 'tsumugi/performer';

export class Hello extends Performer<{ name: string }, void, {}, Env> {
  async perform(payload: { name: string }): Promise<void> {
    console.log(`hello, ${payload.name}`);
  }
}

To add a performer, run add-performer.

npx tsumugi add-performer send-mail

This generates the performer file and appends one export line to src/performers/index.ts.

// src/performers/index.ts
export { Hello } from './hello.js';
export { SendMail } from './send-mail.js';

Worker

init generates src/index.ts with the following content.
Export performers from the Worker's entry point, and the exported name is used as the binding name.
The rules for binding names are described in binding名.

import { bearerAuth, defineTsumugi } from 'tsumugi';
import { ui } from 'tsumugi/ui';
import * as performers from './performers/index.js';

export * from './performers/index.js';

const tsumugi = defineTsumugi({
  performers,
  // Read from a secret; a hard-coded value would remain in the repository and the bundle
  auth: bearerAuth((env: Env) => env.TSUMUGI_TOKEN, { cookie: 'tsumugi_token' }),
  ui: ui({ tokenCookie: 'tsumugi_token' }),
});

// The Durable Object class must be re-exported
export { TsumugiJobShard } from 'tsumugi';

export default {
  ...tsumugi,
  async fetch(request, env, ctx) {
    const { pathname } = new URL(request.url);
    if (pathname === '/enqueue') {
      const id = await tsumugi.enqueue(env, { binding: 'Hello', payload: { name: 'world' } });
      return Response.json({ id });
    }
    // Pass everything else to the dashboard and the REST API
    return tsumugi.fetch!(request, env, ctx);
  },
} satisfies ExportedHandler<Env>;

The return value of defineTsumugi includes the fetch, queue, and scheduled handlers, as well as functions for enqueuing jobs and starting a Flow.
The full list of return values is in 設定, and the differences between enqueue methods are in ジョブの投入.

トークンの設定

If you do not specify auth, tsumugi.fetch responds to every request with 404.
The example above uses bearerAuth. In the local environment, it reads TSUMUGI_TOKEN defined in .dev.vars.
In production, register the secret by running the following command.

pnpm wrangler secret put TSUMUGI_TOKEN

動作確認

pnpm wrangler dev

When you access /enqueue, a Hello job is enqueued, and you receive a response of the form { "id": "..." } containing the job ID.
The enqueued job appears in the list on the dashboard (/).
When prompted for a token, enter the value of TSUMUGI_TOKEN in .dev.vars.
Immediately after init generates it, the value is dev-token.

次に参照するページ

• Performer: Define how jobs are processed.
• ジョブの投入: Scheduled execution, priority, and deduplication
• 実行の制御: Describes job state management, retry settings, execution rate limits, and execution guarantees.