response-routes

Create typed JSON, text, and streaming response routes that bypass the RSC pipeline in Rango.

Updated Nov 7, 2025
One-click install
npx skills add https://github.com/rangojs/rango --skill response-routes-rangojs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: response-routes
Source: https://github.com/rangojs/rango/tree/main/packages/rangojs-router/skills/response-routes
Command: npx skills add https://github.com/rangojs/rango --skill response-routes-rangojs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Rango routes normally render React Server Components, but applications also need plain JSON APIs, text endpoints, XML feeds, and image or streaming responses. This Skill explains how to define non-RSC response routes with typed payloads, structured errors, and client-side type safety. ## Core Features & Use Cases - Typed response route tags: Use path.json(), path.text(), path.html(), path.xml(), path.md(), path.image(), path.stream(), and path.any() inside any urls() callback, with automatic content-type wrapping or full Response pass-through. - Structured error handling: Throw RouterError to emit RFC 9457 problem+json bodies, or return/throw a Response directly as control flow with header and cookie merging. - End-to-end type safety: Look up response payload types with RouteResponse or the ambient Rango.PathResponse, and link to response routes with href.json() for hard navigation. - Use Case: Mount a blog module exposing /blog/api/stats and /blog/api/:slug/likes as JSON endpoints alongside RSC pages, then consume them from a typed fetch wrapper whose return type is inferred from the URL path. ## Quick Start Add a JSON API endpoint to my Rango app by defining a path.json route inside my urls() callback with a typed handler and named route.

Frequently Asked Questions about response-routes

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a JSON API endpoint in a Rango router app?

Use path.json() inside any urls() callback with a handler returning a plain object or array. Rango serializes the return value verbatim as application/json, skipping the RSC pipeline entirely, and you can name the route for reverse() lookups.

How do I return errors from a Rango JSON route?

Throw a RouterError with a code, message, and status to produce an RFC 9457 problem+json body with application/problem+json content type. Clients discriminate success from error using res.ok or the HTTP status, not an in-body envelope.

Can response routes set custom headers and cookies?

Yes. String-returning handlers can call ctx.header() and cookies().set(), which merge into both auto-wrapped and handler-returned responses. Handlers can also return a full Response for complete control over status, headers, and streaming.

How do I get typed responses when fetching Rango API routes from the client?

Use RouteResponse<typeof patterns, "routeName"> for scoped lookups without global wiring, or augment Rango.RegisteredRoutes and use the ambient Rango.PathResponse with a URL pattern or concrete path. Both apply the JsonSerialize transform so types match the wire shape.

What are the limitations of response routes compared to RSC routes?

Response routes support only middleware() and cache() as use items, with no loader, loading, layout, or parallel options. Their handlers receive a lighter context without ctx.use() or ctx.res, and caching applies only to GET/HEAD requests.