Niapya Blog

Migrate to remix@3

Wed, 29 Jul 2026 21:24:00 GMT

We migrated our blog to the beta Remix v3, which abandons React in favor of a TypeScript‑based UI model and an explicit “islands” architecture where only components marked with clientEntry become client‑side JavaScript. By leveraging Remix’s built‑in TypeScript loader, a lazy asset server, Twind for on‑the‑fly Tailwind CSS, and Satori‑generated SVG/PNG captchas, we achieved a fully server‑rendered site with no build step, no default client scripts, and native Web‑API‑driven interactions. Although the ecosystem and documentation are still maturing, the migration demonstrates that Remix v3 can deliver type‑safe, componentized, and dynamically rich web applications while keeping the server, browser, and open standards at the core.

Recently, we migrated this blog to remix@3.

Remix v3 is not a routine upgrade from Remix v2; it drops React and builds a full‑stack framework on its own. It is still in Beta, and both the API and ecosystem are young.

I decided to use Remix v3 at such an early stage because I really like it—it returns to the essence of Web APIs.

A Glimpse of Remix v3

The most striking thing about Remix v3 is that it doesn’t use React; instead it rewrites a TypeScript UI framework.

Remix components are not React components, and there are no Hooks. A component receives a handle and then returns a true render function.

function Greeting(handle: Handle<{ name: string }>) {
  return () => <p>Hello, {handle.props.name}</p>;
}

State updates, events, server‑side rendering, and hydration all revolve around this model. Pages render HTML on the server by default; only components explicitly marked with clientEntry() become JavaScript boundaries in the browser. The server leaves markers for these boundaries and serializes their props, and the browser’s run() lazily loads the corresponding modules and hydrates them. For example, a counter can be explicitly declared as a client entry:

export const Counter = clientEntry(
  import.meta.url,
  function Counter(handle: Handle<{ initialCount: number }>) {
    let count = handle.props.initialCount;

    return () => (
      <button
        mix={on("click", () => {
          count++;
          handle.update();
        })}
      >
        {count}
      </button>
    );
  },
);

Here import.meta.url is the server‑side source file path, e.g. file:///app/components/counter.tsx. When SSR encounters this component it calls resolveClientEntry(), passing the source path to the asset server, which rewrites it to a URL the browser can fetch:

const stream = renderToStream(<App />, {
  async resolveClientEntry(entryId, component) {
    return {
      href: await assetServer.getHref(entryId),
      exportName: component.name,
    };
  },
});

The server still outputs the button’s HTML first, but it marks the region of DOM it owns with comments, roughly like this:

<!--rmx:h:counter-1-->
<button>0</button>
<!--/rmx:h-->

<script type="application/json" id="rmx-data">
{
  "c": {
    "counter-1": {
      "moduleUrl": "/assets/app/components/counter.tsx",
      "exportName": "Counter",
      "props": { "initialCount": 0 }
    }
  }
}
</script>

The HTML above is simplified for protocol illustration, but the essential structure comes from the Remix runtime: a pair of rmx:h comments delimit the hydration area, and rmx-data stores the module URL, export name, and serializable props. Even before any JavaScript is downloaded, the user can see the server‑rendered button.

Then the browser entry runs run(). The runtime reads rmx-data, walks the comment markers, and hands each moduleUrl + exportName to loadModule():

const app = run({
  async loadModule(moduleUrl, exportName) {
    const module = await import(moduleUrl);
    return module[exportName];
  },
});

await app.ready();

Only now does a real network request happen: when the browser executes import("/assets/app/components/counter.tsx"), the asset server reads the TSX from disk, parses and transforms it with Oxc, and rewrites the file’s imports to public URLs.

The browser receives a standard ESM file; loadModule() extracts the Counter export, the runtime reconstructs the virtual node with the serialized props, hydrates the existing DOM between the two comments, and attaches the click listener. Loading the same module again is cached, so ten Counters on the page do not trigger ten requests.

It may start to feel complicated, but this is a truly explicit Islands architecture: instead of turning the whole component tree into a client‑side app and then trying to trim JavaScript, there are no client components by default—only the parts that truly need interaction become islands.

Moreover, in the AI era, Remix writes everything. remix/data-schema provides Zod‑like, Valibot‑like schemas, checks, transformations, and parseSafe(). It also supports Standard Schema, which makes us admire Remix’s boldness.

The simplest object validation looks like other schema libraries; the schema itself describes both runtime constraints and output types:

import * as s from "remix/data-schema";
import { email, minLength } from "remix/data-schema/checks";

const User = s.object({
  name: s.string().pipe(minLength(2)),
  email: s.string().pipe(email()),
  role: s.defaulted(s.string(), "reader"),
});

const user = s.parse(User, {
  name: "Ada",
  email: "ada@example.com",
});

Finally, it follows Standard Schema. s.parse() and s.parseSafe() accept not only Remix’s own schemas but also Zod, Valibot, or ArkType schemas.

Beyond that, Remix offers a suite of coordinated packages for routing, middleware, sessions, authentication, and data tables. All capabilities are imported from remix/<subpath>, making the boundaries very clear.

Why should we have a build step?

Another radical choice in Remix v3 is not treating a build step as a prerequisite for running the app.

Remix ships its own TypeScript/JSX loader that can be used in Node.js via --import flags.

