Responses

Route handlers return a ResponseLike value that Primate converts into a WHATWG Response. You can return simple values ("implicit" responses) or use explicit handlers from primate/response when you need to control all aspects of the response.

Return value	Handler	Response	Notes
`string`	text	`200 text/plain`	Serve plain text
`object`	json	`200 application/json`	Serve JSON
`Blob`·`File`·`FileRef`	binary	`200 application/octet-stream`	Stream contents
`URL`	redirect	`302`	Redirect to URL
—	view	`200 text/html`	Serve frontend component
—	error	`404 text/html`	Show error page
—	ws	`101`	WebSocket upgrade
—	sse	`200 text/event-stream`	Server‑sent events
`null`	—	`204`	`new Response(null)`
Response	—	as given	WHATWG `Response`

Text

Return strings to serve text/plain.

TypeScript JavaScript Go Python Ruby Grainroutes/text.tsroutes/text.jsroutes/text.goroutes/text.pyroutes/text.rbroutes/text.gr

import route from "primate/route";

route.get(request => "Hello from TypeScript!");

import route from "primate/route";

route.get(request => "Hello from TypeScript!");

package main

import "github.com/primate-run/go/route"

var _ = route.Get(func(_ route.Request) any {
	return "Hello from Go!"
})

from primate import Route


@Route.get
def get(request):
    return "Hello from Python!"

require 'primate/route'

Route.get do |request|
  'Hello from Ruby!'
end

module Hello

from "primate/request" include Request

use Request.{ type Request }

provide let get = (request: Request) => "Hello from Grain!"

Use the explicit text handler for more options.

TypeScript JavaScript Go Python Ruby Grainroutes/text.tsroutes/text.jsroutes/text.goroutes/text.pyroutes/text.rbroutes/text.gr

import response from "primate/response";
import Status from "primate/response/Status";
import route from "primate/route";

route.post(request => {
  return response.text("Hello from TypeScript!", { status: Status.CREATED });
});

import response from "primate/response";
import Status from "primate/response/Status";
import route from "primate/route";

route.post(request => {
  return response.text("Hello from TypeScript!", { status: Status.CREATED });
});

package main

import (
	"github.com/primate-run/go/response"
	"github.com/primate-run/go/route"
)

var _ = route.Post(func(request route.Request) any {
	return response.Text("Hello from Go!", map[string]any{"status": 201})
})

from primate import Response, Route


@Route.post
def post(request):
    return Response.text("Hello from Python!", status=201)

require 'primate/route'
require 'primate/response'

Route.post do |request|
  Response.text("Hello from Ruby!", status: 201)
end

module TextResponse

from "primate/request" include Request
from "primate/response" include Response

use Response.{ type Response }
use Request.{ type Request }

provide let post = (request: Request) => {
  Response.text("Hello from Grain!", { status: 201 })
}

JSON

Return JSON-serializable objects to serve application/json.

TypeScript JavaScript Go Python Ruby Grainroutes/json.tsroutes/json.tsroutes/json.goroutes/json.pyroutes/json.rbroutes/json.gr

import route from "primate/route";

route.get(() => [
  { name: "Donald" },
  { name: "John" },
]);

import route from "primate/route";

route.get(() => [
  { name: "Donald" },
  { name: "John" },
]);

package main

import (
	"github.com/primate-run/go/core"
	"github.com/primate-run/go/route"
)

var _ = route.Get(func(request route.Request) any {
	return []core.Dict{{"name": "Donald"}, {"name": "John"}}
})

from primate import Route


@Route.get
def get(request):
    return [{"name": "Donald"}, {"name": "John"}]

require 'primate/route'

Route.get do |request|
  [{ name: 'Donald' }, { name: 'John' }]
end

module JsonResponse

from "primate/request" include Request
from "json" include Json

use Request.{ type Request }
use Json.{ type Json }

