DEV Community: Harshil Agrawal

Could Cloudflare Computer Simplify PromptMotion?

Harshil Agrawal — Mon, 03 Aug 2026 17:59:06 +0000

I wired together a filesystem, a container integration, an asset transfer path, agent tools, and a preview server to make PromptMotion work. Each part is reasonable on its own. The complexity comes from making all of them agree on where the project files live.

And today, Cloudflare published @cloudflare/computer. It gives a Durable Object a persistent filesystem and lets multiple execution backends operate on the same files. That is almost exactly the abstraction I wish I had when I started PromptMotion.

Cloudflare Computer would not replace PromptMotion's domain logic. It could replace the glue that moves project files between my agent, Durable Object, and render container.

I have not migrated yet. This is my current assessment of which problems Computer could solve, which parts would stay, and how I plan to validate the idea.

I checked the details below against the package README and runnable examples. The repository's docs/ directory is explicitly forward-looking and does not always describe what the package ships today.

Why PromptMotion Needs So Much Infrastructure

PromptMotion turns a text prompt into a video composition. The agent writes a HyperFrames project made from HTML and GSAP timelines. The user sees a live browser preview and can render the same composition to an MP4.

That product flow creates five infrastructure requirements:

Project files must survive Durable Object restarts.
The model needs safe tools for reading and editing those files.
Final rendering needs a Linux container with Chromium and FFmpeg.
The project and its assets must move into the container, and the MP4 must come back out.
A browser-facing server must turn project files into an interactive preview.

Today, those requirements use separate paths:

                              +-> custom file tools
                              |
Agent -> @cloudflare/shell ---+-> generation archives
                              |
                              +-> preview handler -> ProjectAgent RPC -> R2

Workflow -> Sandbox container -> base64 assets -> hf-render
                              -> base64 MP4 -> R2

The system works, but every boundary introduces another convention or conversion.

Durable files need custom wrappers

Each ProjectAgent Durable Object owns an @cloudflare/shell Workspace backed by its SQLite storage. On top of it, I built:

readAllProjectFiles() to turn the workspace into a Record<string, string>.
archiveGeneration() and getGenerationFiles() to maintain historical snapshots.
list_files, read_file, and write_file tools with path guards and extension allowlists.

The filesystem is durable. The application code around it is specific to PromptMotion.

Rendering duplicates the filesystem

The render workflow starts a Cloudflare Container through @cloudflare/sandbox, recreates the project directory, and writes every source file into it. It also reads assets from R2 and writes them into the container.

The RPC boundary does not currently give this path a shared filesystem, so binary files travel as base64 strings. The rendered MP4 makes the same trip in reverse before the workflow uploads it to R2.

Workspace files -> flatten paths -> container files
R2 assets       -> base64        -> container files
rendered MP4    -> base64        -> Worker memory -> R2

The workflow also owns the Sandbox ID, sleep timer, and cleanup. A missed destroy() can leave a container running longer than intended.

Previewing is a third file path

The live preview cannot use the render workflow. It needs to respond to browser requests for HTML, JavaScript, and assets.

My main Worker's fetch handler calls the ProjectAgent over RPC, loads an archived generation, injects the HyperFrames runtime fixes, and serves the result. Asset requests use another route that reads from R2.

The agent, renderer, and preview server all consume the same project, but each reaches it differently.

The Abstraction Cloudflare Computer Adds

@cloudflare/computer is a preview package that puts a SQLite-backed virtual filesystem inside a Durable Object. A Workspace has two important surfaces:

workspace.fs provides a node:fs/promises-shaped API for durable files.
workspace.runtime.exec() runs commands or JavaScript through a configured backend against those files.

Three execution backends currently ship:

A container backend with a real Linux userland and a FUSE-mounted workspace.
A Worker shell backend powered by just-bash.
A Worker JavaScript backend that evaluates an ECMAScript module in a fresh Dynamic Worker.

The important part for PromptMotion is not the number of backends. It is that the host application and each backend operate on one durable file model.

                         +-> built-in agent tools
                         |
Agent -> Computer -------+-> Workspace.fs -> preview handler
Workspace                |
                         +-> computerd container -> hf-render
                                                   |
                                                   +-> MP4 stream -> R2

The preview handler remains, but the agent, preview path, and renderer no longer need separate ways to reconstruct the project.

How Computer Maps to My Problems

One durable filesystem instead of file-copying helpers

Computer's filesystem accepts strings, Uint8Array, and ReadableStream values. Text reads can return UTF-8 strings, while binary reads return streams by default.

await ws.fs.writeFile("/workspace/src/composition.html", content);

const composition = await ws.fs.readFile(
  "/workspace/src/composition.html",
  "utf8",
);

const projectEntries = await ws.fs.find("/workspace/src");

That replaces the custom Workspace wrapper and gives the preview and render paths the same file API.

Computer also has an opt-in git client backed by isomorphic-git. I could initialize a repository per project and commit each accepted generation instead of copying every file into a snapshot directory.

await ws.git.add({ dir: "/workspace", paths: ["src/"] });
await ws.git.commit({
  dir: "/workspace",
  message: `generation ${generationId}`,
});

Git is not enabled automatically. The Workspace must be configured with createGitClient(), initialized once, and given an identity before this code works.

Built-in tools replace generic agent glue

@cloudflare/computer/tools provides AI SDK tools named read, write, edit, and ls. An exec tool is available when shell backends are configured.

import { createAITools } from "@cloudflare/computer/tools";

const tools = createAITools({
  workspace: ws,
  read: { maxBytes: 32 * 1024, maxLines: 800 },
});

I would still keep load_skill, list_assets, and start_preview because they describe PromptMotion behavior. I would also preserve my file-extension policy with a thin wrapper because the built-in write tool supports a byte limit, not an extension allowlist.

This is the boundary I want: Computer owns generic file operations, while PromptMotion owns product policy.

The render container sees the same workspace

The CloudflareContainerBackend runs computerd inside a Cloudflare Container. Before a command runs, it synchronizes the Durable Object state into the container and exposes it at /workspace through FUSE. Changes synchronize back after execution.

The render step could operate on the project without recreating it file by file:

using run = await ws.runtime.exec(
  "hf-render . --output out/video.mp4 --quiet",
  {
    cwd: "/workspace/src",
    backend: "render",
    encoding: "utf8",
  },
);

const { exitCode, stderr } = await run.result();
if (exitCode !== 0) throw new Error(`Render failed: ${stderr}`);

This removes the restore-code-to-container step and the manual Sandbox ID. The backend handles container startup, reconnects, workspace synchronization, and command execution.

It does not remove the container image. I still need Chromium, FFmpeg, hyperframes, chrome-headless-shell, and the hf-render wrapper. The image must also run the computerd daemon. The official container example shows the required Worker, Durable Object, WorkspaceProxy, and container wiring.

Streams can replace base64 transfers

Once the command finishes and its changes synchronize back, the workflow can read the MP4 as a stream and pass it to R2:

const video = await ws.fs.readFile("/workspace/src/out/video.mp4");

await env.VIDEOS_BUCKET.put(
  `videos/${userId}/${generationId}.mp4`,
  video,
  { httpMetadata: { contentType: "video/mp4" } },
);

This removes the current readFile(..., { encoding: "base64" }), atob, and Uint8Array conversion loop.

There is a trade-off. The Workspace shares the Durable Object's roughly 10 GB storage limit, and the container-side filesystem is held in memory. Published benchmarks also show that large sequential reads through the FUSE mount are much slower than native disk. A direct container-to-R2 upload may still be the better design for large rendered videos.

Computer gives me a stream instead of a base64 blob. I still need to measure whether synchronizing the MP4 through the Workspace is the right path.

R2 mounts unify file access, not HTTP serving

Computer can mount an R2 bucket as a read-only subtree:

mounts: {
  "/workspace/assets": R2Bucket(env.ASSETS_BUCKET),
}

This lets workspace.fs read assets through the same interface as project files. Before a container command reads a lazily mounted object, the Durable Object must hydrate it or prefetch the mount so bytes are available to synchronize.

An R2 mount does not create a public /assets/... URL. The preview server still needs an HTTP route that reads the mounted file and returns a response. Computer can replace the direct R2 call inside that route, but not the route itself.

What Computer Does Not Solve

The shared Workspace removes infrastructure glue, not PromptMotion logic.

HyperFrames runtime patches stay. The normalizer and runtime injection fix behavior in the HyperFrames player. Changing the filesystem does not change that. Moreover, I am not using the latest version of HyperFrames, maybe the updates already resolve this?
The render image stays. hf-render still needs Chromium, FFmpeg, and PRODUCER_HEADLESS_SHELL_PATH.
The preview server stays. The Worker JavaScript backend evaluates modules and returns output. It does not expose a module as an HTTP request handler.
Generation metadata stays. D1 still tracks status, ownership, billing, and the final R2 key.
R2 stays. Large uploads and final videos still need object storage.
The workflow decision stays. Computer can execute the render command, but I still need to decide where retries, status transitions, and failure recovery live.

This distinction is important. Computer could make the product easier to maintain without pretending that every part of the product becomes a filesystem call.

The Migration I Would Try

I would validate the abstraction in three stages rather than replacing every layer at once.

1. Move source files first

The first step is replacing @cloudflare/shell with a Computer Workspace while keeping the existing preview and render paths.

I would test:

Existing project import into /workspace/src.
Read, write, find, and archive behavior across Durable Object restarts.
The built-in AI tools with my path and extension policies.
Git snapshots against real generation histories.

This isolates the storage migration from container and preview changes.

2. Run one render through computerd

Next, I would configure the container backend using the official example as the starting point. The computerd image tag should match the installed @cloudflare/computer version.

The useful measurements are concrete:

Time to synchronize a typical project and its assets.
Container startup time for the first render and later renders.
Time and memory used to synchronize the final MP4 back.
Behavior when rendering succeeds but post-command synchronization fails.

If MP4 synchronization is too expensive, the container can upload the output directly to R2 while Computer still handles source files and command execution.

3. Point the preview server at the Workspace

Finally, I would keep the current browser-facing routes but replace the custom archive RPC and direct R2 reads with workspace.fs calls.

using ws = await getWorkspace(projectAgent);

const composition = await ws.fs.readFile(
  `/workspace/generations/${generationId}/src/composition.html`,
  "utf8",
);

The HyperFrames injection remains in the handler. Only the file access path changes.

What About Live Render Progress?

An exec handle is also a ReadableStream of events. If a request owns the execution, it can transform those events into Server-Sent Events and stream command output to the browser.

My current render runs inside an AgentWorkflow, so this is not automatic. A workflow step cannot directly pipe its exec stream into a separate active HTTP response. I would need either:

A request or agent session that owns the render execution.
An event relay that persists workflow output and forwards it to connected clients.

Computer provides the stream, but PromptMotion still needs the delivery path.

Where I Am Cautious

@cloudflare/computer is explicitly marked preview-only:

APIs are unstable and the design is subject to change. Suitable for experiments, exploration and prototypes. It is NOT suitable for production use at this time.

That leaves four risks to validate:

API churn. I would pin the package and matching computerd image versions.
Migration and rollback. Computer is not API-compatible with @cloudflare/shell; both directions need an explicit data conversion.
Large-file behavior. Source files match the intended agent-scale workload. Video assets and MP4 output may not.
Operational ownership. SyncRetryScheduler can persist failed sync work, but the application still owns its Durable Object alarm and retry policy.

The preview status is why I would start with a branch and one real project rather than migrate production data immediately.

The Outcome I Want

PromptMotion currently has three ways to reach the same project files: the agent Workspace, the render workflow, and the preview server. Cloudflare Computer could reduce those paths to one durable Workspace shared by the application and its execution backends.

The potential wins are specific:

Generic file tools and version history move into the Workspace layer.
The render container operates on the same project instead of receiving a reconstructed copy.
Binary data can move as streams instead of base64 strings.

The preview server, HyperFrames patches, render image, workflow policy, and R2 storage remain. That is a feature of the design, not a failure. Those pieces contain PromptMotion's product decisions. Computer could remove the infrastructure code around them.

That is the migration I want to test. I will write a follow-up after running a real PromptMotion render through computerd, with timings and the parts that did not work as expected.

If you are testing Cloudflare Computer for a similar agent workload, feel free to hit me up on Twitter. I would love to compare notes.

Further Reading:

How I Run the Pi Coding Agent on Cloudflare

Harshil Agrawal — Mon, 03 Aug 2026 14:40:10 +0000

I recently came across a tweet about Pi's programmatic APIs. I knew Pi as a coding agent, but its portable internals caught my attention. The agent loop, model providers, and session storage are available through lower-level packages rather than being tied to its terminal interface. This project uses @earendil-works/pi-agent-core and @earendil-works/pi-ai directly instead of embedding the full @earendil-works/pi-coding-agent SDK.

That made me think: can I run Pi entirely on Cloudflare's Developer Platform?

Most coding agents assume they are running on a developer's machine. They expect a persistent local filesystem, a shell, long-lived processes, and somewhere to store conversation history. Cloudflare Workers provides a very different runtime. There is no machine waiting for the agent. Workers has a request-scoped virtual filesystem, but it does not persist files across requests or provide the host filesystem a local coding agent expects.

This sounded like a fun challenge. Instead of making Workers behave like a laptop, I wanted to find the Cloudflare primitive for each capability Pi needed.

Pi on Cloudflare is what came out of that experiment. It is a browser-based coding agent where each session has durable conversation history, an isolated filesystem, streaming model output, searchable prior sessions, generated application previews, and one-click deployment to Cloudflare Workers.

It is still a single-user prototype, not a production multi-tenant service. However, building it taught me a lot about what a coding agent needs from its runtime. Let me walk you through the design decisions, the Cloudflare primitives I used, and the limitations I accepted.

What I Wanted to Preserve from Pi

Pi is more than a chat interface around an LLM. Its core packages provide the parts required to run a coding agent:

An agent harness that coordinates model calls and tool execution
A provider abstraction for connecting models
Streaming events for text, reasoning, and tools, plus lifecycle events such as save points
An append-only session tree rather than a flat message list
Branch navigation, labels, forks, clones, and compaction
A storage interface that applications can implement for different runtimes
Steering, follow-up, and abort operations

The storage interface in pi-agent-core was the part that made this experiment possible. It doesn't require the transcript to live in a local JSON file. I could provide my own implementation while retaining Pi's native entry types and tree structure.

I didn't want to flatten Pi into another chat application with a list of messages. I wanted to keep its branches, compaction, tool loop, and model abstraction, then replace only the things that normally come from a local machine.

The Cloudflare version currently supports:

Creating, naming, cloning, forking, searching, and deleting sessions
Streaming assistant text, reasoning, and tool activity
Navigating branches without deleting later history
Automatic and manual context compaction
Durable workspace file operations
Cross-session search and learned memory
Building, previewing, and deploying generated React applications

Pi on Cloudflare isn't a browser port of Pi's terminal interface. It is a new host for Pi's portable core.

The Architecture

I started by listing the capabilities that a local runtime normally gives Pi: identity for each session, durable state, files, model access, real-time communication, a way to execute generated code, and a place to keep deployed source.

Once I mapped those capabilities to Cloudflare products, the architecture looked like this:

There are 2 Durable Object classes:

PiSession owns one Pi conversation and its workspace
PiRegistry owns the session catalog, transcript search index, lineage, and global memory

The application itself is a TanStack Start application deployed on Cloudflare Worker. The browser connects to the Durable Objects through the Cloudflare Agents SDK. Model requests go through AI Gateway. Generated applications run in Dynamic Workers during preview and become independent Workers when deployed.

One Durable Object per Pi Session

The first question I had to answer was: what owns a Pi session when there is no long-lived local process?

This is where Durable Objects clicked for me. I assigned one PiSession Durable Object to each conversation.

A coding-agent session is a natural coordination boundary. It has one active transcript, one selected branch, one workspace, and at most one model turn changing those resources at a time.

Each PiSession owns:

The low-level Session and AgentHarness from pi-agent-core
The append-only transcript tree
The active leaf in that tree
Compaction settings
An isolated filesystem
Indexing and memory-extraction cursors
Generated application metadata
An in-memory build cache

The code for this mapping is surprisingly small:

export class PiSession extends Agent<Env> {
  private active = false
  private harness?: PiHarness

  private readonly sessionStorage =
    new PiSessionStorage(this.ctx.storage)

  private readonly session =
    new Session(this.sessionStorage)

  private readonly workspace = new Workspace({
    sql: this.ctx.storage.sql,
    name: () => this.ctx.id.toString(),
  })
}

The Agents SDK Agent class extends Durable Objects with WebSocket connections, RPC, and browser clients. Durable Objects provide the identity, coordination, and SQLite storage underneath.

This gives each session an independent address and storage boundary. A busy session doesn't need to coordinate transcript writes with every other session.

It also gives me a straightforward exclusivity rule. Before Pi starts a prompt, the session marks itself active. Concurrent operations that could change the same transcript or workspace are rejected until the turn finishes.

Durable Objects solved the ownership and coordination problem, but I still needed to fit Pi's storage model into the Durable Object. That led to the next decision.

Durable Objects are single-threaded, but requests can interleave while awaiting non-storage I/O such as model calls. The active flag provides application-level exclusivity across the complete agent turn, not only an individual storage statement.

Preserving Pi's Session Tree in SQLite

A conventional chat application often stores messages in a table and updates or deletes rows when users retry a prompt. Pi doesn't work that way.

Each session entry has an ID, a parent ID, a type, and a timestamp. Together, those entries form a tree. Changing the active branch doesn't delete another branch. In the low-level pi-agent-core session model used here, Pi appends a leaf-selection entry that points to the newly selected part of the tree.

I preserve that representation directly:

CREATE TABLE IF NOT EXISTS pi_session_entries (
  seq INTEGER PRIMARY KEY AUTOINCREMENT,
  id TEXT NOT NULL UNIQUE,
  type TEXT NOT NULL,
  entry TEXT NOT NULL
);

The serialized entry can be a message whose role is user, assistant, or tool result. Other entry types represent model, thinking-level, or active-tool changes, compaction, branch summaries, custom data, labels, session information, or leaf selection.

Flattening everything into chat messages would discard the exact semantics I wanted to preserve. Pi's branch navigation and compaction logic expect the original entry relationships.

Appending non-empty user or assistant text also creates an indexing event within the same synchronous SQLite transaction. Every entry creates a separate event that updates the registry's session metadata. In simplified form:

this.storage.transactionSync(() => {
  this.storage.sql.exec(
    'INSERT INTO pi_session_entries(id, type, entry) VALUES (?, ?, ?)',
    entry.id,
    entry.type,
    JSON.stringify(entry),
  )

  if (
    entry.type === 'message' &&
    (entry.message.role === 'user' || entry.message.role === 'assistant')
  ) {
    const text = messageText(entry.message)
    if (text) this.enqueue(createMessageIndexEvent(entry, text))
  }

  this.enqueue(createSessionTouchEvent(entry))
})

There is a small but important failure case here. If I stored the transcript first and indexing failed afterwards, search could silently miss a completed message. If I indexed first, search could return a message that had never been committed to the session.

To avoid both cases, a background operation delivers the events to PiRegistry, but writing indexable transcript text and its outbox event happens atomically. Delivery can be asynchronous and idempotent because non-empty user or assistant text cannot be stored without also becoming eligible for indexing.

This is the transactional outbox pattern applied inside a Durable Object.

Giving Pi a Durable Filesystem

At this point, I had durable conversations, but that alone doesn't make a coding agent. Pi also needed files.

A Worker doesn't expose the host machine's persistent POSIX filesystem. This is where the experimental @cloudflare/shell package came in. It gave me a virtual filesystem backed by the session's Durable Object SQLite database.

Every Pi session therefore gets its own isolated workspace. Files survive Durable Object eviction because they live in durable storage rather than in the object's memory.

I expose 6 core filesystem tools to the model:

read
write
edit
list
find
grep

Each tool operates against the virtual workspace:

const writeTool = {
  name: 'write',
  description: 'Write a complete UTF-8 file to the durable workspace.',
  executionMode: 'sequential',

  async execute(_id, { path, content }, signal) {
    signal?.throwIfAborted()
    await workspace.writeFile(path, content)
    signal?.throwIfAborted()

    return text(`Wrote ${path}`)
  },
}