node --import remix/node-tsx ./server.ts

remix/node-tsx transforms .ts and .tsx files before Node executes them.

Someone might ask, “what about the browser?” The browser obviously can’t run TypeScript code, so Remix’s solution is clever.

When client‑side JavaScript is needed, Remix’s asset server can serve modules directly from source, rewrite imports, and generate preload links and fingerprinted URLs. For example, you can map the source directory to a public address under /assets:

import { createAssetServer } from "remix/assets";

const assetServer = createAssetServer({
  rootDir: process.cwd(),
  basePath: "/assets",
  fileMap: {
    "/app/*path": "app/*path",
    "/npm/*path": "node_modules/*path",
  },
  allow: ["app/assets/**", "node_modules/**"],
  deny: ["app/**/*.server.*"],
});

router.get("/assets/*", ({ request }) => assetServer.fetch(request));

When the browser requests a TSX entry, the asset server transpiles that module and rewrites its imports to URLs the browser can fetch.

allow and deny together form a security boundary that prevents accidental exposure of server‑only files. The server still compiles, but there is no need to run a build ahead of time or generate and deploy a dist directory.

Internally it composes Oxc parser, transformer, minifier, and resolver, then uses es-module-lexer to rewrite source, and Lightning CSS for styles.

A pleasant surprise is that fileMap can also bring node_modules/ into the same dependency graph:

fileMap: {
  "/app/*path": "app/*path",
  "/npm/*path": "node_modules/*path",
}

Suppose Counter imports on from "remix/ui". The asset server resolves that bare specifier, finds the real package export inside node_modules, and rewrites it to something like /assets/npm/remix/ui/index.js. When the browser requests that URL, the asset server reads, processes, and returns it; its dependencies are further resolved in the same way. The entire node_modules is not pre‑bundled but loaded on demand following the ESM dependency graph, just like source files.

getPreloads() can walk this graph ahead of time and turn the modules that will be requested into <link rel="modulepreload"> tags or Link headers:

const preloads = await assetServer.getPreloads([
  "app/components/counter.tsx",
]);
// /assets/app/components/counter.tsx
// /assets/npm/remix/ui/index.js
// …and the modules they depend on

That’s the amazing part: it retains the browser’s native ESM request model while still performing TypeScript transformation, package resolution, preload generation, source‑map handling, minification, and fingerprinting—without requiring us to emit a bundle first.

Preparations

In fact, I believe the native Web API is already powerful enough for us to rely on it to implement everything. With that in mind, I set a few goals for the new homepage:

No client‑side JavaScript participation
The blog is inherently lightweight; every page can be static, with no client JavaScript involved, at most using a form for comments, which can be solved entirely with HTML.
No build process
Remix’s dev and start scripts do not involve a build step, so we don’t want to add one either. I want to push directly to the remote repo and be able to run immediately.
Implement all blog functionality
A blog should have stats, comments, captchas, etc., a good UI/UX, a table of contents, and nice interaction effects.

When an app no longer depends on a traditional bundler, tasks that were previously handled automatically by the build system need to be redesigned. To preserve Tailwind’s developer experience, streaming SSR, and dynamic images, we performed a few extra steps.

Generating Tailwind CSS for SSR with Twind

This project uses Twind’s Tailwind preset rather than running the Tailwind CLI to scan source files and produce a static CSS file. Twind can read the class attributes that appear in the final HTML and generate the necessary styles on demand, which fits a server‑side app without a build step.

The challenge is that Remix returns a stream, not a complete string. To handle that we wrote a twind() middleware:

export function twind(): Middleware {
  return async ({ request }, next) => {
    const response = await next();

    /* ... */

    return new Response(
      response.body.pipeThrough(new TwindStream(), {
        signal: request.signal,
      }),
      { status: response.status },
    );
  };
}

It first waits for downstream SSR to finish, processes only text/html responses, and then pipes response.body through a TransformStream. The HTML flowing through the stream is given to Twind’s consume() for scanning; the CSS generated from the first document fragment is injected into <head>.

If a later Remix Frame stream emits new classes, the middleware compares the previous and current style sets and writes only the incremental patch back to the page. The key is keeping an independent Twind snapshot for each chunk of the stream:

const restoreGlobalState = tw.snapshot();
restoreCurrentState();

let html = consume(buffer, tw);
const nextStyle = stringify(tw.target);

restoreCurrentState = tw.snapshot();
restoreGlobalState();

if (lastStyle === null) {
  html = html.replace(
    "</head>",
    `<style data-twind>${nextStyle}</style></head>`,
  );
} else {
  const styleDiff = getStyleDiff(lastStyle, nextStyle);
  if (styleDiff.length) html = createStylePatch(styleDiff) + html;
}

Saving and restoring the global snapshot is crucial because Twind’s instance is process‑wide, while SSR requests happen concurrently. Each response must see only its own classes and must not mix rules generated for another request. The first flush puts the complete stylesheet into <head>; subsequent flushes only send insertion points and new CSS, which a tiny inline script patches into the same <style> element.

This does not break streaming rendering; the browser still receives the document shell as early as possible, and later fragments receive the correct styles.

Meanwhile we can continue using Tailwind‑style atomic classes, Typography, Autoprefixer, theme tokens, and dark mode without any extra build commands.