provide let get = (request: Request) =>
  JsonArray([
    JsonObject([("name", JsonString("Donald"))]),
    JsonObject([("name", JsonString("John"))])
  ])

Use the explicit json handler for more options.

TypeScript JavaScriptroutes/json.tsroutes/json.ts

import response from "primate/response";
import Status from "primate/response/Status";
import route from "primate/route";

route.get(() => response.json([
  { name: "Donald" },
  { name: "John" },
], { status: Status.CREATED }));

import response from "primate/response";
import Status from "primate/response/Status";
import route from "primate/route";

route.get(() => response.json([
  { name: "Donald" },
  { name: "John" },
], { status: Status.CREATED }));

Binary

Return Blob, File, ReadableStream or any object exposing { stream(): ReadableStream } to serve application/octet-stream (binary data).

TypeScript JavaScriptroutes/binary.tsroutes/binary.ts

import route from "primate/route";

route.get(() => new Blob(["data"]));

import route from "primate/route";

route.get(() => new Blob(["data"]));

Primate attempts to read the source's name and MIME type if available. Use the explicit binary handler for more options.

TypeScript JavaScriptroutes/binary.tsroutes/binary.ts

import binary from "primate/response/binary";
import route from "primate/route";

route.get(() => binary(new Blob(["data"]), {
  // set filename manually
  headers: { "Content-Disposition": "attachment; filename=data.bin" },
}));

import binary from "primate/response/binary";
import route from "primate/route";

route.get(() => binary(new Blob(["data"]), {
  // set filename manually
  headers: { "Content-Disposition": "attachment; filename=data.bin" },
}));

Use rcompat's FileRef to conveniently load a file from disk and stream it out.

TypeScript JavaScriptroutes/binary.tsroutes/binary.ts

import FileRef from "@rcompat/fs/FileRef";
import route from "primate/route";

route.get(() => new FileRef("/tmp/data.bin"));

import FileRef from "@rcompat/fs/FileRef";
import route from "primate/route";

route.get(() => new FileRef("/tmp/data.bin"));

Redirect

Return a URL to redirect to another address.

TypeScript JavaScriptroutes/redirect.tsroutes/redirect.ts

import route from "primate/route";

route.get(() => new URL("https://example.com/login"));

import route from "primate/route";

route.get(() => new URL("https://example.com/login"));

Use the explicit redirect handler to vary the status or for local redirects.

TypeScript JavaScript Go Python Ruby Grainroutes/redirect.tsroutes/redirect.tsroutes/redirect.goroutes/redirect.pyroutes/redirect.rbroutes/redirect.gr

import Status from "@rcompat/http/Status";
import response from "primate/response";
import route from "primate/route";

route.get(() => response.redirect("https://primate.run", Status.SEE_OTHER));

route.post(request => response.redirect(`/login?next=${request.target}`));

import Status from "@rcompat/http/Status";
import response from "primate/response";
import route from "primate/route";

route.get(() => response.redirect("https://primate.run", Status.SEE_OTHER));

route.post(request => response.redirect(`/login?next=${request.target}`));

package main

import (
	"github.com/primate-run/go/response"
	"github.com/primate-run/go/route"
)

var _ = route.Get(func(_ route.Request) any {
	return response.Redirect("https://primate.run", 303)
})

var _ = route.Post(func(_ route.Request) any {
	return response.Redirect("/login")
})

from primate import Response, Route


@Route.get
def get(request):
    return Response.redirect("https://primate.run", 303)


@Route.post
def post(request):
    return Response.redirect("/login")

require 'primate/route'
require 'primate/response'

Route.get do |request|
  Response.redirect('https://primate.run', 303)
end

Route.post do |request|
  Response.redirect('/login')
end

module RedirectStatus

from "primate/request" include Request
from "primate/response" include Response

use Response.{ type Response, type HTTPStatus }
use Request.{ type Request }

provide let get = (request: Request) =>
  Response.redirect("https://primate.run", status = Some(SeeOther))