Write and edit tools run sequentially to prevent concurrent changes from racing against each other.

I also expose the workspace in the browser so I can inspect, refresh, and download files. I didn't want the filesystem to be an invisible implementation detail hidden behind the model.

But What About a Shell?

The obvious next question is why I didn't give Pi a process sandbox. This version doesn't provide:

A POSIX shell
Native processes
npm install
Arbitrary package scripts
A development server
A general network-fetch tool
Native test or compiler commands

This is deliberate, and it is probably the biggest difference from running Pi locally.

The first version needed persistent source files and a way to run Workers applications. It didn't need a general-purpose Linux environment. Durable Object SQLite and Dynamic Workers cover that narrower requirement with fewer moving parts.

The system prompt makes that limitation explicit:

const BASE_SYSTEM_PROMPT = [
  'You are Pi running natively on Cloudflare Workers.',
  'Use the durable workspace tools to inspect and modify files.',
  'There is no POSIX filesystem or native process runtime.',
  'Do not claim to run shell commands.',
].join('\n')

Here, "no POSIX filesystem" means the agent is not given a persistent POSIX workspace or a process environment. I don't expose Workers' request-scoped node:fs filesystem as an agent tool.

If I wanted the agent to compile arbitrary native projects or run existing CLI tools, I would use Cloudflare Containers or the process-oriented Cloudflare Sandbox SDK. For React and Workers applications built from a controlled template, the Worker-native path is enough.

Running Pi's Model Loop Through AI Gateway

With sessions and files in place, the next piece was model inference. Pi already separates the agent loop from its model provider, so I registered a custom provider backed by AI Gateway's OpenAI-compatible API.

const model = {
  id: modelId,
  name: modelId,
  api: 'openai-completions',
  provider: 'cloudflare-ai-gateway',
  baseUrl:
    `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1`,
  reasoning: true,
  input: ['text'],
  contextWindow: 200_000,
  maxTokens: 16_384,
}

The contextWindow and maxTokens values above are conservative budgets configured in this adapter, not advertised model limits. The currently selected GLM-5.2 model has a documented 262,144-token context window on Workers AI.

The committed configuration currently selects a Workers AI model:

{
  "vars": {
    "AI_GATEWAY_ID": "default",
    "AI_MODEL": "@cf/zai-org/glm-5.2",
    "AI_MEMORY_MODEL": "@cf/zai-org/glm-5.2"
  }
}

I liked this approach because AI Gateway gives the agent one model endpoint while the model remains a configuration choice. It also gives me a natural place to attach request metadata:

streamOptions: {
  headers: {
    'cf-aig-gateway-id': gatewayId,
    'cf-aig-metadata': JSON.stringify({ sessionId }),
  },
}

The session ID makes model traffic attributable to the Pi session that produced it. Memory extraction requests include an additional purpose field.

The UI doesn't currently expose model or reasoning-level selection. The agent uses a fixed medium thinking level and server-side model configuration.

Getting the Stream Back to the Browser

The agent loop was now running inside a Durable Object, but a coding agent doesn't feel useful if the browser waits for the entire turn to finish. I wanted to show text, reasoning, and tool activity as Pi produced them.