Satori‑Generated Captchas

Satori is Vercel’s open‑source JSX/object‑to‑SVG renderer. It isn’t a browser screenshot tool; it runs on the server, directly computing an SVG from layout objects and font data. We then rasterize the SVG to PNG with Resvg.

The most straightforward use case is dynamic Open Graph images. Our site first validates the title length in the URL with remix/data-schema, feeds both Latin and Chinese fonts explicitly to Satori, and finally returns a PNG:

const parsed = s.parseSafe(
  ogImageQuerySchema,
  new URL(request.url).searchParams,
);
const title = parsed.success ? parsed.value.title : "";

const svg = await satori(createCard(lang, title), {
  width: 1200,
  height: 630,
  fonts: [
    {
      data: RENDER_FONT_DATA.instrumentSerif,
      name: "Instrument Serif",
      weight: 400,
    },
    {
      data: RENDER_FONT_DATA.notoSerifSc,
      name: "Noto Serif SC",
      weight: 400,
    },
  ],
});

const png = new Resvg(svg).render().asPng();

const body = png.buffer.slice(
  png.byteOffset,
  png.byteOffset + png.byteLength,
) as ArrayBuffer;

return new Response(body, {
  headers: {
    "Cache-Control": "public, max-age=3600, stale-while-revalidate=86400",
    "Content-Type": "image/png",
    Vary: "Accept-Language",
  },
});

Simple, right? We’ve implemented OG images for the homepage and each blog post, but the more interesting part is the comment captcha.

The server randomly generates a set of shapes with different colors and chooses one as the target. Satori and Resvg render the challenge as an image, while the target position and a one‑time token are stored in Deno KV. The page uses native HTML:

<input type="image" name="captcha" src="..." />

When the user clicks the image, the browser submits captcha.x and captcha.y together with the normal form—this is the behavior defined by the native <input type="image"> element.

The server only needs to validate the token and coordinates with remix/data-schema/form-data, then check whether the click landed near the target shape. The challenge has a short TTL and is atomically deleted after submission, so the same answer cannot be reused.

What’s truly interesting isn’t the captcha algorithm but the implementation approach: Satori generates the challenge, Deno KV holds short‑lived state, the native image input collects click coordinates, and a regular HTTP form submits everything. No event listeners, fetch(), or any client‑side JavaScript are involved.

Migration Work

With the goals defined, the implementation path was clear: use SSR everywhere.

TypeScript / TSX + Markdown
        ↓
    runtime
        ↓
 Remix streaming SSR
        ↓
Twind injects CSS + Satori generates images
        ↓
   HTML / CSS / HTTP

Betting on SSR Rendering

Remix’s JSX runtime lives in remix/ui, and it does a lot of heavy lifting.

Routes must first be declared as a typed URL contract in app/routes.ts.

export const routes = route({
  home: "/",
  blog: route("/blog", {
    index: get("/"),
    article: get("/:slug"),
    comment: post("/:slug/comments"),
  }),
});

Controllers then return a standard Response.

export default createController(routes, {
  actions: {
    home({ get, render }) {
      const i18n = createI18n(get(LangContext));
      return render(<Home i18n={i18n} />);
    },
  },
});

render() ultimately calls renderToStream(), producing a ReadableStream<Uint8Array> that can be placed directly into a Response.

Deno.serve((request) => router.fetch(request));

GET, POST, redirects, content‑negotiation, and error responses all happen within a single HTTP pipeline.

If comment form validation fails, the controller can re‑render the page with error messages; on success it returns a redirect.

There is no separate server‑side template plus a client‑side state layer—the HTML itself is the final representation of state.

Injecting New CSS Capabilities

In recent years browsers have added many capabilities that previously required JavaScript. The most useful for this project are cross‑document View Transitions and Scroll‑driven Animations.

Since we have no client JS, this must be an MPA, not an SPA.

Page navigation remains ordinary <a> links with full document requests, but with @view-transition { navigation: auto; } the browser can provide View Transitions across document navigations.

For example, the blog list and article pages give their titles the same view-transition-name, so the two independent server responses can create a seamless visual transition.

export function blogPostTitleTransitionName(slug: string) {
  return createDomId("blog-post-title", slug);
}

<h1
  style={{
    viewTransitionName: blogPostTitleTransitionName(post.slug),
  }}
>
  {post.title}
</h1>;

The <h2> on the list page and the <h1> on the article page share a stable name. The browser builds a correspondence between the old and new titles across the navigation, without any SPA router.

We also implemented a scroll‑driven animation timeline for reading progress inside articles.

First we wrapped a simple ScrollDrivenAnimation component:

export function ScrollDrivenAnimation(
  handle: Handle<ScrollDrivenAnimationProps>,
) {
  const {
    timeline = "view()",
    range = "entry 0% cover 40%",
    keyframes,
  } = handle.props;

  const animationStyle = css({
    animationName: `scroll-${handle.id}`,
    animationDuration: "1ms",
    animationFillMode: "both",
    animationTimeline: timeline,
    animationRange: range,
    [`@keyframes scroll-${handle.id}`]: keyframes,
  });

  return () => <div mix={animationStyle}>{handle.props.children}</div>;
}

The article container declares a named view timeline, and each segment consumes a portion of that timeline based on its percentage of the total text:

const articleTimelineStyle = css({
  viewTimelineAxis: "block",
  viewTimelineName: "--article-reading",
});

<ScrollDrivenAnimation
  timeline="--article-reading"
  range={`cover 40% cover 60%`}
  keyframes={{
    from: { color: "var(--border)" },
    to: { color: "var(--foreground)" },
  }}
>
  <span data-timeline-line />
</ScrollDrivenAnimation>;

We calculate the number of words in each Markdown section; longer sections occupy more of the timeline, and the heading marks also serve as ordinary anchor links. Thus the heading is both a reading progress marker and a JavaScript‑free TOC.

Internationalization is also handled at the request boundary. The locale() middleware first reads ?lang= from the URL, falls back to parsing Accept-Language and its q weights, then writes the language into a typed LangContext:

export function locale(): Middleware {
  return (context, next) => {
    context.set(LangContext, getLangFromRequest(context.request), {
      property: "lang",
    });
    return next();
  };
}

This value determines not only the body copy but also <html lang>, date locale, OG locale, manifest URL, and the fonts used in dynamic OG images.

The language information propagates down from a single request fact, so the browser never needs to adjust the page after load—first‑paint HTML is complete for search engines and screen readers.

Regarding accessibility, using new Web capabilities does not mean ignoring compatibility.

View Transitions and scroll‑driven animations are progressive enhancements: supported browsers get a smoother experience, while others retain normal navigation, anchors, and content.

At the same time, prefers-reduced-motion can completely disable the animations, letting system settings take precedence.

Deployment

Removing the build step yields a more direct development and deployment model, but also makes platform differences unavoidable.

We evaluated Cloudflare Workers, Vercel, and Deno.

Cloudflare Workers

Workers are an excellent edge runtime, but they are not a traditional server environment. Application code must be bundled into a module that Workers can deploy, and the runtime provides no local filesystem that the app can read arbitrarily.

For many apps this limitation is fine, but for a blog it would require gathering Markdown files, fonts, and other source assets into a bundle before deployment, or moving them to external storage. We want the repository to be push‑ready and to read Markdown directly from disk at runtime.

Therefore Workers do not align with our core build‑less goal.

Vercel

Remix’s official build‑less path for Node relies on node --import remix/node-tsx.

In the Vercel serverless function entry we examined, there is no way to freely add such a startup flag to the Node process, so we cannot run TS/TSX source files directly as Remix recommends.

We could add a build step using esbuild to produce the expected output, but that would re‑introduce the step we deliberately removed.

Hence we did not choose Vercel.

Deno

Deno turned out to be the most natural answer. It natively executes TypeScript and TSX without needing Node’s --import loader.

Modern Deno also supports npm packages, offering a much more mature Node compatibility layer, plus WebAssembly, Deno FFI, and Node‑API .node native addons.

{
  "tasks": {
    "start": "deno run --allow-env --allow-ffi --allow-read --allow-net deno.ts"
  }
}

Thus the project can run Remix, Twind, Satori, and the Resvg native addon together, use Deno.serve() to handle requests, and store comments and one‑time captchas in Deno KV.

With the free tier sufficient for a personal site, Deno keeps the architecture in its original shape.

The source is the app—no generated directory, no required bundle to commit or upload, and no extra tooling to adapt to a specific platform.

Conclusion

Migrating to a beta framework certainly has costs.

Documentation, API, ecosystem, and deployment experience are evolving rapidly; we lack a mature ecosystem, so we have to read source code and write our own middleware.

But Remix 3 accounted for that. With AI gaining momentum, Remix 3’s libraries are all TypeScript files, making Remix 3 agent‑friendly, unlike Next.js with its myriad compiler tricks, especially directives like use client.

Moreover, Remix does not implement its own PPR protocol; it builds directly on Web APIs, achieving routing, server, components, data boundaries, and progressive enhancement.

You can use Islands, Frames, and client‑side hydration, or, like this site, create zero client entries.

Remix v3 is still very new, and we are continuing to watch its development, but it demonstrates that modern web applications can have type safety, componentization, dynamic images, and interaction while keeping the server, browser, and open standards at the core.

How to Build a Serverless Agent

Mon, 27 Jul 2026 03:25:00 GMT

Serverless platforms are a natural fit for AI agents because they only need to run when a request arrives, allowing cheap, always‑on‑free deployments; Vercel Workflow provides the long‑running, stateful orchestration required for such on‑demand agents. By leveraging Workflow’s use workflow/use step directives, hooks for Human‑in‑the‑Loop interactions, and the Vercel AI SDK, ClawLess demonstrates how to build a durable, interactive agent that handles messages, tool approvals, delayed tasks, and context management (compression and pruning) without a resident process. The article concludes that assembling these components makes creating functional, serverless agents straightforward and invites developers to extend the approach with custom tools and sandboxed execution.

In early April, we open‑sourced the Serverless project ClawLess, which can deploy a lightweight Agent that is available 24 hours for free on your Vercel account.

This article records the trade‑offs behind ClawLess: why it should be Serverless, and how we assembled a working Agent using Vercel Workflow, Vercel AI SDK, Vercel Sandbox, KV, Blob, and Postgres Vector.

Motivation

Building a complete, long‑running Agent runtime costs not the model, but the always‑on part.