provide let post = (request: Request) => Response.redirect("/login")

View

Render and serve components from the components directory as text/html.

TypeScript JavaScript Go Python Ruby Grainroutes/index.tsroutes/index.jsroutes/index.goroutes/index.pyroutes/index.rbroutes/index.gr

import response from "primate/response";
import route from "primate/route";

route.get(() => response.view("Counter.jsx"));

import response from "primate/response";
import route from "primate/route";

route.get(() => response.view("Counter.jsx"));

package main

import (
	"github.com/primate-run/go/response"
	"github.com/primate-run/go/route"
)

var _ = route.Get(func(request route.Request) any {
	return response.View("Counter.jsx")
})

from primate import Response, Route


@Route.get
def get(request):
    return Response.view("Counter.jsx")

require 'primate/route'
require 'primate/response'

Route.get do |request|
  Response.view('Counter.jsx')
end

module View

from "primate/request" include Request
from "primate/response" include Response

use Response.{ type Response }
use Request.{ type Request }

provide let get = (request: Request) => {
  Response.view("Counter.jsx")
}

Props

Populate the component with initial props.

TypeScript JavaScript Go Python Ruby Grainroutes/index.tsroutes/index.jsroutes/index.goroutes/index.pyroutes/index.rbroutes/index.gr

import response from "primate/response";
import route from "primate/route";

route.get(request => response.view("Counter.jsx", { start: 10 }));

import response from "primate/response";
import route from "primate/route";

route.get(() => response.view("Counter.jsx", { start: 10 }));

package main

import (
	"github.com/primate-run/go/core"
	"github.com/primate-run/go/response"
	"github.com/primate-run/go/route"
)

var _ = route.Get(func(request route.Request) any {
	return response.View("Counter.jsx", core.Dict{"start": 10})
})

from primate import Response, Route


@Route.get
def get(request):
    return Response.view("Counter.jsx", {"start": 10})

require 'primate/route'
require 'primate/response'

Route.get do |request|
  Response.view('Counter.jsx', start: 10)
end

module View

from "primate/request" include Request
from "primate/response" include Response
from "json" include Json

use Response.{ type Response }
use Request.{ type Request }

provide let get = (request: Request) => Response.view(
  "Counter.jsx",
  props = JsonObject([("hello", JsonNumber(10))]),
)

Page

Components are embedded into your app's main HTML page at pages/app.html, with the component code replacing the %body% placeholder. If the app page doesn't exist, Primate falls back to its standard one.

<!doctype html>
<html>
  <head>
    <title>Primate app</title>
    <meta charset="utf-8" />
    %head%
  </head>
  <body>%body%</body>
</html>

Pass a different page option to use another HTML page.

import response from "primate/response";
import route from "primate/route";

route.get(() => response.view("Counter.jsx", { start: 10 },
  { page: "counter.html" })); // render into `pages/counter.html`

Placeholders

You can use placeholders in your HTML pages.

<!doctype html>
<html>

<head>
  <title>%title%</title>
  <meta charset="utf-8" />
  %head%
</head>

<body>%body%</body>

</html>

Populate them in your routes.

import response from "primate/response";
import route from "primate/route";

route.get(() => response.view("Counter.jsx", { start: 10 }, {
  placeholders: {
    title: "Counter",
  },
}));

Partial

Pass a partial: true option to render the component without the enclosing HTML page.

import response from "primate/response";
import route from "primate/route";

// will render Counter without embedding it into pages/app.html
route.get(() => response.view("Counter.jsx", { start: 10 }, { partial: true }));

This is useful for replacing parts of the page whilst retaining the HTML page.

Error

Serve a 404 Not Found error page as text/html.

TypeScript JavaScript Go Python Ruby Grainroutes/not-found.tsroutes/not-found.jsroutes/not-found.goroutes/not-found.pyroutes/not-found.rbroutes/not-found.gr

import response from "primate/response";
import route from "primate/route";