The application routes /api/agents/* through the Agents SDK before passing other requests to TanStack Start:

export default createServerEntry({
  async fetch(request) {
    const agentResponse = await routeAgentRequest(request, env, {
      prefix: 'api/agents',
    })

    return agentResponse ?? handler.fetch(request)
  },
})

Ordinary session operations use callable RPC methods. Prompts use a streaming callable method:

@callable({ streaming: true })
async prompt(
  stream: StreamingResponse,
  prompt: string,
): Promise<void> {
  // Run Pi and forward its events to the browser.
}

A prompt moves through the system as follows:

The browser appends the user message optimistically.
The Agents SDK sends the prompt to the session's Durable Object.
PiSession validates configuration and prevents a second active prompt.
The session creates or reuses its in-memory AgentHarness.
Pi compacts the active branch if it is approaching the context budget.
The model produces text, reasoning, and tool calls through AI Gateway.
Pi events are translated into browser-safe stream events.
Completed messages become part of the durable session tree during the turn.
After a turn, a save point schedules asynchronous registry outbox delivery.
The browser reloads the authoritative branch and workspace.

The client batches incoming deltas once per animation frame. Model streams can produce updates faster than React should render them, so batching reduces unnecessary UI work without changing what the user sees.

There is a catch. Only completed Pi entries are durable. Partial token deltas and the browser's position within an active stream are not. If the Durable Object restarts during a turn, the client can reload completed durable entries but cannot reattach to the interrupted stream. Resumable active turns are something I still want to explore.

Searching Across Sessions

One Durable Object per session worked well until I needed to answer questions across them. How do I list every session, search old conversations, or carry a useful preference from one session into another?

This is why I added a singleton PiRegistry Durable Object.

The registry handles:

Session discovery and metadata
Names and timestamps
Parent and source lineage
Full-text transcript search
Regular-expression search
Idempotent index-event processing
Deletion tombstones
Learned memory shared across sessions

The registry indexes non-empty user and assistant text with SQLite FTS5. It intentionally excludes reasoning, tool output, compaction summaries, and workspace files.

I deliberately kept the search lexical rather than adding embeddings and a vector database. SQLite FTS5 has lower operational complexity and produces predictable results for session names, phrases, and code fragments. The agent can call a session_search tool to retrieve relevant text from earlier sessions.

Deletion tombstones handle an important race. Index events travel asynchronously from a session to the registry. Without a tombstone, a delayed event could recreate metadata for a deleted session. The registry records the deletion and rejects later events for that session.

Learned Memory

The registry also stores global memories classified as:

Preferences
Facts
Instructions
Decisions

Memory can change through an explicit model tool or through background extraction after completed turns. The extraction prompt treats transcript contents as untrusted data and requires every change to cite a user-authored source entry.

Later sessions receive those memories in their system prompt.

Memory can become dangerous quickly if an agent stores everything it sees. I therefore kept this feature conservative. It limits the number and total size of memories, uses optimistic version checks for background extraction updates and deletions, and rejects selected secret patterns. Explicit updates through the memory tool do not currently use the same version check. Those checks are guardrails, not a complete data-loss-prevention system.

Memory is currently global to the deployment. It isn't separated by user because the application doesn't yet have a user identity model.

Building an App Without a Build Process

This was the part I was most curious about. Writing source files in SQLite is useful, but I wanted Pi to build something I could actually open and deploy. How do you build a React application when you cannot spawn Vite as a process?

When the user asks Pi to build an application, the model calls initialize_app. That tool copies a React template pinned to a full Git commit into the durable workspace.

Pinning the commit gives the agent a known project shape:

React code lives under /src
Worker API code lives at /worker/index.ts
The host controls the build inputs and compatibility settings
The model cannot introduce arbitrary installation scripts into the build

When the user requests a preview or deployment, the application creates a deterministic source snapshot. It excludes directories such as .git, node_modules, dist, and .wrangler, then enforces explicit limits:

1,000 source files
5 MiB per file
25 MiB total source size

The snapshot is sorted and hashed. The source hash lets the UI detect changes and lets the session reuse a matching in-memory build.

Instead of starting a process, I call the experimental, Workers-runtime-only @cloudflare/worker-bundler package directly inside the Worker:

const result = await createApp({
  files,
  server: 'worker/index.ts',
  client: 'src/main.tsx',
  assets,
  assetConfig: {
    not_found_handling: 'single-page-application',
  },
  jsx: 'automatic',
  jsxImportSource: 'react',
  minify: true,
})

The catch is that this is not equivalent to spawning vite build. The hosted builder uses a controlled entrypoint, fixed compatibility settings, and an in-memory source map. It doesn't execute arbitrary package scripts or custom Vite plugins.

That constraint makes builds repeatable and keeps generated code inside the runtime model I designed for.

Previewing Generated Code with Dynamic Workers

A successful build left me with another interesting problem: the generated code didn't exist when I deployed the host Worker, but I still needed to execute it for a preview. Dynamic Workers is currently in open beta.

The Worker Loader binding lets the application create a Dynamic Worker from the generated modules. I use the bundle hash as its ID:

export async function previewApp(
  request: Request,
  builtApp: BuiltApp,
  loader: WorkerLoader,
): Promise<Response> {
  const worker = loader.get(
    builtApp.bundleHash,
    () => previewCode(builtApp),
  )

  return worker.getEntrypoint().fetch(request)
}

Using get() instead of loading a new Worker for every request lets the runtime reuse a warm isolate when available. Reuse is not guaranteed, and the callback may run again if the runtime needs a new isolate.

The preview Worker receives these application-configured limits and bindings:

The generated Worker modules
Bundled static assets
No environment bindings
A 50ms CPU limit
A 20-subrequest limit
Outbound network access inherited from the parent Worker

The wrapper serves static files first, delegates API requests to the generated Worker, and falls back to index.html for client-side routes.

This is isolated Worker execution, not a Linux process sandbox. Generated code can handle requests using Workers APIs, but it can't spawn a process or access the Pi session's Durable Object unless I explicitly provide a binding. Because the current loader configuration does not set globalOutbound: null, generated code can still make outbound requests with fetch() or connect().

For this project, the binding isolation is useful: the generated app receives no session storage or secrets. Outbound access remains a capability I would need to restrict before treating previews as untrusted code.

Versioning and Deploying Generated Applications

Once preview worked, I wanted a path from "the agent built this" to "this is a real deployed application." A preview is temporary. A deployed application needs durable source history and an independent Worker.

The deployment pipeline has 2 destinations:

Source goes to Cloudflare Artifacts, which is currently in beta and requires enrollment.
The built application goes to the Workers API.

Artifacts provides Git-compatible, versioned storage. I create one repository per Pi session and publish the exact source snapshot used for the deployment.

The application uses a short-lived repository token and a JavaScript Git client over the virtual workspace. This gives each deployment a source commit without requiring a native git process.

After publishing the source, the deployment client:

Uploads the generated static assets.
Creates a Worker version.
Creates a deployment that sends 100% of traffic to that version.
Returns the resulting workers.dev URL.
Stores the source hash, bundle hash, commit SHA, version ID, and deployment ID in the session.

Each generated application becomes its own Worker. It doesn't keep running inside the original Pi session after deployment.

Deleting a session also deletes its generated Worker and Artifacts repository when deployment metadata exists.

Why Each Cloudflare Primitive Is Here

By this point, every primitive had a specific job. I didn't want to add a product because it might be useful later. I added it only when the implementation had a concrete requirement.

Primitive	Responsibility	Why It Fits
Cloudflare Workers	Hosts the UI and request router	One deployment serves the application, agent routes, and preview gateway
Durable Objects	Owns sessions and the registry	A session is a stateful coordination boundary with durable storage
Durable Object SQLite	Stores transcripts, settings, indexes, memory, and files	Transactions preserve Pi entries and indexing events atomically
Agents SDK	Browser connections, RPC, and streaming	It connects React clients directly to Durable Object-backed agents
AI Gateway	Routes model requests	Pi can use an OpenAI-compatible provider while requests retain gateway metadata
`@cloudflare/shell`	Provides the virtual filesystem	The agent gets durable file operations without assuming a host filesystem
Worker Bundler	Builds generated applications	Source can be compiled in memory without spawning a build process
Dynamic Workers	Runs application previews	Generated Worker code executes in an isolated runtime with controlled bindings
Artifacts	Versions generated source	Each deployment has a Git-compatible source history
Workers API	Deploys generated applications	Every generated app becomes an independently versioned Worker
Workers Static Assets	Serves generated frontend files	React assets and Worker API code deploy as one application

I didn't add KV, R2, D1, Queues, Workflows, Containers, or Vectorize. None of them solved a requirement that the existing primitives couldn't already cover.

Current Trade-offs

I am happy with how much of Pi works on Cloudflare, but I don't want to present this as a production-ready replacement for a local coding agent. The architecture works because it chooses a narrower definition of a coding environment.

The main limitations, in order of importance, are:

The application has no user or tenant isolation
Tool writes do not require user approval
Global memory has no management interface and is shared across sessions
There is no native shell or arbitrary process execution
Only the controlled React template can use the hosted build path
Active streams cannot resume after a Durable Object restart
Forks copy the current workspace, not the filesystem as it existed at the selected transcript entry
Search is lexical rather than semantic
Generated previews have no bindings or secrets, but retain outbound network access
Model and reasoning-level selection are server-controlled
The singleton registry could become a coordination bottleneck at larger scale

The first point is the most important.

This repository is a single-user prototype. Session UUIDs create storage boundaries, but they are not authorization controls. Anyone who can reach the deployment can potentially inspect sessions, modify files, call the model, influence global memory, or deploy applications using server-side credentials.

Important: Protect the entire Worker with Cloudflare Access or another authentication layer before exposing it to the Internet. When using Access, follow Cloudflare's guidance to validate the Access JWT in the Worker as well.

Run Pi on Cloudflare

If you want to try the same setup, here is the shortest path. Remember that the project has no application-level authentication, so protect a deployed instance before giving it privileged credentials.

The committed GLM-5.2 configuration requires the Workers Paid plan. Generated app deployment also requires enrollment in the Artifacts beta and an Artifacts namespace named pi-apps, which you can create in the Cloudflare dashboard.

Clone the repository and install its dependencies:

git clone https://github.com/harshil1712/pi-on-cf.git
cd pi-on-cf
npm ci

Because the project uses a remote Artifacts binding during local development, authenticate Wrangler first:

npx wrangler login

Create a local environment file, then add your Cloudflare account ID and an API token with AI Gateway - Read, AI Gateway - Edit, and Workers AI - Read permissions:

cp .env.example .env

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token

Start the local Worker runtime:

npm run dev

For a production deployment, including generated app deployment, configure these Worker secrets. Use the AI Gateway token described above for CLOUDFLARE_API_TOKEN. WORKERS_DEPLOY_API_TOKEN needs account-scoped Workers Scripts Read and Workers Scripts Edit permissions so the application can create and delete Workers, upload assets, create versions and deployments, and read the account's workers.dev subdomain.

npx wrangler secret put CLOUDFLARE_ACCOUNT_ID
npx wrangler secret put CLOUDFLARE_API_TOKEN
npx wrangler secret put WORKERS_DEPLOY_API_TOKEN

Deploy the host application with:

npm run deploy

The repository includes UI tests running in jsdom and a separate test suite running inside the Workers runtime:

npm run lint
npm run typecheck
npm test
npm run build

What I Learned

I started with a simple question after seeing a tweet: can Pi run on Cloudflare?

What I learned is that Pi's lower-level agent, provider, and session abstractions didn't need its normal terminal host. They needed a set of capabilities around them: durable identity, coordinated state, files, model access, streaming, and a constrained way to execute generated code. Pi's portability let me keep the difficult parts of the agent, including its tool loop, session tree, model abstraction, streaming events, and compaction behaviour.

Cloudflare supplied the runtime around it:

Durable Objects turned each Pi session into an isolated, stateful service.
SQLite and @cloudflare/shell replaced local transcript and filesystem storage.
Dynamic Workers, Worker Bundler, and Artifacts created a Worker-native path from generated source to preview and deployment.

The project doesn't imitate a local machine. It treats Workers as the target environment from the beginning. That forced me to be explicit about what the agent can do, and equally explicit about what it cannot do.

I also have a new appreciation for Pi's design. Making the agent loop and session storage portable is what made this entire experiment possible.

The project is open source. If you are experimenting with coding agents on Cloudflare, take a look and let me know what you build. I am especially interested in how you would approach resumable turns, historical workspace snapshots, or multi-user isolation.

I also recommend looking at Project Think. It is an opinionated harness from Cloudflare whose design is inspired by Pi. It packages Cloudflare-native capabilities including workspace tools, persistence, stream resumption, durable recovery, extensions, and sub-agent support, so less custom infrastructure is required. I personally am building agents using Think.

If you have questions or feedback, feel free to reach out on LinkedIn or X.

References

Making My Astro Site Agent-Ready: An Honest Audit of isitagentready.com

Harshil Agrawal — Sun, 07 Jun 2026 21:37:37 +0000

I have built a few SaaS apps and I spend a lot of time thinking about how people find and use them. I track analytics, optimize for search engines, and write descriptive meta tags. But recently I realized a lot of these apps are getting referred by ChatGPT and other AI chat apps. I didn't optimize the sites for this entirely new category of visitor: AI agents.

Agents are increasingly browsing the web on our behalf — reading documentation, comparing products, summarizing content. But most websites, mine included, are built for human eyes. There's no standard way for a site to tell an agent what it can do, what content it offers, or how to access it in a machine-friendly format.

Cloudflare launched isitagentready.com, a scanner that evaluates how "AI-agent-friendly" your website is. I tried it on my personal site built with Astro and deployed on Cloudflare Workers. I didn't expect a perfect score, but I was curious.

I pasted in https://harshil.dev, hit scan, and waited.

Eight issues. All red.

My first reaction was mild panic. My second reaction was more useful: skepticism. Most of these recommendations assume I'm running a SaaS platform with public APIs, authentication flows, and agent-facing tools. I'm not. I'm a developer with a blog and a couple of gated APIs.

This post is what I actually implemented, what I deliberately skipped, and the small decision framework I used to tell the difference between a meaningful improvement and cargo-cult engineering.

The Audit Results

Here's what the scanner found:

#	Check	Result	Assumes you're a...
1	Link response headers (RFC 8288)	🔴 Fail	Any site
2	Markdown content negotiation	🔴 Fail	Any site
3	Content Signals in robots.txt	🔴 Fail	Any site
4	API catalog (RFC 9727)	🔴 403	SaaS with APIs
5	OAuth/OIDC discovery metadata	🔴 Missing	SaaS with auth
6	OAuth Protected Resource Metadata	🔴 Missing	SaaS with auth
7	MCP Server Card	🔴 403	SaaS with tools
8	Agent Skills discovery index	🔴 403	Agent platform
9	WebMCP support	🔴 Missing	SaaS with actions

The first three apply to any website. The last six assume infrastructure I simply don't have. But the scanner doesn't know that; it just checks for files and headers. You can select which ones to scan for — I let it scan for all just out of curiosity.

The Decision Framework

Instead of blindly chasing every red flag, I asked three questions for each recommendation:

Do I actually have this capability? If the scanner wants an MCP Server Card, do I have an MCP server? (No.)
Is it meaningful for a personal blog? Would an agent benefit from discovering a gated API catalog? (Not really.)
Is it a quick metadata win? Can I add meaningful information with a few lines of code or config? (Yes, for the first three.)

This is the framework I'd recommend to anyone running a similar audit. The goal isn't to turn every light green; it's to provide honest, useful signals to agents that visit your site. Publishing empty discovery documents is worse than not publishing them at all. You're wasting an agent's time and giving it false expectations.

Once you answer the above questions, you can copy the prompt provided by the site, update it based on your answers, and let your coding agent handle the improvements.

What my agent implemented

1. Link Headers on the Homepage (RFC 8288)

The scanner found zero Link headers on my homepage. RFC 8288 defines a standard way to advertise related resources via HTTP headers, so agents don't need to parse HTML to find sitemaps, feeds, or author pages.

This was a genuine gap. My site has a sitemap, a writings feed, and an about page — things an agent might want to find. But none of them were advertised in the HTTP response.

The fix was surprisingly simple. Astro's server-side rendering lets you set response headers directly in a page's frontmatter:

---
import Layout from "../layouts/Default.astro";

const title = "Harshil Agrawal";
const description = "...";

// RFC 8288 Link headers for agent discovery
Astro.response.headers.set(
  "Link",
  [
    '</sitemap-index.xml>; rel="describedby"',
    '</writings>; rel="related"',
    '</about>; rel="author"',
  ].join(", ")
);
---

I chose three IANA-registered relation types:

describedby for the sitemap — the best machine-readable overview of the site
related for the writings feed — the primary content stream
author for the about page — semantically correct for a personal site

You could also use service-doc or api-catalog if you have those. I don't, so I didn't add them.

2. Content Signals in robots.txt

The scanner was looking for Content Signals — a proposed IETF standard that lets sites declare AI usage preferences via robots.txt directives. The idea is straightforward: tell agents whether they can use your content for training, search, and input context.

My robots.txt was minimal:

User-agent: *
Allow: /

Sitemap: https://harshil.dev/sitemap-index.xml

I added one line:

User-agent: *
Allow: /
Content-Signal: ai-train=yes, search=yes, ai-input=yes

Sitemap: https://harshil.dev/sitemap-index.xml

I chose ai-train=yes because this is a public blog — the entire point is to share knowledge as widely as possible. search=yes is obvious, and ai-input=yes means agents can use the content as context when generating responses. If you run a private or paywalled site, you might choose differently.

This is a metadata-only change. It's a single line in a text file, but it gives agents a clear signal about your intent. That's the whole point.

Validation:

I deployed the site with these changes, and ran it through the scanner again. The scanner went from red to green on this check immediately.

3. Markdown Content Negotiation

This was the most interesting check, and the one that took the most actual work.

The scanner sends requests with Accept: text/markdown and checks whether your site returns markdown instead of HTML. This matters because markdown is far more token-efficient for LLMs than HTML. A typical HTML page might be 50KB; the same content in markdown might be 8KB. For agents with context window limits, that's a meaningful difference.

The native solution: Cloudflare offers a feature called Markdown for Agents that does this automatically at the edge. When enabled, Cloudflare intercepts requests with Accept: text/markdown, fetches the HTML from your origin, strips navigation/scripts/styles, and converts the body to clean markdown. Agents get structured content; browsers get normal HTML. Zero application code required.

The catch: It's only available on Pro, Business, and Enterprise plans. I'm on the Free plan.

The DIY approach: Since my blog posts are written in MDX, the raw source is already mostly valid markdown. Astro's content collections expose entry.body, which contains the raw MDX before JSX processing. I can serve this directly when an agent requests markdown.

Here's what I changed in my blog post route:

---
import { getEntry, render } from 'astro:content';
import Layout from '../../layouts/Default.astro';

const { id } = Astro.params;
const post = await getEntry('writings', id);

if (!post) {
  return new Response('Not found', { status: 404 });
}

// Content negotiation: return raw markdown when requested
const accept = Astro.request.headers.get('Accept') || '';
if (accept.includes('text/markdown')) {
  return new Response(post.body, {
    status: 200,
    headers: {
      'Content-Type': 'text/markdown; charset=utf-8',
      'Vary': 'Accept',
    },
  });
}

const { Content } = await render(post);
---

<Layout title={post.data.title} description={post.data.description}>
  <article>
    <Content />
  </article>
</Layout>

This worked great for blog posts, but the scanner tests multiple pages — not just blog posts. The homepage, about page, projects, talks, links, and even the 404 page all need to respond to Accept: text/markdown. I needed a site-wide solution.

A Wrinkle: Prerendering vs. Cost

Blog posts are the most frequently accessed pages on a personal blog. Originally, I used server-side rendering for everything — markdown requests ran getEntry() and returned post.body, while HTML requests ran render() to compile MDX into HTML. This worked, but every blog post request hit the Cloudflare Worker, counting against the free daily request limit.

The fix was to prerender blog posts back to static HTML (Astro's default behavior) and move markdown negotiation to a dedicated API endpoint that only runs when explicitly requested:

import type { APIRoute } from 'astro';
import { getEntry } from 'astro:content';

export const GET: APIRoute = async ({ params }) => {
  const post = await getEntry('writings', params.id);
  if (!post) {
    return new Response('Not found', { status: 404 });
  }

  return new Response(post.body, {
    status: 200,
    headers: {
      'Content-Type': 'text/markdown; charset=utf-8',
      'Vary': 'Accept',
    },
  });
};

The blog post page itself is now prerendered:

---
import { getCollection, getEntry, render } from 'astro:content';

export const prerender = true;

export async function getStaticPaths() {
  const posts = await getCollection('writings');
  return posts.map((post) => ({
    params: { id: post.id },
  }));
}

const { id } = Astro.params;
const post = await getEntry('writings', id);
if (!post) {
  return new Response('Not found', { status: 404 });
}

const { Content } = await render(post);
---

To wire it all together, a Cloudflare Transform Rule routes markdown requests to the API. This is the key insight: on the Free plan, static HTML is served from the CDN at no cost, while every Worker invocation counts toward your daily limit. By intercepting markdown requests at the edge before they reach the Worker, normal browser traffic bypasses the Worker entirely:

Browsers hit /writings/my-post — no rule match — static HTML from the CDN (free)
Agents hit /writings/my-post with Accept: text/markdown — rule matches — rewrites to /api/markdown/my-post internally, API returns raw MDX

The rule uses Cloudflare's Rules Language. Note that http.request.headers["accept"] returns an Array<String>, so you must use any() with wildcard index [*]:

Expression: starts_with(http.request.uri.path, "/writings/") and any(http.request.headers["accept"][*] contains "text/markdown")
Rewrite path: concat("/api/markdown/", substring(http.request.uri.path, 10))

This rewrite is internal — the client never sees the /api/markdown/ URL. The agent gets text/markdown, the browser gets text/html, and only markdown-requesting agents pay the Worker cost.

Extending Markdown Negotiation to Every Other Page

Astro's frontmatter syntax makes early returns tricky. A page with <script> tags can't simply return new Response() in frontmatter without confusing Astro's compiler. After some trial and error with the coding agent, I settled on a middleware pattern for the remaining pages:

import { defineMiddleware } from 'astro:middleware';
import { MarkdownResponse } from '../utils/markdown';

export const onRequest = defineMiddleware(async (_context, next) => {
  try {
    return await next();
  } catch (error) {
    if (error instanceof MarkdownResponse) {
      return error.response;
    }
    throw error;
  }
});

import type { AstroGlobal } from 'astro';

export function wantsMarkdown(astro: AstroGlobal): boolean {
  const accept = astro.request.headers.get('Accept') || '';
  return accept.includes('text/markdown');
}

export class MarkdownResponse extends Error {
  response: Response;
  constructor(body: string) {
    super('MarkdownResponse');
    this.response = new Response(body, {
      status: 200,
      headers: {
        'Content-Type': 'text/markdown; charset=utf-8',
        'Vary': 'Accept',
      },
    });
  }
}

Each page now constructs a markdown string from its data, then throws a MarkdownResponse if the client requested markdown. The middleware catches it and returns the proper HTTP response.

For example, the projects page generates a markdown list from its data:

---
// ... fetch projects data ...

let markdownBody = `# Projects\n\nA collection of things I've built, shipped, and open-sourced.\n\n`;

for (const project of allProjects) {
  const tags = project.tags?.length ? ` (${project.tags.join(', ')})` : '';
  markdownBody += `- [${project.title}](${project.link})${tags} — ${project.description}\n`;
}

if (wantsMarkdown(Astro)) throw new MarkdownResponse(markdownBody);
---

Every page follows this pattern — homepage, about, projects, talks, links, and even the 404 page. Each one constructs a meaningful markdown representation of its content, with proper links and structure, then throws MarkdownResponse when Accept: text/markdown is present.

Trade-offs: The raw MDX body for blog posts is about 95% valid markdown, but it may contain JSX component tags. For other pages, I'm constructing markdown programmatically from the page's data — which is cleaner but requires per-page logic. It's not as clean as Cloudflare's native feature — which strips navigation, footers, and scripts automatically — but it works on the Free plan and provides genuine value to agents on every route.

What I Skipped (and Why)

API Catalog (RFC 9727)

The scanner checks for /.well-known/api-catalog returning application/linkset+json. The idea is to advertise your APIs with link relations like service-desc (OpenAPI spec), service-doc (documentation), and status (health endpoint).

My site has no public APIs. Creating a JSON catalog was unnecessary ceremony. If I ever add a proper API surface with multiple public endpoints, OpenAPI specs, and documentation, I'll add a catalog. Until then, an empty catalog or a catalog with one entry is just noise.

OAuth/OIDC Discovery & Protected Resource Metadata

These checks look for /.well-known/openid-configuration and /.well-known/oauth-protected-resource. They're designed for sites with OAuth-protected APIs that agents need to authenticate against.

My only "protected" endpoint is /generate-og, which uses an internal token, not OAuth. There are no public APIs requiring agent authentication, so OAuth discovery metadata would be pure theater.

MCP Server Card, Agent Skills, WebMCP

These assume you're operating infrastructure specifically designed for AI agent consumption:

MCP Server Card: Advertises a running MCP (Model Context Protocol) server
Agent Skills: Publishes a discovery index of agent tools/skills
WebMCP: Exposes browser-side tools via the WebMCP API

I don't have an MCP server. I don't have agent skills. I don't have site actions that need to be exposed to browser-based agents. Publishing empty stub files for all of these would be actively misleading.

The Final Scan

After implementing the three changes, I deployed the site and re-ran the scanner. All scores were now at 100!

Check	Before	After
Link headers (RFC 8288)	🔴 Fail	🟢 Pass
Markdown negotiation	🔴 Fail	🟢 Pass
Content Signals	🔴 Fail	🟢 Pass

What I Learned

Don't cargo-cult scanner recommendations: When I first ran the scanner, I opted for all the checks, even though not all of them were relevant. Only run the scans for the categories that are relevant to your website.
Quick metadata wins have absurdly high ROI: Adding Link headers took 6 lines of code. Adding Content Signals took 1 line in a text file. Both immediately improved how agents discover and reason about the site. These are the changes to prioritize.
Know your platform: Cloudflare's native Markdown for Agents would have saved me from writing custom content negotiation logic, but it's not available on the Free plan. The DIY approach — middleware + per-page markdown generation — works, but it's worth understanding what you're giving up.
Be honest about what your site offers: Publishing empty discovery documents (API catalogs, OAuth metadata, MCP server cards) is worse than not publishing them. Agents that discover these files expect them to be meaningful. Don't waste their time.
Prerender blog posts, but keep an escape hatch for agents: Astro's prerendering generates static HTML that serves straight from the edge — zero Worker invocations, zero cost. For pages that agents might request in markdown, a separate API endpoint plus a Cloudflare Transform Rule gives you the best of both worlds: static HTML for humans, raw markdown for agents, without adding Worker overhead to normal traffic.

Summary

Making your site "agent-ready" doesn't mean implementing every recommendation from every scanner. It means providing honest, useful signals to agents that visit your site, while recognizing the gap between what a scanner demands and what your site actually is.

For a personal blog, that means:

Link headers — advertise your machine-readable resources (sitemaps, feeds, author pages)
Content Signals — declare your AI usage preferences in robots.txt
Markdown negotiation — serve raw markdown when agents request it, or enable Cloudflare's native feature if you're on Pro+
Skip everything else — unless you actually run the infrastructure the scanner is looking for

The goal isn't a perfect score. The goal is to be a good citizen of the agent-accessible web.

If you run your own site through isitagentready.com, I'd love to hear what you decided to implement and what you skipped. Hit me up on X/Twitter to share how you're making your sites agent-ready!

References

Controlling Elgato Key Lights with Voice Agent

Harshil Agrawal — Mon, 18 May 2026 13:48:35 +0000

I have an Elgato Air Light sitting on my desk. It's great for video recording and calls. But every time I want to turn it on, adjust the brightness, or change the color temperature, I have to reach for my phone, open the app, and tap through menus. It's a small friction, but it adds up.

I also had an M5Stack Core2 gathering dust — an ESP32-based device with a built-in microphone, speaker, and touch screen. I kept thinking: what if I could just talk to it? "Turn on my light." "Make it warmer." "Dim it to 30 percent."

That's when I thought, why not use the Cloudflare Agent SDK to build an agent. I started building my agent with custom functions to handle audio input and output. The M5Stack would connect to the agent deployed on the edge, send the audio chunks, the agent would process this, perform the action, and stream the audio response back to the device. This was working fine, but it was a lot of code, fragile code. If I switched the Text-To-Speech (TTS) or Speech-To-Text(STT) models, I would have to update the code to handle encoding, and decoding. This wasn't fun at all.

Then in April, 2026, Cloudflare announced Cloudflare's Voice SDK. The SDK turns an agent into a real-time voice agent with streaming speech-to-text, text-to-speech, and conversation history. Combine that with Workers AI for the LLM and Cloudflare Mesh for reaching local devices from the edge, and I had everything I needed.

In this article, I'll walk you through how I built a voice-controlled smart light system — from the ESP32 firmware to the Worker running on Cloudflare's edge, and all the gotchas I hit along the way. The article will focus more on the Cloudflare stack, and not the device code.

What I built

A voice assistant running on the M5Stack Core2 that can:

Have natural conversations using streaming speech-to-text and text-to-speech
Control my Elgato Air Light on the local network — turn it on/off, adjust brightness and color temperature
Do all processing on Cloudflare's edge — the ESP32 is just a microphone, speaker, and display

Here's the architecture. Click each node to see what it does:

When I say "turn on my light," the LLM recognizes the intent, calls a tool function, which reaches the Elgato light through Cloudflare Mesh — and then speaks back "Done, I've turned on your light."

Prerequisites

Before you follow along, here's what you'll need:

An M5Stack Core2 (or any ESP32 with mic and speaker)
An Elgato Key Light or Air Light on your local network
A Raspberry Pi 3/4/5 (or any Linux machine) on the same local network as the light
A Cloudflare account with Workers AI enabled
Familiarity with TypeScript and Arduino/C++

The Voice SDK: `withVoice`

The @cloudflare/voice SDK provides a withVoice mixin that turns any Cloudflare Agent (Durable Object) into a real-time voice agent. It handles:

Continuous streaming STT (speech-to-text) via the Flux model
Sentence-level TTS (text-to-speech) via Deepgram Aura
Conversation history persistence in SQLite
Interruption handling (new speech cancels in-progress TTS)
A WebSocket protocol that clients connect to

This is where things got exciting for me. The SDK abstracts away so much of the complexity that the core server code is surprisingly compact.

Here's what a single spoken turn looks like inside the Worker:

The server

import { Agent, routeAgentRequest, type Connection } from 'agents';
import { withVoice, WorkersAIFluxSTT, type VoiceTurnContext } from '@cloudflare/voice';
import { streamText } from 'ai';
import { createWorkersAI } from 'workers-ai-provider';

const VoiceAgentBase = withVoice(Agent, { audioFormat: 'pcm16' });

export class VoiceAgent extends VoiceAgentBase<Env> {
  transcriber = new WorkersAIFluxSTT(this.env.AI);
  tts = new PCM16TTS(this.env.AI);

  async onTurn(transcript: string, context: VoiceTurnContext) {
    const workersAi = createWorkersAI({ binding: this.env.AI });

    const result = streamText({
      model: workersAi('@cf/moonshotai/kimi-k2.6'),
      system: 'You are a helpful voice assistant. Keep responses concise.',
      messages: [
        ...context.messages.map(m => ({
          role: m.role as 'user' | 'assistant',
          content: m.content,
        })),
        { role: 'user', content: transcript },
      ],
      abortSignal: context.signal,
    });

    return result.textStream;
  }
}

The onTurn method is called whenever the user finishes speaking. It receives the transcript and returns a text stream — the SDK handles converting that text to speech and streaming the audio back. Make sure to append the current transcript to context.messages when building the message list for the LLM.

PCM16 TTS: Why I needed a custom class

This was the first gotcha I hit. The built-in WorkersAITTS class sends { text, speaker } to the Deepgram model (it defaults to aura-1), which outputs MP3 by default. The ESP32 doesn't have an MP3 decoder (or at least what the coding agents told me), so I needed raw PCM16 audio instead.

The fix: a custom TTS class that calls the aura-2-en model directly and passes encoding: "linear16", sample_rate: 24000, and container: "none":

class PCM16TTS {
  #ai: Ai;
  constructor(ai: Ai) {
    this.#ai = ai;
  }
  async synthesize(text: string, signal?: AbortSignal): Promise<ArrayBuffer | null> {
    const resp = await this.#ai.run(
      '@cf/deepgram/aura-2-en' as any,
      {
        text,
        speaker: 'luna',
        encoding: 'linear16',
        sample_rate: 24000,
        container: 'none',
      } as any,
      { returnRawResponse: true, ...(signal ? { signal } : {}) }
    );
    return await (resp as Response).arrayBuffer();
  }
}

Chunking audio for the ESP32

TTS generates audio per-sentence. A short sentence like "Hi! How can I help you?" produces ~90KB of PCM16 data. The ESP32 WebSocket library has a maximum frame size (WEBSOCKETS_MAX_DATA_SIZE), and the device has limited heap (~170KB free). Sending a single 90KB frame works but leaves little headroom.

The afterSynthesize hook lets me chunk audio into smaller frames before sending:

const AUDIO_CHUNK_SIZE = 4096;

afterSynthesize(audio: ArrayBuffer | null, _text: string, connection: Connection) {
  if (!audio) return null;
  const src = new Uint8Array(audio);
  for (let offset = 0; offset < src.byteLength; offset += AUDIO_CHUNK_SIZE) {
    const end = Math.min(offset + AUDIO_CHUNK_SIZE, src.byteLength);
    connection.send(src.slice(offset, end));
  }
  return null; // returning null tells the SDK we handled sending ourselves
}

The WebSocket protocol

The withVoice SDK defines a WebSocket protocol between the client and the server. Here's the full message flow:

Client → Server

Message	When
`{"type":"hello","protocol_version":1}`	On connect
`{"type":"start_call","preferred_format":"pcm16"}`	User taps to start
Binary PCM16 frames (16kHz, 16-bit, mono)	Continuously while in call
`{"type":"end_call"}`	User taps to end

Server → Client

Message	Description
`welcome`	Connection acknowledged
`status`	State changes: `idle`, `listening`, `thinking`, `speaking`
`transcript`	Final transcript with `role: "user"` or `"assistant"`
`transcript_interim`	Partial STT result while user is speaking
`transcript_start/delta/end`	Streaming LLM response tokens
`audio_config`	Audio format info (format, sampleRate)
`metrics`	Timing info (llm_ms, tts_ms, first_audio_ms)
Binary frames	PCM16 audio during `speaking` status

The ESP32 client

The M5Stack Core2 has a built-in microphone, speaker, display, and touch screen. The firmware does the following:

Connects to WiFi, then opens a WebSocket to the Worker
Sends hello and waits for welcome
On touch: sends start_call, receives the agent's greeting, then begins streaming mic audio as binary PCM16 frames
Receives status updates, transcripts, and audio — plays audio through the speaker using triple-buffered playRaw()
On touch again: sends end_call

This part took the most debugging. The ESP32 is a constrained device, and the M5Stack Core2 has some quirks that weren't obvious from the documentation.

Gotcha: mic reinit after speaker playback

The M5Stack Core2 has separate I2S buses for the microphone and speaker, but Speaker.playRaw() disrupts the mic's I2S state. After playback stops, the mic produces silence. This one took me a while to figure out — I kept thinking my WebSocket connection was dropping, but the mic was just... silent.

The fix: fully tear down and reinitialize the mic after each playback session:

void stop_playback() {
    M5.Speaker.stop();
    M5.Speaker.end();
    is_playing = false;

    // Restart mic — Speaker.playRaw disrupts the mic I2S bus
    M5.Mic.end();
    delay(10);
    auto mic_cfg = M5.Mic.config();
    mic_cfg.sample_rate = 16000;
    mic_cfg.magnification = 16;
    M5.Mic.config(mic_cfg);
    M5.Mic.begin();
}

Gotcha: WebSocket Host header

The ESP32 WebSocket library sends Host: hostname:443 in the header, but routeAgentRequest (which uses partyserver internally) expects just Host: hostname. The extra :443 causes routing to fail silently — no error, no log, just a connection that never reaches the Durable Object.

Important: You need to patch the WebSocketsClient library to omit the port when it's 443 or 80.

Gotcha: Durable Object path routing

routeAgentRequest converts Durable Object binding names to kebab-case for URL routing. The binding VoiceAgent maps to path /agents/voice-agent/default, not /agents/VoiceAgent/default. The coding agents spent an embarrassing amount of time on this one.

Greeting on call start

One nice touch: the agent can speak immediately when a call begins by implementing onCallStart:

async onCallStart(connection: Connection) {
  await this.speak(connection, 'Hi! How can I help you?');
}

That means start_call can produce server audio before the user says anything. It makes the experience feel much more natural.

Adding smart home control: Elgato Air Light via Mesh

Now for the interesting part. I wanted to say "turn on my light" and have the Worker control the Elgato Air light sitting on my local network.

The challenge

The Elgato Air Light exposes a REST API on the local network (http://<ip>:9123/elgato/lights). But the Worker runs on Cloudflare's edge — it can't reach 192.168.x.x directly.

The solution: Cloudflare Mesh + VPC Networks

Why Cloudflare Mesh and not Cloudflare Tunnel?

If you've used Cloudflare before, you might be wondering: why not just use Cloudflare Tunnel? Both connect your private network to Cloudflare, but they solve different problems.

Cloudflare Tunnel (cloudflared) is designed for publishing specific services to the internet. You configure a public hostname (like light.example.com), and Tunnel proxies inbound traffic from the internet to your local service. It's great for "I want my app reachable at this URL." But each service needs its own tunnel route, and the Worker can't initiate arbitrary requests to any local IP — it can only reach the services you've explicitly published.

Cloudflare Mesh (formerly WARP Connector) is designed for private network connectivity. A Mesh node advertises CIDR routes, making an entire subnet reachable. With a VPC Network binding, your Worker gets a MESH.fetch() that can reach any IP and port in the advertised range — no per-service configuration needed.

	Cloudflare Tunnel	Cloudflare Mesh
Traffic direction	Inbound to origin — clients connect to published services	Bidirectional — any participant can initiate
Addressing	By public hostname	By private IP (every participant gets a Mesh IP)
Worker access	Reach specific published services	Reach any IP/port in the advertised subnet
Connector	`cloudflared`	`warp-cli`
Protocols	HTTP/S, TCP, SSH, RDP, SMB	TCP, UDP, ICMP
Best for	Exposing apps to the internet	Private network connectivity, VPN replacement

For this project, the Worker needs to call the Elgato's local REST API at 192.168.x.x:9123 — a private IP that shouldn't be exposed publicly. Mesh gives the Worker outbound access to the entire local subnet with a single binding. If I add more smart devices later, they're automatically reachable too — no new tunnel routes to configure.

This is the same approach I used in my previous article to expose OpenClaw to the internet, but this time using Mesh instead of Tunnels.

The flow:

Worker calls env.MESH.fetch("http://192.168.x.x:9123/elgato/lights")
    → Cloudflare routes to Mesh network
    → Mesh node on local LAN receives the request
    → Forwards to Elgato at 192.168.x.x:9123
    → Response flows back the same path

Setting up the Mesh node

Mesh nodes require Linux. I used a Raspberry Pi 4 sitting on the same local network as the Elgato light.

Step 1: Create a Mesh node in the Cloudflare dashboard

Go to Networking > Mesh and select Add a node. Name it (e.g. home-network) and copy the connector token.

Step 2: Install the WARP client on the Raspberry Pi

SSH into the Pi and run:

# Add Cloudflare's GPG key and repo
curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg \
  | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/cloudflare-client.list

sudo apt-get update && sudo apt-get install -y cloudflare-warp

Step 3: Register as a Mesh connector and connect

sudo warp-cli connector new <YOUR_TOKEN>
sudo warp-cli connect

Verify:

sudo warp-cli status
# Should show: Status update: Connected

The node should appear as Online in the Mesh dashboard with a Mesh IP assigned.

Step 4: Add a CIDR route

In the Mesh dashboard, go to your node > Routes tab > Add route: 192.168.x.0/24. This tells Cloudflare that this Mesh node can forward traffic to devices on the local 192.168.x.x subnet — including the Elgato light.

Step 5: Configure NAT/MASQUERADE on the Mesh node

Important: By default, traffic from your Worker arrives at the Mesh node with a source IP in the 100.96.0.0/12 WARP range. When the Mesh node forwards this to a local device (like your Elgato), that device will try to reply to its default gateway (your router) instead of the Mesh node, causing connection timeouts.

You need to configure the Mesh node to rewrite the source IP before forwarding to local devices. I cover the exact nftables commands in the Gotchas section below. However, if your application is running on the same machine as the Mesh node, you don't need to set this up.

The Elgato REST API

The Elgato Key Light / Air Light exposes a simple HTTP API on port 9123:

Endpoint	Method	Description
`/elgato/lights`	GET	Get current state
`/elgato/lights`	PUT	Set state
`/elgato/accessory-info`	GET	Device info

The state payload:

{
  "numberOfLights": 1,
  "lights": [{
    "on": 1,
    "brightness": 50,
    "temperature": 200
  }]
}

on: 1 = on, 0 = off
brightness: 0–100
temperature: 143–344 (mirek scale — 143 = ~7000K cool white, 344 = ~2900K warm white)

Adding tool calling to the voice agent

Now that I had a way to reach the Elgato from the Worker, I needed the LLM to call the right API based on what I say. The Vercel AI SDK supports tool calling — you define tools with descriptions and parameters, and the LLM decides when to call them based on user intent.

The kimi-k2.6 model on Workers AI supports multi-turn tool calling natively. When you pass tools to streamText, the SDK:

Sends tool definitions to the LLM
When the LLM returns a tool call, executes the execute function
Feeds the result back to the LLM
The LLM generates a natural language response

The textStream returned to onTurn only contains the final spoken text — all the tool calling happens transparently.

Wrangler config

{
  "compatibility_flags": ["nodejs_compat"],
  "compatibility_date": "2025-09-21",
  "migrations": [
    {
      "new_sqlite_classes": ["VoiceAgent"],
      "tag": "v1"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "VoiceAgent",
        "name": "VoiceAgent"
      }
    ]
  },
  "ai": {
    "binding": "AI"
  },
  "vpc_networks": [
    {
      "binding": "MESH",
      "network_id": "cf1:network",
      "remote": true
    }
  ],
  "vars": {
    "ELGATO_IP": "192.168.8.187"
  }
}

Tool definitions

import { tool } from 'ai';
import { z } from 'zod/v4';

const ELGATO_PORT = 9123;

function elgatoUrl(env: Env, path: string) {
  return `http://${env.ELGATO_IP}:${ELGATO_PORT}${path}`;
}

function elgatoTools(env: Env) {
  const fetchLight = async (init?: RequestInit) => {
    try {
      return await env.MESH.fetch(elgatoUrl(env, '/elgato/lights'), init);
    } catch {
      return new Response(JSON.stringify({ error: 'Light unreachable via Mesh' }), {
        status: 503,
        headers: { 'Content-Type': 'application/json' },
      });
    }
  };
  const putLight = (body: object) =>
    fetchLight({
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
  const getLightState = async () => {
    const res = await fetchLight();
    return (await res.json()) as {
      numberOfLights: number;
      lights: Array<{ on: number; brightness: number; temperature: number }>;
    };
  };

  return {
    get_light_status: tool({
      description: 'Get the current status of the desk light',
      inputSchema: z.object({}),
      execute: async () => {
        const res = await fetchLight();
        return await res.json();
      },
    }),

    turn_light_on: tool({
      description: 'Turn the desk light on',
      inputSchema: z.object({}),
      execute: async () => {
        const state = await getLightState();
        const light = state.lights[0];
        light.on = 1;
        const res = await putLight({ numberOfLights: 1, lights: [light] });
        return { success: res.ok };
      },
    }),

    turn_light_off: tool({
      description: 'Turn the desk light off',
      inputSchema: z.object({}),
      execute: async () => {
        const state = await getLightState();
        const light = state.lights[0];
        light.on = 0;
        const res = await putLight({ numberOfLights: 1, lights: [light] });
        return { success: res.ok };
      },
    }),

    set_light_brightness: tool({
      description: 'Set the desk light brightness (0-100)',
      inputSchema: z.object({
        brightness: z.number().min(0).max(100),
      }),
      execute: async ({ brightness }) => {
        const state = await getLightState();
        const light = state.lights[0];
        light.brightness = brightness;
        const res = await putLight({
          numberOfLights: 1,
          lights: [light],
        });
        return { success: res.ok, brightness };
      },
    }),

    set_light_temperature: tool({
      description: 'Set the color temperature (143=cool to 344=warm)',
      inputSchema: z.object({
        temperature: z.number().min(143).max(344),
      }),
      execute: async ({ temperature }) => {
        const state = await getLightState();
        const light = state.lights[0];
        light.temperature = temperature;
        const res = await putLight({
          numberOfLights: 1,
          lights: [light],
        });
        return { success: res.ok, temperature };
      },
    }),
  };
}

Then in onTurn:

import { stepCountIs } from 'ai';

async onTurn(transcript: string, context: VoiceTurnContext) {
  const workersAi = createWorkersAI({ binding: this.env.AI });
  const messages = [
    ...context.messages.map(m => ({
      role: m.role as 'user' | 'assistant',
      content: m.content,
    })),
    { role: 'user', content: transcript },
  ];

  const result = streamText({
    model: workersAi('@cf/moonshotai/kimi-k2.6'),
    system: `You are a helpful voice assistant that can also control the desk light.
When asked about the light, use the available tools. Keep responses concise and natural.`,
    tools: elgatoTools(this.env),
    messages,
    abortSignal: context.signal,
    stopWhen: stepCountIs(5),
  });

  return result.textStream;
}

That's it. The LLM handles intent recognition. When I say "make it brighter," the model calls set_light_brightness. When I say "what's the weather," it just responds normally. No keyword parsing, no intent classification system — the LLM figures it out.

Note: The stopWhen: stepCountIs(5) option gives the model enough room for the tool-call → tool-result → final-answer loop, while preventing an accidental unbounded tool loop. In my Worker, I also log tool-call start/finish and step summaries so Mesh or schema failures are visible in Worker logs.

What's running where

Component	Where	What it does
ESP32 firmware	M5Stack Core2 on my desk	Mic input, speaker output, touch UI, WebSocket client
VoiceAgent	Cloudflare Worker (Durable Object)	STT, LLM, TTS, tool execution, conversation history
Workers AI	Cloudflare edge	Flux STT, kimi-k2.6 LLM, Deepgram aura-2-en TTS
Mesh node	Raspberry Pi 4 on local LAN	WARP connector bridging Cloudflare to local network
Elgato Air Light	Local network (192.168.8.187:9123)	HTTP API for light control

Gotchas and lessons learned

I hit a lot of issues building this. Here's a summary of everything I ran into, including some I already mentioned above.

The built-in WorkersAITTS defaults to MP3. If your client can't decode MP3, you need a custom TTS class that explicitly requests encoding: "linear16". I covered this earlier in the PCM16 TTS section.
routeAgentRequest uses kebab-case paths. The Durable Object binding VoiceAgent maps to URL path /agents/voice-agent/default, not /agents/VoiceAgent/default.
ESP32 mic needs reinit after speaker playback. On the M5Stack Core2, Speaker.playRaw() disrupts the mic I2S bus. You must call Speaker.end(), Mic.end(), then Mic.begin() to restore it.
WebSocket Host header matters. The ESP32 WebSocket library sends Host: hostname:443, which breaks routeAgentRequest routing. Patch the library to omit standard ports.
afterSynthesize returning null is valid. You can use it to chunk large TTS audio into smaller WebSocket frames — just send them yourself via connection.send() and return null so the SDK doesn't double-send.
Tool calling needs a bounded multi-step loop. Define tools with execute functions, pass them to streamText, and use stopWhen: stepCountIs(5) so the SDK can run the tool-call → execute → feed-result → generate-response loop. The textStream only yields the final spoken text.
1. Mesh routing requires NAT/MASQUERADE on the Mesh node. If your Worker gets HandshakeTimeoutError when calling a local device via env.MESH.fetch(), the issue is asymmetric routing. When a packet arrives from the Worker, its source IP is in the 100.96.0.0/12 WARP range. The local device replies to its default gateway (your router), not back to the Mesh node.
The official Cloudflare docs recommend solving this by either making the Mesh node the subnet's default gateway, or adding a static route on your router that points 100.96.0.0/12 to the Mesh node. The coding agent went with a different approach: rewriting the source IP before forwarding to local devices using nftables:

On modern Linux systems using nftables (most newer Raspberry Pi OS versions), add this rule:

   # Check which firewall tool is available
   which nft  # If this returns a path, use nftables. If not, install iptables.

   # Add MASQUERADE rule (replace eth0 with your LAN interface: eth0, wlan0, etc.)
   sudo nft add table ip nat
   sudo nft add chain ip nat postrouting { type nat hook postrouting priority 100 \; }
   sudo nft add rule ip nat postrouting oifname "wlan0" iifname "CloudflareWARP" masquerade

To verify this is the issue before fixing it, SSH into your Mesh node and run:

   # This will fail (simulates the Worker's packet path)
   curl --interface 100.96.0.2 http://<ELGATO_IP>:9123/elgato/lights
   # Error: Failed to connect / Handshake timeout

   # This works (local origin traffic)
   curl http://<ELGATO_IP>:9123/elgato/lights
   # Returns: {"numberOfLights":1,...}

If the first curl fails but the second succeeds, you need the MASQUERADE rule. Make it persistent across reboots by saving the ruleset and loading it at boot:

   echo 'table ip nat {
       chain postrouting {
           type nat hook postrouting priority 100;
           oifname "wlan0" iifname "CloudflareWARP" masquerade
       }
   }' | sudo tee /etc/nftables-mesh-nat.nft

   sudo nft -f /etc/nftables-mesh-nat.nft

   # Persist across reboots (add to crontab)
   (crontab -l 2>/dev/null; echo "@reboot sleep 10 && sudo nft -f /etc/nftables-mesh-nat.nft") | crontab -

Summary

I started with a simple frustration — reaching for my phone every time I wanted to adjust my desk light. What I ended up with is a voice assistant that runs on an ESP32, processes everything on Cloudflare's edge, and controls local devices through Mesh networking.

The stack that made this possible:

@cloudflare/voice SDK — handles the hard parts of real-time voice (STT, TTS, conversation state, interruption)
Workers AI — LLM with tool calling for intent recognition
Cloudflare Mesh — bridges the gap between the edge and my local network
Vercel AI SDK — clean tool calling abstraction on top of Workers AI

The biggest surprises were the ESP32 quirks (mic reinit after speaker, WebSocket Host header) and the Mesh NAT issue. None of these were documented anywhere, so I hope this article saves you some debugging time.

What's next

There's a lot more I want to do with this setup:

Add more devices — I have other smart lights on my local network that I'd love to control by voice
Improve the ESP32 experience — a proper UI on the display showing conversation state and light status
Experiment with wake word detection instead of the touch-to-talk button
Try different LLM models as Workers AI adds more options. Kimi K2.6 is excellent, but a bit overkill for this. I might try with smaller models like Granite 4.0 or others from Workers AI.

If you are building something similar, or run into any issues, feel free to hit me up on X (Twitter) or LinkedIn. I'd love to hear about what you're building with the Voice SDK and Mesh. I also co-authored a book - Building a Virtual Assistant with Raspberry Pi that will help you learn how to build an offline first virtual assistant!

Migrating from Astro 5 to Astro 6: A Real-World Breakdown 📖

Harshil Agrawal — Sun, 03 May 2026 13:05:28 +0000

I have been meaning to upgrade my personal site to Astro 6 for a while. The release notes sat in my open tabs for weeks, and every time I sat down to do it, I found an excuse to work on something else. This week, I finally ran out of excuses. I carved out an afternoon, ran npx @astrojs/upgrade, crossed my fingers, and expected a smooth ride.

The dev server crashed immediately with a cryptic error about a missing tailwindcss package.

I stared at the error for a minute. Then I did what any reasonable developer would do in 2026 — I looped in an AI coding agent and told it to help me fix everything.

This post is the field guide I wish I had, and also a reminder that AI agents are incredibly helpful but dangerously confident. You still need to know what you're doing.

What I started with

Astro 5.x (various patch releases)
@astrojs/cloudflare v12.x
@astrojs/tailwind v5.x
Legacy content collections (src/content/config.ts, type: 'content'/'data')
astro-expressive-code v0.38.x
astro-icon v1.1.5

What I ended up with

Astro 6.2
@astrojs/cloudflare v13
Tailwind CSS v4 (@tailwindcss/vite)
astro-expressive-code v0.41.7
A custom inline-SVG icon component (replacing astro-icon)

Error 1: `Cannot find package 'tailwindcss'`

Cannot find package 'tailwindcss' imported from
.../node_modules/@astrojs/tailwind/dist/index.js

What happened

@astrojs/tailwind v6 was installed by the upgrade command, but its package.json only lists tailwindcss as a peer dependency — it does not bundle it. Since tailwindcss wasn't in my dependencies, Node couldn't resolve it.

The agent's diagnosis

I pasted the error into the agent and asked what was going on. It diagnosed the peer dependency issue immediately and confidently moved to PostCSS. It added postcss.config.mjs, autoprefixed and the @tailwind directives. The site was functional again, but the apporach was completely off.

I had to ask the agent to stick with TailwindCSS and migrate to PostCSS. I asked the agent to check the Astro docs instead of guessing. The agent then used the tools and came up with two options:

Option A: Stay on Tailwind 3 (simplest)

Install tailwindcss@3 alongside the integration and keep everything as-is:

npm install tailwindcss@3

Your astro.config.mjs stays the same:

import tailwind from '@astrojs/tailwind';
// ...
integrations: [tailwind()]

This is the path Astro docs recommend for legacy Tailwind 3 projects.

Option B: Upgrade to Tailwind 4

Astro 5.2+ includes an astro add tailwind command that installs the official Vite plugin (@tailwindcss/vite), which is the new recommended way to use Tailwind 4 in Astro.

npx astro add tailwind

This sets up:

@tailwindcss/vite in your Vite plugins (via astro.config.mjs)
src/styles/global.css with @import "tailwindcss";
Removes the need for tailwind.config.mjs — v4 uses CSS-based configuration instead

If you go this route, you can then remove @astrojs/tailwind entirely and follow Tailwind's v4 upgrade guide to migrate your custom theme to CSS variables.

What happened next: The correct apporach

I instructed the agent to proceed with Option B, running npx astro add tailwind to get the proper Vite plugin set up, then migrated the custom theme into the new @theme block in global.css:

@import "tailwindcss";

@theme {
  --color-primary: #f97316;
  --color-hover: #ea580c;
  --color-light: rgba(249, 115, 22, 0.15);
  --color-secondary: #fdba74;
}

@variant dark (&:where(.dark, .dark *));

If you want to keep Tailwind 3: use Option A above and let @astrojs/tailwind do the work.

If you want Tailwind 4: use Option B and the official Vite plugin. Don't manually wire PostCSS.

Error 2: `LegacyContentConfigError`

With Tailwind sorted, I restarted the dev server feeling optimistic. Then the next error hit.

[LegacyContentConfigError] Found legacy content config file in
"src/content/config.ts". Please move this file to
"src/content.config.ts" and ensure each collection has a loader defined.

What happened

Astro 5 introduced the Content Layer API, but kept automatic backwards compatibility for old collections. Astro 6 removed that safety net entirely. My src/content/config.ts with type: 'content' and type: 'data' was no longer valid.

The fix

The agent handled this migration competently. It moved the file, rewrote the imports, and configured the loaders:

Before:

import { defineCollection, z } from 'astro:content';

const writings = defineCollection({
  type: 'content',
  schema: z.object({ ... })
});

const projects = defineCollection({
  type: 'data',
  schema: z.array(z.object({ ... }))
});

export const collections = { writings, projects };

After:

import { defineCollection } from 'astro:content';
import { glob, file } from 'astro/loaders';
import { z } from 'astro/zod';

const writings = defineCollection({
  loader: glob({ pattern: '**/[^_]*.mdx', base: './src/content/writings' }),
  schema: z.object({ ... })
});