You can pick a cheap or free model, but you still need your own server, VPS, or a constantly‑online Mac mini.

Some projects have offered a different solution: rewrite the runtime in a smaller native language, push memory usage down, and run it on a Raspberry Pi, development board, or another cheap Linux device.

Those solutions still need a device that stays online to run the Agent, maintain its state, wait for user messages, and handle scheduled jobs, and ClawLess was never intended for that approach.

For most people, the most common entry point for an Agent is still a chatbot: the user sends a message, the Agent reads context, calls tools, and returns a result. It does not need to run on the CPU every second; it only needs to reliably handle a request when it is woken up.

We only need to process a request when a conversation arrives:

If it’s on the web, that’s an API request triggered when the user sends a message.
If it’s connected to your IM, that’s a webhook triggered when the IM receives a request (or it could be an API request).

In addition, we need delayed and scheduled tasks, e.g. “remind me tomorrow to continue this topic” or “every morning summarize a channel”. These tasks don’t require a resident process; they only need the platform to pause a workflow, wait, and resume at the appropriate time.

Old friends know I’m a fan of Serverless. Its core idea is: start when a request arrives, sleep while a task is pending, and wake up again when the time comes.

Because of this characteristic, Serverless platforms can be deployed at very low cost, especially for JS runtimes such as AWS Lambda, Vercel, Cloudflare Workers, and many of them have generous free tiers.

After some research, I settled on Vercel Workflow. It can start long‑running tasks, wait inside a workflow, and resume later, so ClawLess can be woken by messages, webhooks, tool approvals, and schedules.

In other words, ClawLess does not need to run continuously; it only needs to be invoked on demand. That’s exactly what a Workflow‑style runtime excels at.

Design

Since it has both front‑end and back‑end, this is a full‑stack project.

For full‑stack we have tried Nuxt or Hono‑SSR approaches, but we chose Next.js as the framework because we need to use the Vercel Workflow API to build the Agent, and Next.js is the native framework for Vercel Workflow.

Workflow as the Agent Runtime

First, a quick intro to Vercel Workflow, Vercel’s newly released official, long‑running, stateful process framework. In our tests a workflow can run for at least 10 minutes.

When we built ClawLess, Vercel Workflow was still in beta, but the API is now stable.

It uses "use workflow"; and "use step"; directives to define a workflow.

use workflow handles orchestration – cross‑step state, waiting, resuming, and the overall flow.
use step handles execution – individual retryable, side‑effect‑heavy atomic operations.

For an Agent, the logic that actually talks to a database, third‑party API, or Sandbox command usually lives in a step; waiting for a user message, waiting for approval, or waiting until 9 am tomorrow belongs in the workflow layer.

An example workflow:

async function updateUser(userId: string) {
  "use step";
  await db.insert({ id: userId });
}

export async function userOnboardingWorkflow(userId: string) {
  "use workflow";
  await updateUser(userId);
}

export async function POST() {
  await updateUser("123");
}

For AI, the most popular TypeScript framework is the Vercel AI SDK.

import { convertToModelMessages, streamText, type UIMessage } from "ai";

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: "anthropic/claude-sonnet-4.5",
    system: "You are a helpful assistant.",
    messages: await convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse();
}

On the front‑end you can use the useChat hook to easily build a chat UI.

"use client";

import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";
import { useState } from "react";

export default function Page() {
  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({
      api: "/api/chat",
    }),
  });
  const [input, setInput] = useState("");

  return (
    <>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role === "user" ? "User: " : "AI: "}
          {message.parts.map((part, index) =>
            part.type === "text" ? <span key={index}>{part.text}</span> : null
          )}
        </div>
      ))}

      <form
        onSubmit={(e) => {
          e.preventDefault();
          if (input.trim()) {
            sendMessage({ text: input });
            setInput("");
          }
        }}
      >
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          disabled={status !== "ready"}
          placeholder="Say something..."
        />
        <button type="submit" disabled={status !== "ready"}>
          Submit
        </button>
      </form>
    </>
  );
}

useChat hooks also have Vue, Svelte, and Angular libraries.

That gives a perfectly usable Web Chat, but it’s not yet a Durable Agent because the runtime ends when the request finishes.

Our Agent needs to keep running after a request ends and persist its state.

So our workflow is equipped with an AI module that is deeply integrated with the AI SDK and provides a DurableAgent suited for workflow scenarios.

Workflow.getWritable() returns a persistent writable stream; the client can disconnect and later reconnect to receive the rest of the output.

A simplified illustration:

import { DurableAgent } from "@workflow/ai/agent";
import { getWritable } from "workflow";
import type { UIMessage, UIMessageChunk } from "ai";

export async function chatWorkflow(messages: UIMessage[]) {
  "use workflow";

  const writable = getWritable<UIMessageChunk>();
  const agent = new DurableAgent({
    model: "anthropic/claude-sonnet-4.5",
    system: "You are a helpful assistant.",
  });

  await agent.stream({
    messages,
    writable,
  });
}

Now the Agent truly behaves like an autonomous system.

In ClawLess the process is more involved: the main workflow reads the current configuration from KV, builds a system prompt, loads tools from MCP, creates a DurableAgent, writes output to the UI message stream (and persists it), and finally saves state to Postgres SQL.