route.get(() => response.error({ body: "Not Found" }));

import response from "primate/response";
import route from "primate/route";

route.get(() => response.error({ body: "Not Found" }));

package main

import (
	"github.com/primate-run/go/response"
	"github.com/primate-run/go/route"
)

var _ = route.Get(func(request route.Request) any {
	return response.Error(map[string]any{
		"body": "Not Found",
	})
})

from primate import Response, Route


@Route.get
def get(request):
    return Response.error({"body": "Not Found"})

require 'primate/route'
require 'primate/response'

Route.get do |request|
  Response.error(body: 'Not Found')
end

module Error

from "primate/request" include Request
from "primate/response" include Response
from "json" include Json

use Response.{ type Response }
use Request.{ type Request }

provide let get = (request: Request) => Response.error(JsonObject([
  ("body", JsonString("Not Found"))
]))

This handler uses the HTML file at pages/error.html or falls back to a standard one provided by Primate.

<!doctype html>
<html>
  <head>
    <title>Error page</title>
    <meta charset="utf-8" />
    %head%
  </head>
  <body>
    <h1>Error page</h1>
    <p>
      %body%
    </p>
  </body>
</html>

You can pass a custom status to this handler.

TypeScript JavaScript Go Python Ruby Grainroutes/error.tsroutes/error.jsroutes/error.goroutes/error.pyroutes/error.rbroutes/error.gr

import Status from "@rcompat/http/Status";
import response from "primate/response";
import route from "primate/route";

route.get(request => response.error({
  status: Status.INTERNAL_SERVER_ERROR,
}));

import Status from "@rcompat/http/Status";
import response from "primate/response";
import route from "primate/route";

route.get(request => response.error({
  status: Status.INTERNAL_SERVER_ERROR,
}));

package main

import (
	"github.com/primate-run/go/core"
	"github.com/primate-run/go/response"
	"github.com/primate-run/go/route"
)

var _ = route.Get(func(request route.Request) any {
	return response.Error(core.Dict{"status": 500})
})

from primate import Response, Route


@Route.get
def get(request):
    return Response.error({"status": 500})

require 'primate/route'
require 'primate/response'

Route.get do |request|
  Response.error(status: 500)
end

module ErrorOptions

from "primate/request" include Request
from "primate/response" include Response

use Response.{ type Response }
use Request.{ type Request }

provide let get = (request: Request) =>
  Response.error(status = Some(500))

As with view, you can pass a different page option to use another HTML page.

import response from "primate/response";
import route from "primate/route";

// use pages/custom-error.html instead of pages/error.html
route.get(() => response.error({ page: "custom-error.html" }));

WebSocket

Upgrade a GET request to ws: and handle open, message, and close events.

import response from "primate/response";
import route from "primate/route";

route.get(() => response.ws({
  open(socket) {
    socket.send("hello");
  },
  message(socket, message) {
    // echo
    socket.send(String(message));
  },
  close(socket) {
    console.log("socket closed");
  },
}));

Server‑sent events

Push out events to the client as text/event-stream.

import response from "primate/response";
import route from "primate/route";

route.get(() => response.sse({
  // connection opened
  open(source) {
    // push event to client
    source.send("open", "hi!");
  },
  // connection closed
  close() { },
}));

Response

Return a custom Response.

import Status from "primate/response/Status";
import route from "primate/route";

route.get(() => new Response("Hi!", {
  status: Status.ACCEPTED,
  headers: { "X-Custom": "1" },
}));

`ResponseLike` reference

type ResponseLike =
  | string
  | Record<string, unknown>
  | Record<string, unknown>[]
  | Blob
  | ReadableStream
  | URL
  | null
  | Response
  ;

Requests

Validation

Responses

Text

JSON

Binary

Redirect

View

Props

Page

Placeholders

Partial

Error

WebSocket

Server‑sent events

Response

ResponseLike reference

`ResponseLike` reference