const projects = defineCollection({
  loader: file('src/content/projects/projects.json'),
  schema: z.object({ ... })  // not z.array(...)
});

export const collections = { writings, projects };

Key changes:

File location: src/content/config.ts → src/content.config.ts (project root inside src/).
z import: astro:content → astro/zod.
type removed: No more type: 'content' or type: 'data'. You explicitly declare a loader.
Data collections: If you were using type: 'data' with a JSON file, the new file() loader returns one entry per top-level object. The schema should be z.object(...) (one item), not z.array(...) (the whole file).
slug → id: In the old API, entry.slug was auto-derived. In the new API, entry.id is the identifier. My URLs needed updating:

// Before
href={`/writings/${post.slug}`}
// After
href={`/writings/${post.id}`}

Here's where the agent overstepped. It told me that since my posts live in folder/index.mdx structures, glob() would generate IDs from file paths, producing something like migrating-astro-5-to-astro-6/index. It suggested I strip the suffix:

href={`/writings/${post.id.replace(/\/index$/, '')}`}

Something about that felt off. Every post in my writings collection already has a slug field in its frontmatter, and I had a hunch Astro would use that as the entry id. I pushed back and asked the agent to verify against Astro's documentation.

After checking the docs, it couldn't actually confirm that /index gets appended when slug is present in frontmatter. And in practice, post.id was already migrating-astro-5-to-astro-6 and never migrating-astro-5-to-astro-6/index. The .replace() was unnecessary for my setup, and the simple post.id works perfectly.

