mime-routes

Serve different response types from the same URL based on the Accept header.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? APIs and web pages often need to share one URL, but browsers want HTML while API clients want JSON or XML. This Skill implements HTTP content negotiation in a Rango router so a single URL pattern dispatches to the correct handler based on the request's Accept header, with automatic Vary: Accept headers for correct CDN caching. ## Core Features & Use Cases - Negotiated Route Registration: Declare an RSC page plus JSON, text, XML, HTML, or Markdown variants on the same URL pattern; the trie merges them at build time. - Standards-Based Negotiation: Q-value priority, client-order tiebreakers, wildcard fallbacks, and explicit text/x-component opt-in for the RSC flight wire format. - Type-Safe Responses: Use RouteResponse or Rango.PathResponse types to get typed response payloads per negotiated variant. - Use Case: Expose /products/:id as an HTML page for browsers and a JSON endpoint for API consumers without maintaining separate route trees or manual Accept parsing. ## Quick Start Ask the AI to add a JSON variant to an existing Rango route so the same URL serves HTML to browsers and JSON to API clients based on the Accept header.

Frequently Asked Questions about mime-routes

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

FAQPage Schema
How do I serve JSON and HTML from the same URL?

Register an RSC route with path() and a JSON variant with path.json() on the same URL pattern in your urls() array. The router inspects the Accept header and dispatches to the matching handler, adding Vary: Accept automatically.

How does Accept header content negotiation work in Rango?

Rango parses q-values first, then uses client ordering as a tiebreaker, then specific MIME matches. Wildcards and missing Accept headers fall back to route definition order, with the first-defined variant winning.

Can I have multiple response types on one route without an RSC page?

Yes, two or more response-type routes like path.json and path.text can share a URL without an RSC route. The last registered route becomes the primary and the Accept header picks among the response-type candidates directly.

Does content negotiation work with CDN caching?

Yes, all negotiated responses automatically include the Vary: Accept header. This tells CDNs and HTTP caches to store separate entries per Accept header value, so no additional cache configuration is needed.

When is the RSC flight wire format served instead of HTML?

The flight format is explicit opt-in only, served when the client sends Accept: text/x-component or the internal transport params the Rango client runtime sends. Browsers, curl, and generic HTTP clients always receive the HTML document.