JSON in Cloudflare Workers

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

Cloudflare Workers handle JSON through the standard Web API — Response.json(), request.json(), and full JSON.parse/JSON.stringify support — with no Node.js polyfills needed. Workers run on V8 isolates deployed across 300+ edge locations, so JSON parsing performance is identical to Node.js at sub-millisecond latency. This guide covers every layer: fetch handler JSON responses, parsing request bodies, KV storage, D1 SQL queries, Hono framework routes, Zod validation, and error handling.

JSON Responses in Fetch Handler

The simplest way to return JSON from a Cloudflare Worker is Response.json(data). This static constructor serializes data with JSON.stringify and sets Content-Type: application/json; charset=UTF-8 automatically. Pass an optional init object as the second argument to control status codes and headers.

// wrangler.toml: name = "my-worker", compatibility_date = "2024-01-01"

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url)

    // Basic JSON response — sets Content-Type automatically
    if (url.pathname === '/api/ping') {
      return Response.json({ ok: true, ts: Date.now() })
    }

    // Custom status code
    if (url.pathname === '/api/created') {
      return Response.json({ id: 42, name: 'item' }, { status: 201 })
    }

    // Custom headers alongside JSON
    if (url.pathname === '/api/cached') {
      return Response.json(
        { data: 'hello' },
        {
          status: 200,
          headers: {
            'Cache-Control': 'public, max-age=60',
            'X-Worker-Region': request.cf?.colo ?? 'unknown',
          },
        }
      )
    }

    return Response.json({ error: 'Not Found' }, { status: 404 })
  },
}

Avoid constructing responses manually with new Response(JSON.stringify(data)) — you must set Content-Type yourself and it is easy to forget. Response.json() has been available in Cloudflare Workers since mid-2023 and is part of the WinterCG fetch standard.

Parsing JSON Request Bodies

Call await request.json() to parse an incoming JSON body. The method reads the body stream and calls JSON.parse internally. A body stream can only be consumed once — call request.clone().json() if you need to read the body twice (for example, in middleware and in the handler).

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== 'POST') {
      return Response.json({ error: 'Method Not Allowed' }, { status: 405 })
    }

    // Check Content-Type before attempting to parse
    const contentType = request.headers.get('Content-Type') ?? ''
    if (!contentType.includes('application/json')) {
      return Response.json({ error: 'Expected application/json' }, { status: 415 })
    }

    // Parse body — throws SyntaxError on invalid JSON
    let body: unknown
    try {
      body = await request.json()
    } catch {
      return Response.json({ error: 'Invalid JSON body' }, { status: 400 })
    }

    // Type narrowing after parse
    if (
      typeof body !== 'object' ||
      body === null ||
      !('name' in body) ||
      typeof (body as Record<string, unknown>).name !== 'string'
    ) {
      return Response.json({ error: 'Missing required field: name' }, { status: 422 })
    }

    const { name } = body as { name: string }
    return Response.json({ created: true, name }, { status: 201 })
  },
}

JSON in Cloudflare KV

Cloudflare KV stores values as UTF-8 strings or ArrayBuffers. JSON must be serialized on write and parsed on read. KV provides a built-in { type: "json" } option that calls JSON.parse internally, returning null if the key does not exist.

// wrangler.toml:
// [[kv_namespaces]]
// binding = "CACHE"
// id = "abc123..."

interface Env {
  CACHE: KVNamespace
}

// --- Write JSON to KV ---
async function saveUser(env: Env, userId: string, user: object) {
  await env.CACHE.put(
    `user:${userId}`,
    JSON.stringify(user),
    { expirationTtl: 3600 }  // seconds; optional
  )
}

// --- Read JSON from KV (manual parse) ---
async function getUser(env: Env, userId: string) {
  const raw = await env.CACHE.get(`user:${userId}`)
  return raw ? JSON.parse(raw) : null
}

// --- Read JSON from KV (built-in type option) ---
async function getUserTyped(env: Env, userId: string) {
  return env.CACHE.get(`user:${userId}`, { type: 'json' })
  // Returns parsed value or null — no JSON.parse needed
}

// --- List keys with metadata ---
async function listProducts(env: Env) {
  const list = await env.CACHE.list({ prefix: 'product:' })
  const items = await Promise.all(
    list.keys.map(k => env.CACHE.get(k.name, { type: 'json' }))
  )
  return items.filter(Boolean)
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const user = await getUserTyped(env, '42')
    if (!user) return Response.json({ error: 'Not Found' }, { status: 404 })
    return Response.json(user)
  },
}