Note: always verify agent output against your own code and build output. The agent is fast, but you are the one who has to ship it.

So far, so good. The agent was saving me hours. Then it got cocky.

Error 3: `Property 'runtime' does not exist on type 'Locals'`

Content collections were fixed. I was ready to see the site render. But the Cloudflare adapter had other plans.

ts(2339): Property 'runtime' does not exist on type 'Locals'.

What happened

@astrojs/cloudflare v13 removed Astro.locals.runtime entirely. The new documented approach is:

import { env } from 'cloudflare:workers';
const kv = env.MY_KV;

I migrated my API routes to this pattern. But then I hit a runtime error in dev:

module is not defined

originating from the Cloudflare Vite plugin's worker runner.

The agent spent a while suggesting random fixes — clearing caches, reordering imports, checking Vite config — none of which worked. I ended up tracing it myself: @astrojs/cloudflare v13's dev server runs inside workerd, and it has an incompatibility with the astro-icon integration. When astro-icon's <Icon> component was first rendered, the workerd module runner would crash with that cryptic module is not defined error, breaking every route on the site.

At this point, the was frustrated. It had already spent more time on this than it planned. It downgraded back to @astrojs/cloudflare v12 just to get something working.

But we didn't stop there. The agent suggested replacing astro-icon entirely with a tiny custom component that inlines SVG paths from @iconify-json/mdi. Thirty lines of code. No virtual modules. No workerd compatibility issues. We tried it, switched back to v13, and that was the unlock.

The fix: finish the v13 migration properly

First, update wrangler.toml to use the v13 entrypoint:

main = "@astrojs/cloudflare/entrypoints/server"

Then migrate all code from Astro.locals.runtime.env to import { env } from 'cloudflare:workers':

Before:

const { env } = Astro.locals.runtime;
const kv = env.VOTES;

After:

import { env } from 'cloudflare:workers';
const kv = env.VOTES;

For TypeScript, I also had to augment Cloudflare.Env in src/env.d.ts with secrets that aren't declared in wrangler.toml (like YOUTUBE_API_KEY and GITHUB_TOKEN):

declare namespace Cloudflare {
  interface Env {
    YOUTUBE_API_KEY: string;
    PLAYLIST_ID: string;
    GITHUB_TOKEN: string;
  }
}

Note: The agent didn't know about the wrangler types command. This command generates the types, which would have prevented the manual addition.

This is required because import { env } from 'cloudflare:workers' is typed against the global Cloudflare.Env interface, not the project-level Env that wrangler types generates.

Finally, remove astro-icon from package.json and astro.config.mjs, and replace <Icon name="mdi:github" /> usages with the custom component. Problem solved.

Error 4: `astro-expressive-code` peer dependency mismatch

That was the biggest battle. I thought I was in the clear. Then npm run build reminded me that integrations have their own timelines.

peer astro@"^4.0.0-beta || ^5.0.0-beta || ^3.3.0" from astro-expressive-code@0.38.3

What happened

The upgrade command didn't bump astro-expressive-code, so it still had a peer dependency range that excluded Astro 6.

The fix

npm install astro-expressive-code@0.41.7

v0.41.7 officially supports Astro 6.

This one the agent got right on the first try. I take the wins where I can get them.

Error 5: `Buffer<ArrayBufferLike>' is not assignable to parameter of type 'BodyInit'`

Just when I thought the dependency wars were over, TypeScript had one more surprise for me.

In my OG image generation endpoint, I had:

const screenshot = await page.screenshot({ ... });
return new Response(screenshot, { ... });

After the upgrades, TypeScript started rejecting Buffer as a Response body. This wasn't a runtime issue — Puppeteer still returns a Buffer — but astro check (and therefore npm run build) flags it.

The fix

Converted to Uint8Array before passing to Response:

return new Response(new Uint8Array(screenshot), { ... });

This satisfies both the Workers runtime types and TypeScript's strict checks.

Final checklist

Command	Status
`npm install`	✅ (no `--legacy-peer-deps`)
`npm run dev`	✅ All routes render in `workerd`
`npm run build`	✅
`npm run preview`	✅

What I learned

npx @astrojs/upgrade handles the Astro core bump, but integrations often have their own timeline. Always check npm ls for peer dependency warnings after upgrading.
Content collections migration is unavoidable in v6. Astro 5 gave you a grace period. Astro 6 does not. The new loader API is actually clearer once you get used to it.
Adapter upgrades are the riskiest part. @astrojs/cloudflare v13 made major changes to how env bindings work and moved the dev server into workerd. The upside is your dev environment is now nearly identical to production. The downside is that some integrations (like astro-icon) aren't yet compatible with workerd's module loading.
Build != dev. My site built successfully long before the dev server worked. The v13 Cloudflare adapter broke only in dev (astro dev) because of how it runs code inside workerd. Always test both.
When an integration breaks, check the official docs before inventing a workaround. I had already pulled @astrojs/tailwind and installed tailwindcss directly, but the agent pointed me to @tailwindcss/vite — the proper Vite plugin for Tailwind CSS v4. Astro's npx astro add tailwind command sets this up automatically for v4, which is the supported path.
import { env } from 'cloudflare:workers' is the new standard. It replaces Astro.locals.runtime.env completely. If you're on v13, embrace it — just remember that wrangler types generates the Env interface, but cloudflare:workers reads from Cloudflare.Env, so you may need to augment the namespace for secrets.
AI agents are great teammates, but bad team leads. They will suggest wrong approaches confidently, miss root causes, and hallucinate migration details. You need to know enough to push back, verify claims, and direct the strategy.

Summary

Upgrading from Astro 5 to 6 is not a single command. The core bump is smooth, but the integrations around it — Tailwind, Cloudflare, expressive-code — each carry their own breaking changes. If I were doing this again, I would:

Start with the content collections migration (src/content/config.ts → src/content.config.ts).
Decide on Tailwind 3 vs. 4 before running the upgrade. Use npx astro add tailwind for v4, or install tailwindcss@3 for legacy v3.
Go straight to @astrojs/cloudflare v13. The Astro.locals.runtime → import { env } from 'cloudflare:workers' migration is mechanical.
Test npm run dev, not just npm run build. workerd is stricter than Node.

The workerd dev server in v13 is a net positive — my local environment now behaves almost exactly like production — but it is unforgiving. If you hit module is not defined or similar low-level errors, trace which integration is triggering them. Replacing astro-icon with a custom 30-line SVG component removed an entire class of compatibility issues for me.

Implementing localization to your Svelte App: A step-by-step guide

Harshil Agrawal — Mon, 24 Jun 2024 22:23:15 +0000

In today's global market, making your web application accessible to a diverse audience is crucial. Localization enables apps to adapt to different languages and cultural contexts, enhancing user experience.

Tolgee simplifies localization with its open-source i18n tool, combining a localization platform and SDKs. It provides features like in-context translation and automatic screenshot generation, making translation easy for developers and translators. Svelte is an open-source frontend framework that compiles components into small, performant JavaScript modules.

In this tutorial, you'll learn how to implement localization in your Svelte app using Tolgee. Let's get started!

Prerequisites

This tutorial assumes that you have familiarity with JavaScript. Knowledge of Svelte is not required but is good to have. You will also need the following, to follow the tutorial.

Node.js: Install Node.js on your machine if you don’t already have it installed. Use a node version manager tool like nvm to install Node.js.
Tolgee account: You will be using Tolgee to implement localization. Hence, if you don’t have an account, please sign-up here to create an account.
Git: Install Git for your machine. You will use Git for cloning the repo and version management.

Step 1 - Setting up the Svelte App

For this tutorial, you will use the Svelte Tolgee example project. This project is a personal blogging website built using TailwindCSS. If you want to create your own Svelte app, follow the official Svelte documentation. While following the steps further down this tutorial, make sure to adapt to your app.

To clone the project, run the following command in your terminal.

git clone https://github.com/harshil1712/svelte-tolgee-example.git

Next, navigate into the project directory and run the following command to install the required dependencies.

cd svelte-tolgee-example
npm install

Now that you have all the required dependencies installed, run the development server and check out the project. To start the development server, execute the following command in your terminal.

npm run dev

On your browser, navigate to http://localhost:5137. You will see the sample app up and running.

Step 2 - Getting started with Tolgee

In the previous step you scaffolded the Svelte project. In this step you will learn how to get started with Tolgee to integrate it in your Svelte project.

If you don’t have a Tolgee account, create one. After you sign-up/sign in for the first time, you will be presented with a demo project. While that is a good place to explore the platform in depth, for this tutorial, you will create a new project.

To create a new project, click on the + Add Project button. Next, enter the name of your project in the Name field and select the translation languages you. This tutorial implements English (en) and German (de). But you can select other languages as well.

Now that you have the project setup on Tolgee, the next step is to generate the API key. This API key will allow your application to interact with the Tolgee platform. To generate the API key, select Integrate from the left sidebar menu. Next, under the Choose your weapon section, select Svelte. Click on the dropdown menu under the Select API key section, and select Create new +.

Enter the name for your API key in the Description field. Set the Expiration to Never expires.

Note: For the purpose of this tutorial, the Expiration is set to Never expires. Please make sure you are following the best security practices and have set a proper expiration time for the API key.

Next, under Scopes, select Admin. This will give you all the permissions. Click on Save, and your API key will be generated. Scroll down to the Setup your environment (with SvelteKit) section. Copy the URL and the API Key. You will need these in the next step.

Note: Before setting up the API key for production, carefully read and understand Scopes. You don’t want to give everyone the admin access.

Step 3 - Integrating Tolgee in the Svelte app

In the previous step, you configured the Tolgee platform by adding a new project and generating an API key. In this step, you will integrate Tolgee in your Svelte app.

First, at the root of your project, create a .env.development.local file. Paste the URL and the API key you copied in the previous step. Your file should contain the content as shown below, where <YOUR_TOLGEE_API_KEY> is the API key you generated.

VITE_TOLGEE_API_URL=https://app.tolgee.io
VITE_TOLGEE_API_KEY=<YOUR_TOLGEE_API_KEY>

Next, to start using Tolgee and make use of its SDK, you need to install the Tolgee SDK for Svelte. To install this SDK, execute the following command in your terminal.

npm install @tolgee/svelte

You have installed the required SDK and also have the API key to connect to Tolgee. In the next step, you will initialize the Tolgee SDK for your app.

Step 4 - Initializing Tolgee for Svelte

Tolgee comes with a provider component. This component provides the required context to all the children components it gets wrapped on. You will use this provider component to wrap all the child components with some configurations.

Open up the src > routes > +layout.svelte file and paste the following code under the <script> tag. This line of code imports the required methods from the Tolgee SDK.

import { TolgeeProvider, Tolgee, DevTools, FormatSimple } from '@tolgee/svelte';

Next, to configure Tolgee, add the following code under the import statement.

const tolgee = Tolgee()
  .use(DevTools())
  .use(FormatSimple())
  .init({
    defaultLanguage: 'en',
    availableLanguages: ['en', 'de']
    apiUrl: import.meta.env.VITE_TOLGEE_API_URL,
    apiKey: import.meta.env.VITE_TOLGEE_API_KEY,
  });

In the above code, you initialize Tolgee passing on the DevTools and FormatSimple methods. You also configure the default and available languages for your app. Lastly, you configure your Tolgee credentials.

Your updated <script> tag should be as follows.

<script>
    import Navbar from '../components/Navbar.svelte';
    import { TolgeeProvider, Tolgee, DevTools, FormatSimple } from '@tolgee/svelte';

const tolgee = Tolgee()
  .use(DevTools())
  .use(FormatSimple())
  .init({
    defaultLanguage: 'en',
    apiUrl: import.meta.env.VITE_TOLGEE_API_URL,
    apiKey: import.meta.env.VITE_TOLGEE_API_KEY,
    availableLanguages: ['en', 'de']
  });
</script>

Now that you have imported the provider and configured it, the next step is to wrap the children components. In your +layout.svelte file, update the HTML code as follows.

<TolgeeProvider tolgee="{tolgee}">
  <div slot="fallback">Loading...</div>
  <div class="min-h-screen bg-gray-100">
    <Navbar />
    <div class="container mx-auto px-4 py-8">
      <slot />
    </div>
  </div>
</TolgeeProvider>

In the above code, you wrap the children components under the <TolgeeProvider> component. You pass the tolgee configuration and add a fallback component. While the translation gets loaded, the user will see this fallback component. You can modify this fallback component.

Step 5 - Implementing localization

In the previous step, you have initialized Tolgee. In this step, you will learn to implement localization using Tolgee. You will update the navigation bar option elements. These elements will render the localized content for the selected language.

In your src > components > Navbar.svelte file, import the T component (Translation component) from the Tolgee SDK. Paste the following code in the <script> tag.

import { T } from '@tolgee/svelte';

Next, replace the text for anchor tag with <T keyName=”navbar_<VALUE>” defaultValue=”<VALUE>”/>. Here, <VALUE> is the title of the page. The T component takes keyName and defaultValue as parameters. The keyName parameter helps to identify the content. For each unique translating content, its value should be unique. The defaultValue parameter takes the value that should be rendered by default. Your +Navbar.svelte file should be as follows.

<script>
  import { T } from '@tolgee/svelte';
</script>

<nav class="bg-white shadow">
  <div class="container mx-auto px-4">
    <div class="flex justify-between items-center py-6">
      <div class="text-xl font-semibold text-gray-900">My Blog</div>
      <div class="space-x-4">
        <a href="/" class="text-gray-600 hover:text-gray-900"
          ><T keyName="navigation_home" defaultValue="Home"
        /></a>
        <a href="#" class="text-gray-600 hover:text-gray-900"
          ><T keyName="navigation_about" defaultValue="About"
        /></a>
        <a href="#" class="text-gray-600 hover:text-gray-900"
          ><T keyName="navigation_contact" defaultValue="Contact"
        /></a>
      </div>
    </div>
  </div>
</nav>

Run the development server by executing the following command and navigate to http://localhost:5137.

npm run dev

One of the features of Tolgee is in-context translation. In the previous step, you configured the Dev Tools provided by the Tolgee SDK. Press and hold the Option/ALT key on your keyboard and hover over the title. You will observe a red border around the title. If you click on the title holding the Option/ALT key, a Quick Translation window pops up. This is where you can add translation and screenshots.

Step 6 - Using in-context Translation

In the previous step, you implemented the T component. This enabled you to use in-context translation for your app. In this step, you will use in context translation to add translation.

To get started with in-context translation, press and hold the Option/ALT key and click on Home. It will open up a pop window.

Enter the English blog title in the English field. Add the German translation of the title in the German field. Optionally, you can add screenshots in the Screenshot section. Click on Save to save your translation.

You can view this translation on the Tolgee platform. You can also modify it via the platform or via in-context translation option.

There might be scenarios where you want to use the platform to manage translations. In the next step, you will learn how to add translation on the platform.

Step 7 - Manage Translation on the Platform

To use the platform to manage translation, make sure you are logged into the platform. Next, navigate to the project you created for this application. Click on Translations from the left sidebar. You will see the translation for Home is already available there.

To add translation for the About option, click on + on the right corner. Enter navigation_about in the Key field.

Note: The key must be unique. It should match the value you pass to the T component.

Enter the English translation in the English field and click on Save. This will generate the key.

To add the German translation for this key, click on German under navigation_about. Tolgee uses various APIs to provide the translations. You can use one of the provided translations or add your own. To use the translation that Tolgee provides, select one of the translations from the Machine Translation section. Click on Save, to save the translation.

You now have translations for Home and About. However, you can’t really view them in your app without changing the language. In the next step, you will add a language switcher for your application.

Step 8 - Adding a Language Switcher

Irrespective of where the user is based, you should give the user an option to view the content in the language of their choice. Adding a language switcher to your app can help the user select the language from available choices. In this step, you will add a language switcher.

To add a language switcher, open the Navbar.svelte file and update the <script> tag with the following code.

import { T, getTolgee, getTolgeeContext } from '@tolgee/svelte';

const { tolgee } = getTolgeeContext();
const availableLanguages = tolgee.getInitialOptions().availableLanguages;

In the above code, you import the required methods. You get the reference to the Tolgee instance you configured in Step 4. Next, you get the list of all the configured available languages for your app. You will use this list to provide options to the users.

You also need to add a function that listens to the change of language. Paste the following in the <script> tag to add this function.

const t = getTolgee(['language']);

function handleLanguageChange(e) {
  $t.changeLanguage(e.currentTarget.value);
}

The above subscription function listens for the change in language. When the language changes, it gets updated and the respective translated content is displayed to the user.

The last step is to show the user a switch component. To add this component, paste the following code under the <div id=”switch”> tag.

