@lunora/browser

@lunora/browser provides a ctx.browser helper for Cloudflare Browser Rendering. It is action-only: browser navigation is non-deterministic network I/O, so codegen wires it onto ActionCtx exclusively, the same class as ctx.ai / ctx.fetch. A ctx.browser call in a query or mutation is a type error.

@cloudflare/playwright is an optional peer dependency (the chromium-protocol shim). Install both:

pnpm add @lunora/browser @cloudflare/playwright

Add the binding to your wrangler.jsonc (the Vite plugin / CLI infers and reconciles it automatically when it sees a @lunora/browser import):

{
    "browser": { "binding": "BROWSER" },
}

Usage

import { action, v } from "@/lunora/_generated/server";

export const screenshotPage = action.input({ url: v.string() }).action(async ({ args: { url }, ctx }) => {
    // Action context only. `ctx.browser` is TYPED automatically, but it is not
    // CONSTRUCTED for you: codegen emits a throwing stub unless the app passes a
    // `browser` thunk to `createShardDO()` (see "Wiring the thunk" below).
    const png = await ctx.browser.screenshot(url, { fullPage: true });

    const { key } = await ctx.storage.store(`shots/${crypto.randomUUID()}.png`, png.buffer, { contentType: "image/png" });

    return ctx.storage.getUrl(key);
});

Wiring the thunk

Codegen weaves ctx.browser onto every ActionCtx and reconciles the BROWSER binding, but it does not construct the helper: createBrowser needs the optional @cloudflare/playwright launch peer, and the generated worker stays free of it deliberately. So codegen emits config.browser ? config.browser(env) : browserStub, and browserStub throws a directed error on every method. Pass the thunk once, where you build the shard:

import { launch } from "@cloudflare/playwright";
import { createBrowser } from "@lunora/browser";

export const ShardDO = createShardDO({
    browser: (env) => createBrowser({ binding: env.BROWSER, launch }),
});

Without that line every ctx.browser call throws — including the one the browserTool agent sandbox makes.

Outside a Lunora action (worker entry, DO, queue handler), build the helper directly:

import { launch } from "@cloudflare/playwright";
import { createBrowser } from "@lunora/browser";

const browser = createBrowser({ binding: env.BROWSER, launch });

const png = await browser.screenshot("https://example.com", { fullPage: true });
const pdf = await browser.pdf("https://example.com", { format: "A4", printBackground: true });
const html = await browser.content("https://example.com");
const title = await browser.scrape("https://example.com", () => document.title);

API reference

createBrowser(options)

Browser

URL safety (SSRF guard)

Every navigation URL is validated before the browser is launched: non-http(s) schemes, embedded credentials, and private/internal targets (loopback, RFC1918, link-local, CGNAT, localhost/*.internal/*.local) are rejected by default. IPv4-mapped IPv6 and octal/hex encodings are normalized first. Set allowPrivateTargets: true only when every URL is trusted.

A public hostname that resolves to a private/metadata IP passes the string guard above (classic DNS rebinding), so a second layer runs on top:

• resolveDns is on by default when allowedHosts is unset: a DoH re-check that resolves the hostname over Cloudflare DNS and refuses if any A/AAAA record is private. Best-effort (it adds a round-trip and is TOCTOU-imperfect; it falls back to the string guard if the lookup fails). Setting allowedHosts turns it off by default, because the allowlist is the stronger guard and may legitimately name an internal host that a resolved-address check would refuse; pass resolveDns: true to run both. Set resolveDns: false for trusted, non-user-controlled URLs where the round-trip matters.
• allowedHosts: [...] is a strict allowlist that refuses any hostname not exactly on the list (case-insensitive, trailing-dot- and IPv6-bracket-normalized). This is the only guard that fully closes rebinding, so prefer it whenever you can enumerate the destinations. allowedHosts: [] allows nothing — an empty list is a configured allowlist with no members, not an absent one, so every navigation is refused. Omit the option to run without an allowlist.