Hook Makes the Workflow Truly Interactive

Consider the case where a user continues to send messages on the web, or an IM webhook delivers more messages while the workflow is still running. We should follow‑up with the existing Agent instead of spawning a brand‑new workflow each time.

This is the basic logic of Human‑in‑the‑Loop (HITL). For more details see Wikipedia’s Human‑in‑the‑Loop.

Fortunately, Workflow provides hooks that enable this pattern. A hook lets a running workflow pause at a certain point, wait for an external event, and then resume.

The simplest external event is “the next user message”:

import { defineHook } from "workflow";

// Define a hook that receives an external event (the next user message)
export const messageHook = defineHook<{
  text: string;
  userId: string;
}>();

export async function conversation(sessionId: string) {
  "use workflow";

  const events = messageHook.create({
    token: "chat-" + sessionId,
  });

  // Wait for external events (the next user message)
  for await (const event of events) {
    console.log("Received", event.text, "from", event.userId);
  }
}

export async function POST(req: Request) {
  const data = await req.json();

  await messageHook.resume("chat-" + data.sessionId, {
    text: data.text,
    userId: data.userId,
  });

  return new Response("OK");
}

The same mechanism works well for tool approvals. For example, when the model wants to execute a high‑risk command—delete a file, send a message, place an order, transfer money—we should not run it directly. Instead we throw an approval request to the front‑end and wait for user confirmation.

See the AI SDK documentation on Tool Execution Approval.

Using workflow hooks means you don’t have to poll a database or write a complex state machine; the workflow suspends while waiting and resumes from the same state.

So the typical Agent workflow looks like this:

A user message hits the entry point.
The entry point checks whether the current session already has an active workflow.
If it does, the new message is sent back via a hook.
If not, a new workflow is created from scratch.

Context

Agents have a context limit. Token‑counting differs between models, but they all share one constraint: you must fit the system prompt, history, tool results, file inputs, and memory into the context window.

Moreover, as the context grows, model accuracy degrades and costs rise.

Two common approaches for handling long context are compression and pruning.

Compression

Compression rewrites “very long but still needed” history into a shorter representation. A typical pattern is: once a conversation reaches a certain length, ask the model to summarize early dialogue, key tool results, and confirmed user preferences, then remove the original messages from the current window.

On the next real model call you prepend the summary.

If you want more control, you can use a sliding‑window approach that includes the summary plus the most recent rounds and the current input.

import { generateText, type ModelMessage } from "ai";

export async function compactMessages(messages: ModelMessage[]) {
  const summary = await generateText({
    model,
    messages: [
      ...messages,
      {
        role: "user",
        content:
          "Please summarize our previous conversation and extract the key information that will help later.",
      },
    ],
  });

  return {
    summary: summary.text,
    recentMessages: messages.slice(-8),
  };
}

In a Workflow this is natural because the workflow already has its own lifecycle and external storage. After a round finishes you can write the summary to KV, delete the old messages, and keep only a “session summary” field. The durable session persists, but the context fed to the model does not grow indefinitely.

Pruning

Pruning does not try to understand the history; it simply cuts away parts that are unlikely to help the current round.

The AI SDK already provides pruneMessages, which can strip old reasoning, tool call results, approval traces, and empty messages before sending the payload to the model.

import { type ModelMessage, pruneMessages } from "ai";

export function buildContextWindow(messages: ModelMessage[]) {
  const pruned = pruneMessages({
    messages,
    reasoning: "before-last-message",
    toolCalls: "before-last-2-messages",
    emptyMessages: "remove",
  });

  const pinned = pruned.filter((m) => m.role === "system");
  const recent = pruned.filter((m) => m.role !== "system").slice(-12);

  return [...pinned, ...recent];
}

For Workflow‑based AI you typically call prepareStep before each model invocation to rewrite the window.

const result = await agent.stream({
  messages,
  writable,

  // prepareStep runs before each model call to reshape the context window
  prepareStep: async ({ messages: currentMessages }) => {
    return {
      messages: buildContextWindow(currentMessages),
    };
  },
});

Compression and pruning are not mutually exclusive; most production systems combine them according to design needs.

This is the idea of Context Engineering – see Anthropic’s article Effective Context Engineering for AI Agents.

Beyond that, we also need cross‑conversation, cross‑knowledge, or permanent shared context. For those cases we store data in external systems via tools rather than stuffing everything into the model’s context.

Tools

An Agent’s tools define its capability boundary.

Without tools it is just a chat model; with tools it can store memory, execute commands, learn skills, schedule tasks, or delegate work to sub‑Agents.

In the AI SDK, tools are first‑class citizens. A minimal tool definition looks like this:

import { tool } from "ai";
import { z } from "zod";

const tools = {
  remember: tool({
    description: "Save a useful fact into long‑term memory",
    inputSchema: z.object({
      note: z.string(),
    }),
    execute: async ({ note }) => {
      const memory = await buildMemory(note);
      return { ok: true, memory };
    },
  }),
};

Memory

Memory stores long‑term facts and user preferences.

You can keep it in KV, a database, or as files in Blob, and expose tools for the model to manage it.

For search, full‑text keyword search is convenient but has limits; two sentences may be highly related without sharing any words.