KV is eventually consistent: writes propagate to all edge locations within approximately 60 seconds. Use KV for read-heavy data that can tolerate brief staleness — user profiles, feature flags, product catalogs. For strictly consistent data, use D1 or Durable Objects.

JSON with D1 (SQLite)

Cloudflare D1 is a serverless SQLite database. SQLite's JSON1 extension is available in D1, enabling json_extract(), json_set(), json_each(), and json_array_length() on TEXT columns that store JSON strings. This lets you query nested JSON fields without fetching and parsing the full row in application code.

// wrangler.toml:
// [[d1_databases]]
// binding = "DB"
// database_name = "mydb"
// database_id = "..."

interface Env {
  DB: D1Database
}

// Schema: CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, attrs TEXT);
// attrs column stores JSON like: {"color":"red","size":"M","tags":["sale","new"]}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url)

    // --- Insert a row with a JSON column ---
    if (request.method === 'POST' && url.pathname === '/products') {
      const body = await request.json() as { name: string; attrs: object }
      const result = await env.DB
        .prepare('INSERT INTO products (name, attrs) VALUES (?, ?) RETURNING id')
        .bind(body.name, JSON.stringify(body.attrs))
        .first<{ id: number }>()
      return Response.json({ id: result?.id }, { status: 201 })
    }

    // --- Query with json_extract ---
    if (url.pathname === '/products/red') {
      const { results } = await env.DB
        .prepare("SELECT id, name, json_extract(attrs, '$.color') AS color FROM products WHERE json_extract(attrs, '$.color') = ?")
        .bind('red')
        .all()
      return Response.json(results)
    }

    // --- Update a nested JSON field with json_set ---
    if (request.method === 'PATCH' && url.pathname.startsWith('/products/')) {
      const id = url.pathname.split('/').pop()
      const { color } = await request.json() as { color: string }
      await env.DB
        .prepare("UPDATE products SET attrs = json_set(attrs, '$.color', ?) WHERE id = ?")
        .bind(color, id)
        .run()
      return Response.json({ updated: true })
    }

    // --- Expand a JSON array column with json_each ---
    if (url.pathname === '/products/tags') {
      const { results } = await env.DB
        .prepare("SELECT p.id, p.name, t.value AS tag FROM products p, json_each(p.attrs, '$.tags') t")
        .all()
      return Response.json(results)
    }

    return Response.json({ error: 'Not Found' }, { status: 404 })
  },
}

Hono JSON API Framework

Hono is a lightweight (~12 KB) web framework built on Web Standards that runs natively on Cloudflare Workers. Its c.json(data, status?) method returns JSON responses with correct headers, and c.req.json() parses request bodies. Hono's router, middleware pipeline, and TypeScript generics significantly reduce boilerplate compared to a bare fetch handler.

// npm install hono
import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'

interface Env {
  DB: D1Database
  CACHE: KVNamespace
}

const app = new Hono<{ Bindings: Env }>()

// Global middleware
app.use('*', logger())
app.use('/api/*', cors({ origin: 'https://example.com' }))

// GET — return JSON
app.get('/api/products', async (c) => {
  const { results } = await c.env.DB.prepare('SELECT * FROM products').all()
  return c.json(results)
})

// GET by ID
app.get('/api/products/:id', async (c) => {
  const id = c.req.param('id')
  const product = await c.env.DB
    .prepare('SELECT * FROM products WHERE id = ?')
    .bind(id)
    .first()
  if (!product) return c.json({ error: 'Not Found' }, 404)
  return c.json(product)
})

// POST — parse body with c.req.json()
app.post('/api/products', async (c) => {
  const body = await c.req.json<{ name: string; price: number }>()
  const result = await c.env.DB
    .prepare('INSERT INTO products (name, price) VALUES (?, ?) RETURNING id')
    .bind(body.name, body.price)
    .first<{ id: number }>()
  return c.json({ id: result?.id }, 201)
})

// PATCH — partial update
app.patch('/api/products/:id', async (c) => {
  const id = c.req.param('id')
  const body = await c.req.json<Partial<{ name: string; price: number }>>()
  await c.env.DB
    .prepare('UPDATE products SET name = COALESCE(?, name), price = COALESCE(?, price) WHERE id = ?')
    .bind(body.name ?? null, body.price ?? null, id)
    .run()
  return c.json({ updated: true })
})