<select value="{$t.getLanguage()}" on:change="{handleLanguageChange}">
  {#each availableLanguages as lan}
  <option>{lan}</option>
  {/each}
</select>

Your finished Navbar.svelte file should have the following code.

<script>
  import { T, getTolgee, getTolgeeContext } from '@tolgee/svelte';

  const { tolgee } = getTolgeeContext();
  const availableLanguages = tolgee.getInitialOptions().availableLanguages;

  const t = getTolgee(['language']);

  function handleLanguageChange(e) {
    $t.changeLanguage(e.currentTarget.value);
  }
</script>

<nav class="bg-white shadow">
  <div class="container mx-auto px-4">
    <div class="flex justify-between items-center py-6">
      <div class="text-xl font-semibold text-gray-900">My Blog</div>
      <div class="space-x-4">
        <a href="/" class="text-gray-600 hover:text-gray-900"
          ><T keyName="navigation_home" defaultValue="Home"
        /></a>
        <a href="#" class="text-gray-600 hover:text-gray-900"
          ><T keyName="navigation_about" defaultValue="About"
        /></a>
        <a href="#" class="text-gray-600 hover:text-gray-900"
          ><T keyName="navigation_contact" defaultValue="Contact"
        /></a>
      </div>
      <div id="switch">
        <select value="{$t.getLanguage()}" on:change="{handleLanguageChange}">
          {#each availableLanguages as lan}
          <option>{lan}</option>
          {/each}
        </select>
      </div>
    </div>
  </div>
</nav>

Save the file with the updated code. Start the development server, if it is not running already. The navigation bar should have a language switcher. Try changing the language, and you should see the respective translated content.

Congratulations, you have successfully implemented localization to your Svelte app using Tolgee.

Conclusion

Tolgee allows you to seamlessly implement localization to your app. It provides features like in-context translation and SDK that makes it easy for your team to manage translations.

In this article, you learned about Tolgee and how to integrate it with Svelte. You implemented localization to the navigation bar. Which means, you only scratched the surface! The next step is to implement localization to the rest of your application.

If you ran into issues while following this tutorial, feel free to hit me up on LinkedIn/X (formerly Twitter). I would be happy to help you. If you have more questions about Tolgee, I encourage you to join the official Slack workspace.

I am looking forward to seeing your localized apps!

Airtable automation: How I streamlined submissions to the Developer Showcase

Harshil Agrawal — Thu, 13 Oct 2022 14:28:58 +0000

NOTE: This post was first published on the Contentful Blog.

In April 2022, we launched the Developer Showcase to highlight the work of the community. Developers share their projects, apps, videos, or blog posts they’ve created around Contentful. The developer showcase has become the go-to place to see what others are building and get inspired!

If you’ve worked on a project that you believe can help the community, you can go to the Developer Showcase page, and submit the form. If your project meets the criteria, you get an email from us for the next step. In this step, you share more information about the project and yourself. This information is then used on the Developer Showcase page.

The process seems straightforward, but there are a lot of repetitive tasks that are being performed behind the scenes. In this tutorial, I’ll share how automated processes using Airtable and a few other integrations got myself some time back!

The manual process and challenges

As mentioned above, if a developer is interested in adding their project to the showcase, they submit a form on the website with initial details. Once the form is submitted, the developer relations (DevRel) team gets a notification over email with the submission details. We then manually enter the details into a Google Sheet.

Imagine, getting submissions every day, and you have to fill out entries in the Google Sheet manually! Yes, data entry is monotonous and time-consuming. I knew it could be automated and save us time.

After the details were entered in the Google Sheet, team members would review the submissions weekly. We’d check and decide if the submissions met the criteria. If the submission was a good fit, the developer would receive an email from us asking them to fill out another form with more details. The information shared via this form would get added to a Contentful space, which was being used to manage the content on the Developer Showcase page (yes, we use Contentful at Contentful!).

The above process was also manual. We had to manually add the relevant information shared via the form to the Contentful space. This again cost us time. I recognized this as another task that could be automated.

Both the tasks were manual, which meant that the chances of human error were high. There were situations where I would enter the information in the wrong columns when I was in a hurry. This was also becoming monotonous.

Automating the boring parts

I take pride in being lazy! My laziness helps me find solutions that make my tasks joyful. Now that I recognized two tasks that could be automated, I started looking for solutions.

My first step was to migrate to a spreadsheet-like tool that provided better features than Google Sheets. I was looking for a tool that would allow me to easily create automation workflows, configure different views, and also have an easy-to-use API.

Luckily for me, we already use Airtable at Contentful for various projects. I created a base in Airtable for the Developer Showcase which would contain all the details — from the initial form submission details to the final details.

Everyone in the DevRel team is involved in the showcase. All of us decide if a submission should be added to the Developer Showcase. We handle this by voting. For every member of the team, I created a view that would list all the submissions that they haven’t viewed. Having an individual view made it easy for my team to go in, view the project, leave their thoughts, and vote. It hardly takes them 15 minutes now!

The migration to Airtable also involved creating automation to handle the form submissions. After setting up the table and the individual views, I created an automation workflow in Zapier.

This workflow would get triggered whenever there was a submission made to the Developer Showcase form. The workflow would then add the new record to the Airtable base, and also send a Slack message to notify us. All I had to do now was to check if the submission was valid and if it was, update the Valid column in Airtable.

The above workflow replaced the manual labor of entering the data into Google Sheets. The first task was now automated!

Connecting Airtable to Contentful

The other time-consuming task was entering the final details of the submissions to Contentful, and I wanted to automate it next. Now that we were using Airtable to manage the data, I re-created the template for the final submission form in Airtable. This enabled us to capture the data in Airtable itself. Whenever a developer submitted this form with the details, it now got saved in Airtable. There was no need to create an automation workflow to handle it!

The data from the final form submission was in Airtable, and not Contentful, yet. To get this data added automatically to Contentful, I created a workflow in Airtable. If you’re using Airtable, you might know that Airtable doesn’t have webhooks (at the time of writing this article). This means that whenever data is created or updated, you can’t trigger external events.

To overcome this, you can either create automation workflows that run at a certain interval of time, or check for new data and then process that data. A better and faster solution is to use automation within Airtable. It allows you to trigger actions when data is entered or updated.

I created a workflow in Airtable to handle the above scenario. Every time a developer submitted the final form, this workflow would get triggered. It is out of the scope of this article to walk you through all the steps of creating the automation workflow. But, below I’m sharing the code snippet that populates Contentful with the data.

Once the form is submitted, the workflow gets triggered. The next step is to create an action that will add the content to Contentful. Airtable doesn’t have an in-built action for Contentful, so there isn’t a no-code or even a low-code solution available just yet. However, it has an action that allows you to run custom JavaScript code.

While working with this action, I learned that you can’t import npm packages. Hence, using the Contentful Management JavaScript SDK was not possible. Fortunately, Contentful has a REST API to interact with the Management API! I wrote the following code in the “Run a Script” action. This script populated the Contentful space with the data from Airtable.

// @ts-ignore
const SPACE_ID=SPACE_ID
const URL = `https://api.contentful.com/spaces/${SPACE_ID}`
const inputConfig = input.config();
const AUTHORLINK = 'authorLink';
const AUTHOR = 'author';
const ENTRY = 'entry';

const linkId = [];
let authorId;

const makeCall = async (endpoint, method, contentType, body) => {
  return fetch(URL+endpoint, {
    method: method,
    headers: {
      Authorization: 'Bearer MANAGEMENT_TOKEN',
      'Content-Type': 'application/vnd.contentful.management.v1+json',
      'X-Contentful-Content-Type': contentType
    },
    body
  })
}

const checkLinkType = (link) => {
  if(link.includes('github')) {
    return 'Github'
  } else if (link.includes('linkedin')) {
    return 'LinkedIn'
  } else if (link.includes('twitter')) {
    return 'Twitter'
  } else if (link.includes('youtube')) {
    return 'YouTube'
  } else {
    return 'Website'
  }
}

const addAuthorLink = async () => {
    const links = inputConfig.authorLink.split(',');
    for (var link of links) {
        let linkType = checkLinkType(link)
        const response = await makeCall('/environments/master/entries', 'POST', AUTHORLINK, JSON.stringify(
            {
                "fields": {
                    "internalTitle": {
                        "en-US": `${inputConfig.authorName}'s ${linkType}`
                },
                "type": {
                    "en-US": `${linkType}`
                },
                "link": {
                    "en-US":`${link}`
                }
            }
        }))
        const res = await response.json();
        linkId.push(await res.sys.id)
    }
    return linkId
}

const addAuthor = async () =>{
    const links = linkId.map(link => {
        return {
            "sys": {
                "type": "Link",
                "linkType": "Entry",
                "id": link
            }
        }
    })

    const response = await makeCall('/environments/master/entries', 'POST', AUTHOR, JSON.stringify({
        "fields":{
            "name": {
                "en-US": `${inputConfig.authorName}`
            },
            "bio":{
                "en-US": `${inputConfig.authorBio}`
            },
            "links": {
                'en-US': links
            }
        }
    }))
    const res = await response.json();
    authorId = await res.sys.id;
}

const addEntry = async() =>{ 
    const response = await makeCall('/environments/master/entries', 'POST', ENTRY, JSON.stringify({
        "fields": {
            "title": {
            "en-US": `${inputConfig.projectTitle}`
            },
            "description": {
            "en-US": `${inputConfig.projectDesc}`
            },
            "link": {
            "en-US": `${inputConfig.projectLink}`
            },
            "author": {
                "en-US": {
                    "sys": {
                    "type": "Link",
                    "linkType": "Entry",
                    "id": authorId
                    }
                }
            },
            "type": {
              "en-US": {
                "sys" : {
                  "type": "Link",
                  "linkType": "Entry",
                  "id": "FIELD_ID"
                }
              }
            }
        }
    }))
    const res = await response.json();
    console.log(await res)
}

(async () => {
    await addAuthorLink()
    await addAuthor()
    await addEntry()
})()

Walking through the code

Let’s break down the code to understand what is happening. The first few lines are defining some variables that we need later in the code. This includes the space ID, URL of the Management API, content type IDs, as well as the input object from Airtable.

We then define a reusable function makeCall that takes the API endpoint, HTTP method, content type, and the body as the parameters. We use this function to call the Management API.

An author of a Developer Showcase submission can share social links. These links are displayed on the respective author page, e.g., one of our top contributors Teemu Tammela. To identify the type of this link, we are using the checkLinkType function. It returns the type that we have configured in Contentful.

Next, we define the addAuthorLink function. This function creates an array of links shared by the author, gets the link type, and adds them to Contentful. It also returns an array of link IDs that get used in the addAuthor function.

The addAuthor function adds all the information about the author, as well as adds references to the links. The final result, a new entry of the author, is now available with references to the author’s social media accounts.

Lastly, the addEntry function adds the project details and references the author. Since the type of project has not been asked in the form, it is hard-coded. The type is manually updated before the entries are published.

The last action in this automation workflow is sending a message on Slack. Since Airtable has an built-in app for Slack, it was straightforward to set it up!

To summarize the above workflow, every time the Airtable form was submitted, the automation would be triggered. It will execute the “Run a script” action, that runs the above code and adds the content to Contentful. Once the content is successfully added, a message is sent on Slack.

All we have to do now is log in to the Contentful space, review the newly created entries, add the missing assets, and publish the changes!

What’s next?

These workflows have saved us a huge amount of time! We don’t have to manually add data, and we can focus more on highlighting the amazing work the community is doing!

The code currently doesn’t handle images, however. We manually have to add them to Contentful. I couldn’t find a good solution to handle images in Airtable, and I am still on the lookout. If you have worked with images in Airtable and have a solution, please let me know!

There are a lot of other tasks that can be automated in the whole process. But my experience with automation has taught me one thing — start small and automate the things you do often. It has helped me not over-engineer a simple solution.

Now that I have more free time, why don’t you share what you’ve created with Contentful? I would love to see it and share it with the community. Also, let me know which Developer Showcase entries you find the most interesting!

What is TypeScript and why should you use it?

Harshil Agrawal — Thu, 01 Sep 2022 10:04:30 +0000

NOTE: This article originally appeared on the Contentful Blog

I’ve been learning and using TypeScript for the past year for various projects, and I have been enjoying it. TypeScript provides a great developer experience, and I believe that it has increased my productivity. I don’t have to manually check for errors every time a change gets made, and the inline documentation helps me ship faster. In this article, I will give you an overview of TypeScript, share some of its features, and help you get started.

Before learning about TypeScript, let’s take a step back and revisit JavaScript. Since the earliest days of the World Wide Web, JavaScript has been used to make websites interactive – handle mouse and keyboard events, validate forms, and so on. With time, the language evolved. You can now use JavaScript to build websites and apps for any platform. It can be used to code both the frontend and backend of your website/app. You can build cross-platform apps using React Native and desktop apps with Electron, and you can even use JavaScript for your next IoT project!

With these extensive use cases, the complexity in the codebase increased. For smaller projects, using JavaScript is still fine. However, for larger projects, it became difficult to debug the code and catch errors.

What is the difference between TypeScript and JavaScript?

TypeScript is a superset of JavaScript. It means that TypeScript provides all the features and functionalities of JavaScript with some added features. TypeScript compiles to JavaScript, which the browser understands. TypeScript provides “type safety” (hence the name!) to JavaScript. It was created by Microsoft and is open source. If you’re interested in contributing or just going through the source code, you can find the repository on GitHub.

To understand type safety, consider an example where you define a variable name. In JavaScript, you would use a similar code as below:

var name = "Harshil"

Since this is a variable name and we haven’t defined its type, this variable can have any value. It doesn’t matter if it’s a string, number, boolean, or object. Hence, the below code will execute without errors:

name = 17

name = false

name = {
first: "Harshi",
last: "Agrawal:
}

Using TypeScript, you can define the type string for the variable name, as below:

var name :string = "Harshil"

If you change its value to any other type, the compiler returns an error. Type safety saves a lot of debugging time and helps in keeping the code consistent.

Features of TypeScript

TypeScript extends JavaScript and improves the developer experience. It enables developers to add type safety to their projects. Moreover, TypeScript provides various other features, like interfaces, type aliases, abstract classes, function overloading, tuple, generics, etc. Explaining all the features is out of the scope of this article. However, I will present two that I find useful.

Interface

You receive an object when you call any Contentful API. This object response contains the necessary data that you need. Similar to the Contentful API, other APIs also send an object as a response.

Interfaces get used to ensure that the object contains the required data with the correct data type. This object can be a response or request body or parameters for a function.

An interface has the following syntax:

interface interfaceName {
    variableOne: type;
    variableTwo: type;
}

Using the above syntax, we can create an interface Profile with the properties name and social.

interface Profile {
    name: string;
    social: string;
}

The above interface can be used as follow:

function hello (params: Profile) {
    return "Find " + params.name + " here " + params.social
}

The above is a simple example of interfaces. There are various other functionalities that interfaces provide. You can set optional properties, extend interfaces to add new properties, and more. To learn more about interfaces, refer to the TypeScript documentation.

Literal Types

Another feature that I find useful is Literal Types. Though, by themselves, they’re not so useful. But one can combine them into unions, which makes the Literal Types useful.

The following example demonstrates the syntax of Literal Types.

let social: "twitter" = "harshil1712"

Here, the variable social has the type “twitter.” However, this isn’t useful on its own.

function greet(message: string, name: "Alice" | "Bob" ){
    //...
}
greet("Hello", "Alice" );
greet("Hey", "Bob");
greet("Hey", "Max"); // Argument of type '"Max"' is not assignable to parameter of type '"Alice" | "Bob"'.

In the above function, the second parameter can only take values that have the type of either “Alice” or “Bob.” This helps us in writing functions that only accept a certain set of known values. They can do much more with Literal Types. Read the official documentation to learn more.

How to use TypeScript?

Now that you have a basic understanding of what TypeScript is, in this section, you will learn how to use TypeScript.

Browsers don’t understand TypeScript. They understand JavaScript code. Hence, the TypeScript code needs to get compiled into JavaScript, and for that, you need the TypeScript compiler.

You can install TypeScript globally using the following npm command. The global installation allows you to run the tsc command anywhere from your terminal.

npm install -g typescript

Once you have installed TypeScript, create an index.ts file and add the following code:

let message:string = "Hello, World!"

function greeting () {
    console.log(message);
}

greeting()

The above code declares a variable message and creates a function that logs the message to the console. To run this code, you have to compile it to JavaScript. Run the following command:

tsc index.ts

You’ll observe that the compiler creates an index.js file with the compiled code.

The TypeScript compiler is flexible and allows you to configure options like the target JavaScript version. At the time of writing this article, the default target is es3.

To configure the compiler options, you can either pass them with the CLI command or create a tsconfig.json. You can learn more about the various configuration options on the TSConfig Reference documentation page.

If you want to use TypeScript in your next Contentful project, we released contentful.js v10 in Beta with enhanced TypeScript support. Check out the changelog and let us know what you think!

Advantages of using TypeScript

TypeScript extends JavaScript, providing a better developer experience. The benefits of using TypeScript over JavaScript include:

Static typing – TypeScript comes with optional static typing and a type inference system, which means that a variable, declared with no type may be inferred by TypeScript based on its value.
Object oriented programming – TypeScript supports object-oriented programming concepts like classes, inheritance, etc.
Compile time checks – JavaScript is an interpreted programming language. There is no compilation involved. Hence, the errors get caught during the runtime. Since TypeScript compiles into JavaScript, errors get reported during the compile time rather than the runtime.
Code editor support – IDEs or code editors like VS Code support autocomplete for a TypeScript codebase. They also provide inline documentation and highlight the errors.
Use existing packages – You might want to use an npm package that is written in JavaScript. Since TypeScript is a superset of JavaScript, you can import and use that package. Moreover, the TypeScript community creates and maintains type definitions for popular packages that can be utilized in your project. You can learn more about it here.

What is the best way to learn TypeScript?

TypeScript comes with tons of features, and learning and implementing them all together might get overwhelming. I started learning TypeScript by refactoring my JavaScript codebase to TypeScript one line at a time. This helped me to migrate my codebase to TypeScript with minimal effort and helped me dive deeper into the concepts.

The TypeScript Handbook is a great place to learn about TypeScript. It explains the concepts well and contains relevant examples. The handbook is also regularly updated with new features.

There are also tutorials available that will help you with migrating your JavaScript project to TypeScript or help you learn about DOM manipulation in TypeScript.

The Contentful community members have also created apps and tools that can help generate type declarations for your content types and sync TypeScript with your content model.

If you’re looking for your next TypeScript project, why don’t you create an app for your Contentful space with App Framework? The boilerplate is available in TypeScript, where you can learn or brush up your TypeScript knowledge. Happy type checking!

How to automatically manage contributions to open-source projects 🏷️

Harshil Agrawal — Fri, 26 Nov 2021 08:05:18 +0000

October is an exciting month, with people across the world looking forward to Halloween or Oktoberfest. But for me, I'm most excited about Hacktoberfest–the month-long celebration of open-source projects. DigitalOcean has been organizing this event for the past eight years with the goal of encouraging the global tech community to support open-source projects.

Hacktoberfest provides a great opportunity on one side for individual developers to apply their skills on real-world projects, and on the other side for organizations to extend their projects with the help of contributors.

However, the popularity of Hacktoberfest also creates spam, unnecessary pull requests, and loads of comments on GitHub issues, which can become overwhelming for the project owners and maintainers.

Our solution to this problem? Automation! In this tutorial, you will learn how to create a no-code workflow that automatically assigns an open GitHub issue to a contributor interested in working on it.

Prerequisites for building the workflow

Workflow for assigning GitHub issues to contributors
1. Trigger the workflow on GitHub events
2. Route the workflow on specific events
3. Handle new GitHub issues
4. Assign the issue
5. Handle new comments on GitHub issues
6. Check if the issue is already assigned
7. Assign an issue to a contributor
8. Add a comment to the issue
What's next?

Workflow for assigning GitHub issues to contributors

Prerequisites for building the workflow

n8n: Sign up for n8n.cloud to quickly get started or use n8n on your own servers. Refer to the installation guide to learn more.
GitHub account: To connect the workflow with your GitHub account, follow the steps mentioned in the documentation.

Workflow for assigning GitHub issues to contributors

The general idea of this workflow is to assign an issue to the contributor who is interested in working on it. There are four scenarios that you need to consider:

A contributor creates an issue and wants to work on it.
A contributor creates a new issue and doesn't want to work on it.
A contributor is interested in working on an issue reported by another contributor and no one got assigned to it.
A contributor is interested in working on an issue opened by another contributor, but someone else has already been assigned to it.

In popular open-source projects, you usually meet all these scenarios. If you're a project maintainer, you know it can become difficult to manage the contributions efficiently, especially during events like Hacktoberfest.

The visual builder that n8n provides helps you classify and handle issues automatically. Let's dive into it!

1. Trigger the workflow on GitHub events

The workflow should run every time someone opens a new issue or comments on an issue. For this, add the GitHub Trigger node and configure the following parameters:

Authentication: If you're using n8n.cloud, I suggest you select the OAuth2 authentication method. This option allows you to connect the node with your GitHub account without the need to create credentials. Otherwise, you can learn how to create the credentials from our documentation.
Repository Owner: Enter your GitHub username.
Repository Name: Enter the name of your repository.
Events: Select issue_comment and issues from the dropdown menu.

Configuration of GitHub Trigger node

Now the workflow will run when a new issue gets created, closed, or edited, or when a comment gets posted, removed, or edited.

Note: If you want to use this workflow for a repository that belongs to an organization, you will have to use the Webhook Trigger node. Refer to the GitHub documentation to learn to add webhooks to your repository.

2. Route the workflow on specific events

The workflow should continue only when a new issue gets created or a new comment gets posted. To identify these events, add a Switch node and set the following parameters:

Data Type: String
Value 1: Use the expression {{$json["body"]["action"]}}

Click on the Add Routing Rules button. For this workflow, you need two different routes, one to handle each event mentioned above.

The first routing rule handles the scenario where a new issue gets created. For this, configure the following parameters:

Operation: Equal
Value 2: opened
Output: 0

The second routing rule will navigate the data to output 1 of the Switch node when a new comment gets posted on an issue. For this, use the following values:

Operation: Equal
Value 2: created
Output: 1

Configuration of Switch node

3. Handle new GitHub issues

Contributors who open a new issue may or may not want to contribute to it. To make sure that you assign the contributor only if they're interested in working on it, add an IF node connected to the output 0 of the Switch node.

Configure the IF node as follow:

Value 1: Add the expression {{$json["body"]["issue"]["body"]}} in the Expression Editor.
Operation: Regex
Regex: /[a,A]ssign[\w*\s*]*me/gm

The above condition checks if the user wants you to assign them the issue or not.

The workflow should also check if the issue has already been assigned to a contributor or not. For this, add another condition in the IF node. This condition should be of the type Number. Set the following parameters for this condition:

Value 1: Use the expression {{$json["body"]["issue"]["assignees"].length}}
Operation: Equal
Value 2: 0

Configuration of IF node for new GitHub issues

4. Assign the issue

The next step is assigning the issue to the interested contributor and label the issue as assigned. To do this, connect a GitHub node to the true output of the IF node and

Configure the parameters of the node as follows:

Authentication: Use the authentication that you used in the GitHub Trigger node
Resource: Issue
Operation: Edit
Repository Owner: Enter your GitHub username or use the following expression: {{$node["Switch"].json["body"]["repository"]["owner"]["login"]}}
Repository Name: Enter the name of the repository you previously used, or use the following expression: {{$node["Switch"].json["body"]["repository"]["name"]}}
Issue Number: Use the expression {{ $json["body"]["issue"]["number"] }}

Click on Choose Option To Add, and select Labels. Similarly, add the Assignees option. Configure these parameters as follow:

Label: Enter assigned or any other label you want to add to the issue.
Assignees: Enter the following expression: {{$json.body.issue["user"]["login"]}}

Configuration of GitHub node for issue assignment

5. Handle new comments on GitHub issues

Your workflow currently handles the following situations:

Assigning the issue to the contributor who opened the issue if the contributor is interested in working on it
Stopping the workflow if the contributor who opened the issue is not interested in working on it.

You now have to design the workflow that handles the other two scenarios. For this, add an IF node connected to output 1 of the Switch node. This node will check if the contributor is interested in working on the issue. Set the following parameters for the IF node:

Value 1: Use the expression {{$json["body"]["comment"]["body"]}}
Operation: Regex
Regex: /[a,A]ssign[\w*\s*]*me/gm

Configuration of IF node for interested contributors

6. Check if the issue is already assigned

If a contributor is interested in working on an issue, the workflow should assign them to the issue, but it should also check if someone has previously been assigned to the issue or not. To check this, connect an IF node to the true output of the previous IF node. Set the IF node as follow:

Value 1: Enter the expression {{$json["body"]["issue"]["assignees"].length}}
Operation: Equal
Value 2: 0

If no one is assigned to the issue, this node returns true, otherwise false.

Configuration of IF node for assigned issues

7. Assign an issue to a contributor

To assign available issues to an interested contributor, connect a GitHub node to the true branch of the previous IF node.

Configure the parameters similarly to the previous GitHub node. In the Assignees fields, use the expression {{$json["body"]["comment"]["user"]["login"]}}. The rest of the parameters should stay the same.

8. Add a comment to the issue

If the issue has already been assigned to a contributor, you should the interested contributor know about it. For this, connect a new GitHub node to the false branch of the IF node. This node will add a comment to the issue.

Set the node parameters as follows:

Authentication: Similar to the previous GitHub node
Resource: Issue
Operation: Create Comment
Repository Owner, Repository Name, Issue Number: Similar to the previous GitHub node
Body: Enter the comment body in this field.

Configuration of GitHub node for commenting on issues

This is the last node in the workflow. Now you only need to activate the workflow by clicking on the toggle in the top right corner of the Editor UI. The active workflow will run automatically in production.

What's next?

In this article, you learned to create a no-code workflow that automatically assigns GitHub issues to interested contributors. This kind of automation will help you and our organization maintain your open-source projects–just in time for Hacktoberfest!

Here's what you can do next:

Build more workflows: There are many other possible automation workflows that could improve your work as a project maintainer and the experience for your contributors. For example, you can build a workflow that checks the progress on an assigned issue to see if the contributor needs help.
Contribute to n8n: You can work on open issues, create nodes, improve our docs, or write a blog post.
Read more tutorials: Learn how to build workflows for other automation use cases, for example a no-code CI/CD pipeline with GitHub and TravisCI.

I'd like to know how you are using automation to manage your open-source projects! Feel free to message me on Twitter or discuss in the community forum 🧡 And if you want to get the latest content on automation, subscribe to our newsletter 💌

This post originally appeared on the n8n.io blog.

Creating triggers for n8n workflows using polling ⏲

Harshil Agrawal — Thu, 14 Jan 2021 12:35:39 +0000

One of the key features of n8n is the ability to use Trigger nodes. Trigger nodes are special nodes that listen for events and then start a workflow. For example, you can build a workflow using the ClickUp Trigger node and a Google Sheets node. Whenever a new task gets created in ClickUp, the workflow would execute, and the data gets added to the Google Sheet. This makes Trigger nodes extremely useful, as you can monitor events across different services using them.

Creating triggers for n8n workflows using polling

Once you start using several of these different Trigger nodes, you wonder what happens when you want to listen for an event from a service that does not have a Trigger node. For example, Google Sheets and Twitter (at the time of writing this tutorial — n8n@0.101.0) don’t have a Trigger node.

In this article, we are going to discuss how you can monitor changes and execute workflows for services that do not support webhooks and don’t have Trigger nodes in n8n.

Monitoring changes in Google Sheets every 45 mins

Introduction to polling

In a conventional n8n Trigger node, the node listens for events using a webhook. In this method, the service sends an update to the Trigger node when an event occurs. While polling works by periodically checking for new data by connecting to the server.

In this process, n8n will connect to the server every X time (every second/minute, etc) and check if there is any new data.

Difference between polling and webhook

Not every platform supports sending updates via a webhook and this is where polling comes to the rescue. Using polling we can check for updates and execute our workflow if data gets added or updated.

How to poll using n8n?

If you break down the polling process, as described in the image above, you realize that it is possible to replicate the same functionality in n8n. The Interval node or the Cron node triggers the workflow periodically to fetch data from a service. We pass this data to the Function node, where all the magic happens.

In n8n, the getWorkflowStaticData() method allows access to the static workflow data. We can save the data directly with the workflow, but this data has to be small. On every execution, the Function node compares the incoming data with the data from the previous execution. If the data got changed, we pass it to the next node in the workflow. We also update the static data with this new data so that the next execution knows what data gets stored in the previous node. If the data did not get changed, you may return a message based on our use-case.

Polling in n8n

Trigger a workflow when new data gets added to your Google Sheets

I wanted to run a workflow every time there was new data added in Google Sheets, so I created a polling workflow. Follow along the steps mentioned below to learn to create a polling workflow.

Prerequisites

Set up n8n

Follow the instructions mentioned in the documentation to install and spin-up an n8n instance on your machine. You can also sign-up for n8n.cloud to get access to our hosted service.

Set up a Google Sheet

Create a Google Sheet like this Google Sheet. We will monitor this sheet for new data that gets added. Feel free to make a copy of my Sheet.

Google Sheet used in this tutorial

We will also need to configure credentials for the Google Sheets node. For this tutorial, we will use the OAuth authentication method. You can learn to configure the OAuth credentials by following the steps mentioned in the documentation.

Set up Mattermost

We will send a message to a channel in a Mattermost team if new data gets added. Create a Mattermost team if you don’t have one already.

You will also have to configure the credentials for the Mattermost node. Follow the instructions mentioned in the documentation to configure the credentials.

Quick Start

If you don’t want to get into the details and have experience building workflows in n8n, you can follow the quick-start instructions below. If something is unclear or you want to learn more about how it works, feel free to dig deeper into the sections that follow.

Access your n8n instance, and copy and paste the workflow from the workflow page. Configure the following nodes:

Google Sheets node

Use the credentials that you configured earlier.
Enter the Sheet ID of your Sheet in the Sheet ID field. If you’re not sure how to find the Sheet ID, refer to the section Google Sheets section below.

Note : If you change a column name in your Google Sheet, make sure to configure the Function node accordingly.

Mattermost node

Use the credentials that you configured earlier.
If you’re not the system administrator, enter the channel ID where you want the app to send the message in the Channel ID field. Otherwise, select the channel from the Channel ID dropdown list. Refer to the Mattermost section below, to learn more about the steps.

Save and execute the workflow!

Note : Activate the workflow to run it in production.

The Workflow

This workflow can be divided into three stages, as it progresses from start to finish:

Read Data
Extract New Data
Communication

Stage 1 — Read Data

Interval node (Execute every 45 mins)

The Interval node triggers the workflow at a regular interval of time. For this tutorial, we want to execute the workflow every 45 minutes.

Click on the ‘ + ’ button on the top right corner and click on the Trigger tab. Select the Interval node from the list to add the node.

Select ‘Minutes’ from the Unit dropdown list and set the value of Interval to 45.

Rename the node’s headline from “Interval” to “Execute every 45 mins” by clicking the name, editing it, and clicking the ✔ (checkmark) to the right of the name. This will finish the configuration of the node and close the parameters window. Select ‘Save As’ from the Workflow menu on the left sidebar. Once you save the workflow, click on the Execute Node button to execute the node.

Google Sheets node (Read data)

The Google Sheets node in n8n allows you to create new sheets and read, lookup, append, delete, and update data from a sheet. Our workflow will read the data from a Google Sheet every 45 minutes.

To add the Google Sheets node, click on the ‘ + ’ button, and select the Google Sheets node from the Regular section. Use the credentials that you configured earlier.

Copy the string of characters located between /d/ and /edit in your spreadsheet URL. This string is the Sheet ID. For example, for the URL https://docs.google.com/spreadsheets/d/1PyCgaglXSCbxVmHuwFbkKDF9e3PW\_iUn8T-iAd\_MYjQ/edit#gid=0 the Sheet ID is 1PyCgaglXSCbxVmHuwFbkKDF9e3PW_iUn8T-iAd_MYjQ. Enter this Sheet ID in the Sheet ID field in the Google Sheet node. Enter the range of the columns in the Range field. The range contains the column references corresponding to those on the spreadsheet. The range tells the Google Sheets node from which columns to read the data.

Rename the node to Read data and click on the Execute Node button. The node will return the data from the Google Sheet.

Stage 2- Extract new data

Function node (Check if new data)

Our workflow reads the data from a Google Sheet and returns all the data. However, we only want the data that was recently added. We will use the Function node to return only the data that was added after the previous execution.

To help you understand this better, let us take a look at an example. Our workflow ran at 1:00 PM and returned the following data:

New data was added to our Google Sheet at 1:20 PM. When your workflow will execute next, we only want this new data. Using the Function node we will return this new data. n8n has a getWorkflowStaticData() method that gives access to the static workflow data. We can save data directly with the workflow, however, this data should be very small. When the workflow execution succeeds, n8n will check automatically if the data has changed and will save it, if necessary.

Click on the ‘ + ’ icon and select the Function node from the list. In the Javascript Code editor, paste the following code snippet.

The above code snippet gets the static workflow data and checks for new items. If new items are found, it is added to an array and gets returned by the node. If the data remains unchanged, an empty array is returned by the node.

Rename the node to Check if new data and click on the Execute Node button.

Note : The static data can not be read and written when we’re building the workflow. Hence, on every execution, the node will return all the data. When the workflow is set to active and triggered by a Trigger node, the node will save the static data and return only the new data that was added (if any).

The following image shows the output returned by the node when the workflow is not active.

Output returned by the Function node when the workflow is not active

The following image shows the output returned by the node when the workflow is active.

Output returned by the Function node when the workflow is active

Stage 3- Communication

Mattermost node (Send message)

If new data was added to the Google Sheet we will send a message to Mattermost along with the new data. We will send a message to the updates channel. But you can select a different channel to send the message.

Click on the ‘ + ’ button and select the Mattermost node. Connect the node to the true branch of the Is new item? node. Use the credentials you configured earlier.

If you are not the system administrator of the Mattermost team, navigate to Mattermost and select the ‘updates’ channel from the left sidebar. Click on the caret next to ‘updates’ and select ‘View Info’ from the dropdown list. Copy and paste the displayed ID in the Channel ID field in the Mattermost node.

Finding channel ID of a Mattermost channel

If you’re the system administrator, select the ‘updates’ channel from the Channel ID dropdown list.

Click on the gears icon next to the Message field and select ‘Add Expression’. Enter the following expression in the Expression Editor.

Rename the node to Send message and click on Execute Node to run the node.

What’s next?

Currently, the Check if new data node in our workflow returns all the items since the static data is not getting saved. Save the workflow and toggle the Active, on the top right, to true. This will set our workflow to active and our workflow will execute every 45 mins. Add new data to the Google Sheets, and after 45 mins (for testing you can set the time to 2 mins!) you will receive a message on Mattermost.

Such polling workflows can be used for various use-cases. If you’re using Google Forms to collect data, and if the form adds the data to a Google Sheet, you can build a workflow that will trigger the workflow whenever there is a new form response.

Another interesting use-case can be for Twitter. You can build a polling workflow that executes every 10 mins. This workflow would fetch Tweets for your search criteria using the Twitter node and return the most recent tweets. At n8n, we use a similar workflow that sends a message to Mattermost with the recent Tweets. You can find the workflow on the workflow page.

A few more examples where polling can help:

Trigger a workflow when an event gets added to your Google Calendar using the Google Calendar node
Trigger a workflow when price changes for a cryptocurrency using the CoinGecko node
Trigger a workflow when new data gets added to your database (MongoDB, Postgres, etc.)

Summary

In this tutorial, we learned how polling can help us overcome a barrier for the nodes that do not have a Trigger node. We can use polling with the nodes that do not have a default Trigger node and build a workflow based to trigger actions when new data is added or updated.

We built a polling workflow that executes every 45 mins and reads data from a Google Sheet. If the data has been updated or new data has been added, the workflow sends a message to Mattermost.

I’d like to know about how you are using the concept of polling and building workflows with n8n! If you run into any issues while following the tutorial, feel free to message me on Twitter or ask for help on ourforum 🧡

This post originally appeared on the n8n.io blog.

Migrating Community Metrics to Orbit using n8n 📈

Harshil Agrawal — Fri, 18 Dec 2020 16:04:36 +0000

It has been more than two years since I have been involved in the community as an organizer. My journey started as a GitHub Campus Expert. My love for privacy and the open internet helped me become a Mozilla Representative, and I am now an Auth0 Ambassador too. This journey is teaching me new skills and pushes me to do better. This is the aim I have for the community as well. Every member should get the opportunity to grow, showcase their skills, and achieve their goals.

Migrating Community Metrics to Orbit using n8n

To know what everyone was up to, I started keeping records of the activities of the community members using Google Sheets. But with an ever-growing community, it became difficult. Every time a community member contributed, I manually added these records to a Google Sheet. The members of the community are very active, and it became difficult to keep up with the pace. Structuring data in Google Sheets for community metrics was also a painful task. The biggest challenge was making sense of these metrics. So I started using Orbit and connected my Google Sheets to it using n8n to transfer data automatically.

What is Orbit?

The Orbit model is a framework for building communities. Orbit makes it easy for community leaders and Developer Relations (DevRel) Leadership to easily keep track of the DevRel metrics and quantify the business impact.

I started at n8n as a Developer Advocate Intern and was excited to learn that we use Orbit for DevRel metrics. I had read about Orbit and was eager to know more about it. I explored Orbit for a while and ended up creating an n8n workflow that moved the metrics from Google Sheets to Orbit.

Like me, if you too manage DevRel metrics in Google Sheets (or Airtable), follow along the article to learn how you can move these metrics to Orbit using n8n.

Prerequisites

Orbit account

You can request access to Orbit by filling a form on their website. Once you have access to Orbit, create a workspace for your community.

Google account

I used Google Sheets to keep a record of the metrics in this spreadsheet. You will need a Google account to create a Google Sheet. Sign in to your Google account and open this sheet. Click on the File and select ‘Make a Copy’ from the dropdown list to copy the sheet in your account.

Note: If you change the name of the columns or the name of the sheet, make sure to make the changes in the n8n workflow accordingly.

n8n

We will connect Google Sheets to Orbit using n8n. Follow the instructions mentioned in the documentation to install and spin-up an n8n instance on your machine. You can also sign-up for n8n.cloud to get access to our hosted service (in beta).

Quickstart

If you don’t want to get into the details and have a bit of experience with n8n, you can follow the quick-start instructions below to get to the endgame. If something is unclear or you want to learn more about how it works, feel free to dig deeper into the sections that follow.

Access your n8n instance, and copy and paste the workflow from the workflow page. Configure the credentials for the following nodes:

Google Sheets node : configure the OAuth credentials and make sure you enter the correct Sheet ID in the Sheet ID field.

Get Members : This Google Sheet node fetches the data from the Members sheet. If your sheet has a different name, modify the Range field accordingly. If you’re using the Google Sheet shared earlier, enter the following range: Members!A:F.
Get Activities : We fetch the activities of our members from the Activities sheet. If you are using a different name for your sheet, modify the Range field accordingly. For the spreadsheet I shared earlier, enter the following range: Activities!A:D.

Orbit node : configure the credentials and select your workspace from the Workspace field.

Save and execute the workflow.

The final workflow in n8n

Moving data from Google Sheets to Orbit automatically

Our workflow will fetch the data of our community members and their activities from a Google Sheet and add the information in our Orbit workspace automatically. The workflow uses the following nodes:

Get Members (Google Sheets node)
Add Members (Orbit node)
Get Activities (Google Sheets node)
Get all members (Orbit node)
Merge
Add Activities (Orbit node)

1. Get Members (Google Sheets node)

We are storing our members’ information like their name, GitHub username, Twitter handle, etc. in a Google Sheet. We will use the Google Sheet node to fetch this information.

The following image shows the Members sheet in my Google Sheet.

Storing members’ information in Google Sheet

Follow the instructions mentioned in the documentation to configure the credentials for the Google Sheets node. Enter your Sheet ID in the Sheet ID field and enter a range in the Range field. If you’re using the Google Sheet shared earlier, enter the following range: Members!A:F.

Rename the node to Get Members and click on Execute Node to run the node.

The following image shows the output of the Get Members node.

Fetching members’ data using Google Sheets node

2. Add Members (Orbit node)

We will use the members’ data that we received from the previous node and pass it on to the Orbit node. To configure the credentials of the Orbit node, follow the instructions mentioned in the documentation.

Select the ‘Upsert’ operation and your workspace in the Orbit node. We are using the GitHub identity to add the members. Select ‘GitHub’ from the Source dropdown list and ‘Username’ from the Search By dropdown list. In the username parameter of the node, use the following expression: {{$json["GitHub"]}}.

In our Google Sheet, we also have information like Location, Tags, Name, and T-shirt size. We will add this information to Orbit as well. You can add this information by selecting them from the Add Field dropdown list. Enter the following expression in the Expression Editor of the respective fields.

Location : {{$json["Location"]}}
Name : {{$json["Name"]}}
Tags to Add : {{$json["Tags']}}
T-Shirt : {{$json["T-Shirt Size"]}}

Rename the node to Add Members and click on Execute Node to run the node.

The following image shows the output of the Add Members node.

Adding members to Orbit

3. Get Activities (Google Sheets node)

Keeping only the data of the community members is not that useful. We also need to keep records of their activities. This record helps us understand the contributions the community members make, the type of content they are involved with, and other critical insights.

The following image shows the Activities sheet in my Google Sheet.

Storing members’ activities in Google Sheet

We will get the records of the activities of our community members from the Google sheet and add them to Orbit.

Select the credentials that we used in the Get Members node. Our Google Sheet uses the members’ GitHub username to associate them with their activities. We will use the ‘Lookup’ operation to get this information. Enter the following in the expression editor for the Sheet ID parameter: {{$node["Get Members"].parameter["sheetId"]}}. Enter the range for our Google Sheet in the Range field. If you’re using the Google Sheet shared earlier, enter the following range: Activities!A:D.

Enter ‘GitHub Username’ in the Lookup Column field. If you are using a different column name, enter that instead.

In the Lookup Value field, we pass the GitHub username of all our members that we got from the Get Members node. Enter the following expression in the Lookup Value field: {{$node["Get Members"].json["GitHub"]}}. Toggle Return All Match to true. This will check for the activities of all the members and return all their activities if it exists.

Rename the node to Get Activities and click on Execute Node to run the node.

The following image shows the output from the Get Activities node.

Getting members’ activities using the Google Sheet node

4. Get all members (Orbit node)

To add the activities that we got from the previous node, we need the ID of the members that were generated by Orbit. This node will get the ID of the members along with other information.

Create a new Orbit node and select the credentials that we used in the Add Members node. Select ‘Get All’ from the Operation dropdown list. Select your workspace and toggle Return All to true.

Rename the node to Get all members and click on Execute Node to run the node.

NOTE: Depending on the amount of data we have, the Orbit node might take some time to add the new members to the workspace.

The following image shows the output from the Get all members node.

Getting all members using the Orbit node

5. Merge information Google Sheets and Orbit

We now have all the activities of our members from Google Sheet and their member ID from Orbit. We need to merge this information to map the activities to their respective member IDs.

We are using the Merge node to merge this information. Connect one input of the node with the Get Activities node and the other input with the Get all members node.

Select ‘Merge By Key’ from the Mode dropdown list. This option will merge the information using the GitHub username as the key. Enter ‘GitHub Username’ in the Property Input 1 field and ‘attributes.slug’ in the Property Input 2 field.

Click on Execute Node to run the node.

The following image shows the output from the Merge node.

Merging data from Google Sheets and Orbit

6. Add Activities (Orbit node)

The Merge node returns all the necessary data that we need. Using the Add Activities node, we will add the activities of our community members to Orbit.

In our new Orbit node, select the credentials that we used for the Get all members node. Select ‘Activity’ from the Resource dropdown list and ‘Create’ from the Operation dropdown list.

In the expression editor for the Member ID field, enter the following expression: {{$json["id"]}}. Enter the following expression in the expression editor of the Title field: {{$json["Title"]}}.

We will also add a description and a link (if they exist) for the activities. Add the Description and Link fields from the Add Field dropdown list. Enter the following expression in the Expression Editor of the respective fields.

Description : {{$json["Description"}}
Link : {{$json["Activity Link"]}}

Rename the node to Add Activities and click on Execute Node to run the node.

The following image shows the output from the Add Activities node.

Adding activities using the Orbit node

What’s next?

The current workflow shows how we can migrate our data from Google Sheet to Orbit. But we might be using Airtable or a CRM tool to manage these records. We can migrate these records to Orbit using n8n in less than 10 mins.

We can build another workflow using the Cron node and the Orbit node to get the information about members with the highest activity in a month. Appreciate their contributions in the community using the Mattermost node or the Slack node (or whatever your community uses), and tweet about their work using the Twitter node.

I previously wrote an article on how you can use the Slash command in Slack and integrate it with n8n to get community members’ information and give a shout-out to them. We can combine these workflows. Use the Orbit node to get the data (email, address, t-shirt size) of the members, the Shopify node to place an order for swags. If you use Printfection, you can use the HTTP Request node to place the order on Printfection. Let us recognize the contributions of the community!

Summary

Community metrics are yet not well defined and is a challenge for a lot of us. But the Orbit model streamlines these metrics and gives us a more efficient output. With this workflow, we now have our community metrics in our Orbit workspace. Orbit displays the data more sensibly and helps us understand the metrics. We can now make sense of these metrics and plan future activities for our community more efficiently.

I’d love to hear about how you extend the workflow using n8n and manage your communities! If you run into any issues while following the tutorial, feel free to reach out to me on Twitter or ask for help on our forum 🧡

This post originally appeared on the n8n.io blog.

Building an expense tracking app in 10 minutes 📱

Harshil Agrawal — Fri, 11 Dec 2020 07:42:06 +0000

I tried various ways in the past to keep a record of my expenses. It started with maintaining a record in a book. But this wasn’t an ideal solution and involved manual work. I tried using everyone’s favorite — spreadsheets, but it failed me. I still had to manually enter the information of my expenses. I also tried various apps, but none of them catered to my needs. They all lacked the option to customize the way I wanted to upload the information.

I built an app!

I came across the article Automatically Adding Expense Receipts to Google Sheets with Telegram, Mindee, Twilio, and n8n 🧾 that showed how to build a Telegram bot to track expenses. This article inspired me to create an app for managing my expenditures. But creating a mobile app would mean designing the user interface of the app and transforming the design into a functional app. This was going to be a long process, and I was looking for a less complicated and faster solution, and that is when I learnt about Bravo Studio. With Bravo Studio, you can convert your Figma designs into a mobile app. I had never used a no-code platform to build a mobile app, and Bravo Studio piqued my interest.

I ended up creating an app that captures the image of a receipt and stores the information parsed from it in Airtable. I am now storing my data in my Airtable account, and I can use it the way I want. I would also have the flexibility to add more features that I might need in the future.

If you’re struggling with managing expenses like me, and if you want to build your custom app, follow along with this article.

In this article, we will learn to build an expense tracker app using no-code tools and platforms. We will start by designing our application in Figma and converting it into an app using Bravo Studio. We will use Typeform to collect the images of the receipts, Mindee to extract the information from the receipts, and Airtable to store all the information. We will use n8n to connect these different services and make the app functional.

Prerequisites

Figma

Figma is a prototyping tool. We will use Figma to design the user interface of our application. If you don’t have an account on Figma, go ahead and create one.

Bravo Studio

Bravo Studio is a no-code tool to build native applications. We will use Bravo Studio to transform our Figma design into a mobile app. Create an account on Bravo Studio if you don’t have one. To test our application on a real device we will use Bravo Vision.

Typeform

Our application needs an input field that will allow the users to upload images, as well as trigger our n8n workflow. We will use Typeform to handle that. Create an account on Typeform and make a form with the question type ‘File Upload’.

Note: You need to have a premium account on Typefrom to access the ‘File Upload’ question type. If you don’t have a premium account, use the code n8nxTypeform_2021 to get free access for a month.

Mindee

Once we have the image of the receipt, we need a service to extract the information from it. We will use Mindee to extract information like merchant name, amount, date of purchase, etc. from the image. You will need an account on Mindee to access the Expense Receipts API.

Airtable

Our app will use Airtable as the database to store and retrieve information from. We will need an Airtable account to create a base and connect it with Bravo Studio. Sign in to your Airtable account and open this base. Click on the Copy base button on the top right corner to copy the base in your account.

Note: If you change the name of the columns, or the name of the Table, make sure to make the changes in the n8n workflow accordingly.

n8n

Our application is using different services like Typeform, Mindee and Airtable. n8n will connect these services together and make our app functional. Follow the instructions mentioned in the documentation to install and spin-up an n8n instance on your machine. You can also sign-up for n8n.cloud to get early access to our hosted service.

This workflow was built in n8n version 0.101.0.

Quickstart

We often tend to jump to the results before committing to the steps of the experiment if we are aware of the subject. If you already know how to work with Bravo Studio and n8n, you can follow the quick-start instructions below to get to the endgame. If something is unclear or you want to learn more about how it works, feel free to dig deeper into the sections that follow.

Typeform

Create a form in Typeform with the question type ‘File Upload’.
Enter Upload Receipt in the text box where it indicates ‘Type question here…’.
Publish the Typeform and copy the link under the ‘SHARE’ tab.

Figma

To duplicate this Figma Design open it in a new tab.
Click on the down chevron next to Expense Tracker and select ‘Duplicate to your Drafts’ from your dropdown list.
Replace ‘TYPEFORM-LINK’ in Add Receipts Data > Typeform Container > Rectangle[component:web-view:TYPEFORM-LINK] with your form’s link.

n8n

Install n8n, and copy and paste the workflow from the workflow page. Configure the credentials for the following nodes:

Typeform Trigger node (Get Receipt): configure Access Token credentials and make sure to select your form from the Form dropdown list.
Mindee node (Extract Information): configure credentials for the Expense Receipts API.
Airtable node (Store Information): configure credentials and enter the application id and the table name in the Base ID and Table field respectively.

Save the workflow and set it to active.

Bravo Studio

Create an app in Bravo Studio by importing the Figma design from step 2.
Add Airtable as a data library in Bravo Studio. You can follow the instructions mentioned in the official documentation.
Bind the data from your Airtable base to your Bravo Studio app. You can learn how to do that from the documentation of Bravo Studio.

NOTE : If you were successfully able to follow the steps mentioned above, you can jump directly to the Testing the Application section before going through the conceptual sections.

Creating the User Interface

To add the expense in our app, a user will upload an image of the receipt. We will use a Typeform form to get the image of the receipt from the user. Create a form in Typeform with the question type ‘File Upload’. Publish the Typeform and copy the link under the ‘SHARE’ tab. We will use this link in Figma to embed the form.

We want to create an app with our custom design and functionality. We will use Figma to design the prototype of the app. Below is the screenshot of the app’s design created in Figma.

Creating the app’s design in Figma

Our app will have three screens:

A welcome screen which gives the user an option to either add a new receipt or view the stored receipts.
An ‘Add Receipt Data’ screen that will allow the user to upload new receipts using the form we created in Typeform.
A ‘Review Added Receipts’ screen to view all the receipts added by the user.

The design that we create in Figma should be compatible with Bravo Studio. To design a Bravo Studio app in Figma there are a few things to consider:

Containerize your design: To make our Figma app design adaptable in Bravo Studio, wrap the layers in containers. These containers are frames that divide an app screen into separate blocks based on the intended behavior of the design. In our app, we will need to create the following containers:

Main Container : The Welcome Screen contains a container that consists of all the layers and the ‘App Buttons’ container.

Creating the Main Container

App Buttons : This container consists of the ‘Add new receipt’ and ‘My receipts’ button on the Welcome Screen.

Creating the App Buttons container

Top navigation : We need a container that helps us navigate back to the welcome screen. The Top navigation container will contain an image for the back button and the title of the screen. We will add this container to the Add Receipt Data screen and the Review Added Receipts screen.

Creating the Top navigation container

Typeform Container : The Typeform Container contains a rectangle layer that will render the Typeform. We will add this container to the ‘Add new receipt’ screen.

Creating the Typeform container

*List: This container consists of the layers that will render the receipts information such as the merchant name, amount, date, time, category, and image of the receipt. We will add this container to the ‘My receipts’ screen.

Creating the *List container

Use Bravo Tags: A Bravo Tag is a text string that converts the layer into a mobile component. For each container and layer, you want to convert to a mobile component, use the appropriate Bravo Tags. In our design, we will use the [component:web-view:URL] tag to embed the Typeform in the Typeform Container. Replace ‘URL’ with the URL of the Typeform you created earlier.

Note: The name of the List container and the layers inside the container starts with an asterisk (*). Bravo Studio recognizes such containers and layers as a list.

After designing the application in Figma, the next step is to use this design in Bravo Studio to create a native application. In Bravo Studio, click on the Import Figma File button and copy and paste the link of your Figma design in the input field to create a new project.

Congratulations! The user-interface of your application is ready.

Connecting with Airtable

In Bravo Studio we can use a custom API or Airtable to connect our application with a database. The application we built uses Airtable as the database. Hence, we will connect Airtable with our application.

In Bravo Studio, add a new data collection by clicking the ‘+ New Collection’ button on the Data Library page. Select Airtable, and follow the instructions as shown in the video, in the Airtable API Wizard, enter the base URL and your Airtable API Key. You can learn more about Using the Airtable API Wizard from the documentation here.

Click on Advanced view and make a GET request for ‘Expenses — List’. Select ‘All’ from the data.records[] dropdown list in the Response Data section.

Navigate to the ‘Projects’ page and select the app that we created. We will bind the data from the Airtable base with the respective components of the ‘Review Added Receipts’ screen. Select the ‘Review Added Receipts’ screen and select the ‘Expenses Tracker’ Airtable base. Select ‘GET Expenses — List’ in the Select Request section of Data Binding. Select the *List component and select Records from the dropdown list below Get Expenses — List. Expand the *List component and map each element to their corresponding field. You can learn more about this from the documentation.

The video below shows the steps to bind the data to components.

Building the workflow

Creating a backend for applications can get complicated when it comes to connecting different services together. You have to write functions to make API calls to each service, and pass information from one service to another in the proper format. But n8n makes it easy to create the backend and stitch different services together. You also get a visual representation that helps you in designing the application logic.

In n8n, you will use the following nodes to build the backend logic:

Typeform Trigger node (Get Receipt)
HTTP Request node (Get Image)
Mindee node (Extract Information)
Set node (Set Information)
Airtable node (Store Information)

Our workflow will look like the image below.

Completed workflow in n8n

1. Typeform Trigger node (Get Receipt)

The Typeform Trigger node will trigger the workflow whenever the user submits a new receipt. Add the Typeform Trigger node and configure the credentials by following the instructions in the documentation here.

Select the form that you created for the application from the Form dropdown list.

Rename the node as Get Receipt, and save the workflow.

Click on the Execute Node button to execute the node. Upload an image of a receipt using the Typeform. You will notice that the Typeform Trigger node triggers the workflow when the form is submitted.

2. HTTP Request node (Get Image)

The HTTP Request node is used to make an HTTP request to APIs and websites. It can return data in JSON, String as well as Binary format. Add an HTTP Request node in n8n that will make a GET request to fetch the image we uploaded using the Typeform. In the URL parameter of the node, add the following expression: {{$node["Get Receipt"].json["Upload receipt"]}}. This expression will get the URL of the image that we uploaded using Typeform.

Select ‘File’ from the Response Format dropdown list and rename the node to Get Image. Click on Execute Node to run the node. In the output, you will notice that the node returns the image of the receipt.

3. Mindee node (Extract Information)

The Mindee API enables to extract information from an image and transform it into usable data. We will use the Mindee node in n8n to extract data from an image of a receipt. The node will extract the merchant name, the amount, the date and time the expense was incurred, and its category.

Add the Mindee node in the n8n workflow, and configure the credentials as mentioned in the documentation.

Rename the node to Extract Information, and click on Execute Node to run the node. You will notice that the node extracts the information from the image and transforms it into usable data that can be added to Airtable.

4. Set node (Set Information)

The Set node allows us to set the workflow data. We will reference the data from the Mindee node and the Typeform Trigger node in the Set node and set the parameters.

Add the Set node in your n8n workflow and add the parameters with the following properties.

Amount : The type of this field should be Number and it’s value should be {{$node["Extract Information"].json["total"]}}
Merchant : The type of this field should be String and it’s value should be {{$node["Extract Information"].json["merchant"]}}
Date : The type of this field should be String and it’s value should be {{$node["Extract Information"].json["date"]}}
Time : The type of this field should be String and it’s value should be {{$node["Extract Information"].json["time"]}}
Receipt URL : The type of this field should be String and it’s value should be {{$node["Get Receipt"].json["Upload receipt"]}}
Category : The type of this field should be String and it’s value should be {{$node["Extract Information"].json["category"]}}

Note: The value in the Name field should be the same as the column name of your Airtable base.

Toggle the Keep Only Set to true. This ensures that only the data that we set in this node gets passed on to the next nodes in the workflow. Click on the Execute Node button to run the node.

5. Airtable node (Store Information)

Airtable is a spreadsheet-database hybrid, with the features of a database but applied to a spreadsheet. The Bravo Studio app will get the data from the Airtable base to display it to the user. But before connecting the app with Airtable, in the front-end, we need to connect Airtable with your backend.

The n8n workflow will store the data extracted by the Mindee node and the URL of the image in Airtable. Create a base in Airtable similar to this template base if you haven’t already created one.

In n8n, add the Airtable node and configure the credentials following the instructions mentioned here. Select ‘Append’ from the Operation dropdown list. To get the Application ID, go to https://airtable.com/api and select the base. Copy and paste the ID in the Base ID field in n8n. Enter the name of your base in the Table field.

Click on Execute Node to run the node. On successful execution, you will notice that a new row gets added to your Airtable base.

Testing the application

Congratulations! You have successfully built the application. Now let us test our application and see how it would work in the real world.

In n8n, on the top right corner, toggle Active to true. This will set our workflow to active and execute the workflow every time a new receipt is submitted to Typeform.

Open the Bravo Vision app on your device and select the Expense Tracker app. Click on the Add new receipt button and submit an image of the receipt.

If you don’t have a receipt at hand now, feel free to use the following image of the receipt for testing.

A receipt for testing your workflow

You can see the new receipt and the information on the ‘My Receipts’ screen.

My Receipts page after adding the receipt

What’s next?

You can extend the workflow and send an email every time you add a new expense, using either the Send Email node or the Gmail node. You can also use the Twilio node or the Vonage node to send an SMS when a new expense gets added.

You can also create a new workflow that will send you a weekly or monthly notification about the expenses you made during that period. This workflow can be built using the Cron node to trigger the workflow weekly or monthly, the Airtable node to read the data, and the Function node to calculate the sum of the expenses. To send a push notification, you can use the Pushover node.

Summary

In this article, you learned how to build an application. You learned to design an app in Figma that is compatible with Bravo Studio. You also created the front-end of the app using Bravo Studio. You stitched different services together using n8n to get the desired output. Lastly, you learned how to bind data to your app in Bravo Studio.

I plan to add more features to the app that will help me build a healthy habit of keeping track of my expenses and help me manage them.

I’d love to hear about how you extend the app using n8n! If you run into any issues while following the tutorial, feel free to me on Twitter or ask for help on our forum 🧡

DEV Community: Harshil Agrawal

Could Cloudflare Computer Simplify PromptMotion?

Why PromptMotion Needs So Much Infrastructure

Durable files need custom wrappers

Rendering duplicates the filesystem

Previewing is a third file path

The Abstraction Cloudflare Computer Adds

How Computer Maps to My Problems

One durable filesystem instead of file-copying helpers

Built-in tools replace generic agent glue

The render container sees the same workspace

Streams can replace base64 transfers

R2 mounts unify file access, not HTTP serving

What Computer Does Not Solve

The Migration I Would Try

1. Move source files first

2. Run one render through computerd

3. Point the preview server at the Workspace

What About Live Render Progress?

Where I Am Cautious

The Outcome I Want

How I Run the Pi Coding Agent on Cloudflare

What I Wanted to Preserve from Pi

The Architecture

One Durable Object per Pi Session

Preserving Pi's Session Tree in SQLite

Giving Pi a Durable Filesystem

But What About a Shell?

Running Pi's Model Loop Through AI Gateway

Getting the Stream Back to the Browser

Searching Across Sessions

Learned Memory

Building an App Without a Build Process

Previewing Generated Code with Dynamic Workers

Versioning and Deploying Generated Applications

Why Each Cloudflare Primitive Is Here

Current Trade-offs

Run Pi on Cloudflare

What I Learned

References

Making My Astro Site Agent-Ready: An Honest Audit of isitagentready.com

The Audit Results

The Decision Framework

What my agent implemented

1. Link Headers on the Homepage (RFC 8288)

2. Content Signals in robots.txt

3. Markdown Content Negotiation

A Wrinkle: Prerendering vs. Cost

Extending Markdown Negotiation to Every Other Page

What I Skipped (and Why)

API Catalog (RFC 9727)

OAuth/OIDC Discovery & Protected Resource Metadata

MCP Server Card, Agent Skills, WebMCP

The Final Scan

What I Learned

Summary

References

Controlling Elgato Key Lights with Voice Agent

What I built

Prerequisites

The Voice SDK: withVoice

The server

PCM16 TTS: Why I needed a custom class

Chunking audio for the ESP32

The WebSocket protocol

Client → Server

Server → Client

The ESP32 client

Gotcha: mic reinit after speaker playback

Gotcha: WebSocket Host header

Gotcha: Durable Object path routing

Greeting on call start

Adding smart home control: Elgato Air Light via Mesh

The challenge

The solution: Cloudflare Mesh + VPC Networks

Why Cloudflare Mesh and not Cloudflare Tunnel?

Setting up the Mesh node

The Elgato REST API

Adding tool calling to the voice agent

Wrangler config

The Voice SDK: `withVoice`

Error 1: `Cannot find package 'tailwindcss'`

Error 2: `LegacyContentConfigError`

Error 3: `Property 'runtime' does not exist on type 'Locals'`

Error 4: `astro-expressive-code` peer dependency mismatch

Error 5: `Buffer<ArrayBufferLike>' is not assignable to parameter of type 'BodyInit'`