Consider RAG (Retrieval‑Augmented Generation) – letting the model retrieve relevant information from an external knowledge base while generating a response.

The simplest approach is vector‑embedding search: encode a sentence into a multi‑dimensional vector and find the most similar vectors in the space. Cosine similarity is a common metric:

$\operatorname{Similarity} = \hat{\mathbf{q}} \cdot \hat{\mathbf{d}} = \sum_{i=1}^{n} \hat q_i \hat d_i$

Normalize the similarity scores and sort.

In production we usually combine vector search with keyword search (hybrid search).

For a deeper dive into Memory, see OpenClaw’s Memory design.

Skills

Skills are more like file‑system‑based knowledge bases.

A Skill typically lives in a directory structure such as:

my-skill $ tree

my-skill/
    SKILL.md

    scripts/
    templates/
    examples/
    assets/

Skills describe how to do things, for example:

How to write a certain type of test
How to invoke an internal specification
How to generate code according to team conventions

We usually extract a Skill’s title and description and inject them into the System Prompt.

Skills were introduced by Anthropic; see Agent Skills Overview.

Execute Bash

Execution tools let the Agent actually interact with the outside world.

The most basic execution tool is a Bash tool that runs shell commands, bridging the Agent to a real environment.

In ClawLess we use @vercel/sandbox to implement the Bash tool.

Bash is the highest‑risk tool and requires strong isolation, careful approval, and sandboxing.

If you’re looking for a Serverless Bash tool or a sandboxed Bash implementation, check out our AI SDK X.

Tasks

When handling complex work we need to consider more categories.

Delayed and Scheduled Tasks

A delayed task notifies you after a certain amount of time.

ClawLess implements delayed tasks inside a Workflow using the sleep function.

import { sleep } from "workflow";

export async function remindTomorrow(taskId: string) {
  "use workflow";

  await sleep("1 day");
  await sendReminder(taskId);
}

A scheduled task (Cron Job) runs at a specific time repeatedly.

Implementation is similar; we use an infinite loop with sleep.

while (true) {
  await sleep("1 day");
  runTask();
}

Sub‑Agents

A sub‑task does not have to be a full‑blown Agent; it can delegate a small piece of work.

For example, the main Agent handles the conversation, but a specific research question could be handed to a cheaper, smaller model.

A minimal Sub‑Agent implementation:

import { generateText, tool } from "ai";
import { z } from "zod";

const delegateResearch = tool({
  description: "Hand off a focused research subtask",
  inputSchema: z.object({
    question: z.string(),
  }),
  execute: async ({ question }) => {
    const result = await generateText({
      model: "openai/gpt-4.1-mini",
      prompt: "Answer briefly and return only key facts:\n" + question,
    });

    return { summary: result.text };
  },
});

MCP and Other Tools

The Model Context Protocol (MCP) is a unified protocol that lets an Agent connect to external systems in a standardized way.

If you are building a domain‑specific Agent, MCP is often a better fit than a handful of ad‑hoc Skills.

ClawLess does not implement web search, browser navigation, etc., directly; instead we can plug those capabilities in via MCP.

Connecting to the Frontend

The front‑end that interacts with the Agent can be a web page, a Bot, or any other client.

Web Chat

The useChat hook we showed earlier is the simplest web‑chat solution; we won’t repeat it here.

Connecting to IM via Webhook

Most instant‑messaging platforms expose Bot capabilities (e.g., Telegram, Discord).

Bots typically receive messages either via long polling or webhooks.

Long polling means the Bot periodically (the “heartbeat”) asks the server for new messages; OpenClaw’s connectors work this way.

Webhooks are more efficient: the server pushes a new‑message notification to the Bot without the Bot having to request.

ClawLess uses the Chat SDK to connect to various IMs via webhook.

The Chat SDK is straightforward: create a Chat instance.

// Next: lib/bot.ts
import { Chat } from "chat";

const bot = new Chat({
  userName: "mybot",
  adapters: { slack },
  state: createRedisState(),
});

bot.onNewMention(async (thread, message) => {
  await agent.handleMessage(message);
});

Then expose an API route that handles the webhook.

// Next: app/api/webhooks/slack/route.ts
export const POST = bot.webhooks.slack;

Conclusion

By now you should see that building an Agent can be surprisingly simple.

We hope you combine these pieces to create your own Agents—it’s genuinely fun.

We are also building a universal sandboxed Bash that works in any JS Runtime, Serverless or embedded environments. If you’re interested, check out our AI‑SDK‑X documentation.

Welcome To Niapya's Blog

Mon, 27 Jul 2026 03:25:00 GMT

The author argues that, despite the dominance of AI‑generated “Vibe‑coded” blogs, a personal blog should remain fully under the author’s control, so they built a lightweight static‑site generator using Hono/JSX for templating, marked for Markdown, and UnoCSS for atomic styling, resulting in a site with zero client‑side JavaScript. They demonstrate a working prototype and outline future plans to evolve it into a full framework with plugins, a retro UI component library, and optional SSR, all open‑sourced on GitHub.

Yes, I finally have a blog.

2026 is the year Vibe Coding exploded. We've gotten used to using Code Agent to write any project, and the old “hand‑coded” approach is mocked as “ancient programming”. By now most people have lost the habit of writing code themselves; if they want a blog, they just Vibe a Next.js template, or even use an off‑the‑shelf SaaS blogging platform with Skills and let an Agent write the posts.