// Global error handler
app.onError((err, c) => {
  console.error(err)
  return c.json({ error: 'Internal Server Error' }, 500)
})

// 404 fallback
app.notFound((c) => c.json({ error: 'Not Found' }, 404))

export default app

Validating JSON with Zod at the Edge

Zod runs in any V8 environment with no native bindings, making it suitable for Cloudflare Workers. Use schema.safeParse() to validate without throwing, then return structured error responses. With Hono, the @hono/zod-validator middleware handles validation before the route handler runs.

// npm install zod @hono/zod-validator
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const app = new Hono()

// --- Schema definitions ---
const CreateProductSchema = z.object({
  name:     z.string().min(1).max(100),
  price:    z.number().positive(),
  category: z.enum(['electronics', 'clothing', 'food']),
  tags:     z.array(z.string()).max(10).optional(),
})

const UpdateProductSchema = CreateProductSchema.partial()

// --- Route with zValidator middleware ---
// Validation runs before handler; returns 400 on schema violation
app.post(
  '/api/products',
  zValidator('json', CreateProductSchema),
  async (c) => {
    // c.req.valid('json') is already typed and validated
    const product = c.req.valid('json')
    // product.name, product.price, product.category are type-safe
    return c.json({ created: true, product }, 201)
  }
)

// --- Manual validation without Hono ---
export default {
  async fetch(request: Request): Promise<Response> {
    if (request.method !== 'POST') {
      return Response.json({ error: 'Method Not Allowed' }, { status: 405 })
    }

    let raw: unknown
    try {
      raw = await request.json()
    } catch {
      return Response.json({ error: 'Invalid JSON' }, { status: 400 })
    }

    const result = CreateProductSchema.safeParse(raw)
    if (!result.success) {
      return Response.json(
        { error: 'Validation failed', details: result.error.flatten().fieldErrors },
        { status: 422 }
      )
    }

    const { name, price, category } = result.data
    // ... store in DB
    return Response.json({ name, price, category }, { status: 201 })
  },
}

Error Handling and JSON Error Responses

Consistent JSON error shapes make APIs easier for clients to handle programmatically. Return a structured error object — { error: string, code?: string, details?: unknown } — with every non-2xx response. Wrap your fetch handler in a top-level try/catch to prevent unhandled exceptions from returning HTML error pages.

// Shared error response helper
function jsonError(message: string, status: number, details?: unknown): Response {
  return Response.json(
    { error: message, ...(details ? { details } : {}) },
    { status }
  )
}

// Error code constants
const E = {
  INVALID_JSON:    'INVALID_JSON',
  VALIDATION:      'VALIDATION_ERROR',
  NOT_FOUND:       'NOT_FOUND',
  METHOD_MISMATCH: 'METHOD_NOT_ALLOWED',
  SERVER_ERROR:    'INTERNAL_ERROR',
} as const

// Full fetch handler with error handling
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    try {
      return await handleRequest(request, env)
    } catch (err) {
      // Log for Cloudflare Workers Logs / Logpush
      console.error('Unhandled error:', err)
      return Response.json(
        { error: 'Internal Server Error', code: E.SERVER_ERROR },
        { status: 500 }
      )
    }
  },
}

async function handleRequest(request: Request, env: Env): Promise<Response> {
  const url = new URL(request.url)

  if (url.pathname === '/api/items' && request.method === 'POST') {
    // 1. Parse body
    let body: unknown
    try {
      body = await request.json()
    } catch {
      return jsonError('Request body is not valid JSON', 400)
    }

    // 2. Validate shape
    const parsed = ItemSchema.safeParse(body)
    if (!parsed.success) {
      return jsonError('Validation failed', 422, parsed.error.flatten().fieldErrors)
    }

    // 3. Business logic
    const existing = await env.DB.prepare('SELECT id FROM items WHERE name = ?')
      .bind(parsed.data.name).first()
    if (existing) {
      return jsonError(`Item "${parsed.data.name}" already exists`, 409)
    }

    const result = await env.DB
      .prepare('INSERT INTO items (name) VALUES (?) RETURNING id')
      .bind(parsed.data.name).first<{ id: number }>()

    return Response.json({ id: result?.id }, { status: 201 })
  }

  return jsonError('Not Found', 404)
}

FAQ