But I think a blog, as a personal platform, should be fully controlled by the author. So I want to build my own blogging framework, my own blog style, and my own blog content from scratch.

Building the Blog Framework

Since sites of this type usually don’t need server‑side logic, we call them static sites. What I need to create is a Static Site Generator (SSG).

The SSG workflow is simple: fetch a content source and parse it into documents, render them with templates, and output the result as website files. I want to control every step.

Step 1 – Fetch the content source and parse it into documents

The source can be anything: a database, a CMS, Markdown files, etc. To unify the process we define an interface like this:

export function definePost(
  input: {
    title: string;
    category?: string[];
    tags?: string[];
    content: string;
  },
): Post;

Now we can define our content anywhere, in any way. In the future plugins could pull content from file routes, databases, or even the browser.

Blog content (content) is usually written in Markdown, so I use marked to compile Markdown to HTML, together with marked‑highlight and highlight.js for code highlighting.

import hljs from "highlight.js";
import { Marked } from "marked";
import { markedHighlight } from "marked-highlight";

const markdownRenderer = new Marked({
  breaks: false,
  gfm: true,
});

markdownRenderer.use(
  markedHighlight({
    emptyLangClass: "hljs",
    langPrefix: "hljs language-",
    highlight(code, language) {
      const highlightLanguage = hljs.getLanguage(language)
        ? language
        : "plaintext";

      return hljs.highlight(code, { language: highlightLanguage }).value;
    },
  }),
);

await markdownRenderer.parse(markdown, { renderer });

Step 2 – Render with templates

Because we are producing website files, most SSGs tie the template closely to the HTML structure. If you pick a custom template language you have to define an AST and a compiler yourself—for example, Astro’s .astro files are a proprietary component syntax. You’d also need to build a toolchain for type checking and syntax highlighting, which hurts developer experience.

Some SSGs use React/Vue components as templates. Those feel nice to develop with, but they tend to be tightly coupled to the respective framework’s ecosystem and can unintentionally pull in client‑side JavaScript. For an SSG, pulling in any unnecessary client JavaScript by default is unwise.

So I chose a lightweight solution: JSX powered by Hono/JSX for templates. It lets us write JSX, render it on the server, and output an HTML string while keeping type safety. For pure static pages the resulting HTML files contain no framework‑related client code.

export function HtmlArticle({ html }) {
  return (
    <div
      dangerouslySetInnerHTML={{ __html: html }}
    />
  );
}

const app = new Hono()
  .get("/", (c) => {
    return c.html(<HtmlArticle html={markdownRenderer.parse(markdown)} />);
  });

Step 3 – Output as website files

After defining content and templates we need to define the site structure (aka routes). Since we’re using Hono/JSX, we can declare routes with an HTTP framework—Hono fits the bill. With Hono we can also spin up a dev server easily.

Later we could also use this approach for Server‑Side Rendering (SSR), but for now we focus on SSG.

Hono provides a toSSG method that pre‑renders the Hono app’s routes into static files at build time, allowing us to output static files directly from Hono.

Styling the Blog

Applying CSS in JSX has always been tricky—CSS Modules, until atomic solutions like TailwindCSS arrived.

We chose UnoCSS as our CSS solution because it generates atomic CSS on demand and offers a programmable generator API that can compile class names into CSS code.

import { createGenerator, presetWind4 } from "unocss";

const uno = await createGenerator({
  presets: [presetWind4()],
});

export async function compileAtomicCss(input: string): Promise<string> {
  const { css } = await uno.generate(input);
  return css;
}

For the default blog style I went with a classic Macintosh look. We’re planning to use Figma and create a corresponding UI component library to deliver a retro‑styled blog theme.

Future Plans

You may notice that this blog uses no client‑side JavaScript, which is exactly what I wanted. A static blog doesn’t need any client JavaScript.

The source code is available on GitHub.

Eventually we hope to turn this project into a real framework and release our own UI component library, along with features such as:

Plugin‑based RSS and Sitemap generation
Search and comment systems based on HTML Form
An online compiler
Possible full‑stack SSR support

Because we don’t rely on Vite and we avoid dependencies that only work in a Node.js environment, this framework could even run directly in the browser in the future.

Niapya Blog

Migrate to remix@3

A Glimpse of Remix v3

Why should we have a build step?

Preparations

Generating Tailwind CSS for SSR with Twind

Satori‑Generated Captchas

Migration Work

Betting on SSR Rendering

Injecting New CSS Capabilities

i18n, a11y, and Others

Deployment

Cloudflare Workers

Vercel

Deno

Conclusion

How to Build a Serverless Agent

Motivation

Design

Workflow as the Agent Runtime

Hook Makes the Workflow Truly Interactive

Context

Compression

Pruning

Tools

Memory

Skills

Execute Bash

Tasks

Delayed and Scheduled Tasks

Sub‑Agents

MCP and Other Tools

Connecting to the Frontend

Web Chat

Connecting to IM via Webhook

Conclusion

Welcome To Niapya's Blog

Building the Blog Framework

Step 1 – Fetch the content source and parse it into documents

Step 2 – Render with templates

Step 3 – Output as website files

Styling the Blog

Future Plans