Skip to main content


Elevate your Robo.js project with @robojs/server, a powerful plugin that provides an effortless way to create and manage web routes. This guide will walk you through the essentials of setting up and using the API plugin.

Heads up! RoboPlay Pods are currently optimized for bots and do not support API servers. This will be supported in the coming weeks.

Installation 💻

To add this plugin to your Robo.js project:

npx robo add @robojs/server

New to Robo.js? Start your project with this plugin pre-installed:

npx create-robo <project-name> -p @robojs/server

Getting Started

Create a new API route by adding a file in /src/api. For example, creating hello.js with the following content:

export default () => {
return 'Hello World!'

Now, run your Robo and visit http://localhost:3000/api/hello to see the route in action.


Routes are created based on your file structure within /src/api. The path to the file translates to the route URL. For example:

  • test.js/api/test
  • auth/sign-in.js/api/auth/sign-in
  • user/[id]/dashboard.js/api/user/:id/dashboard

Default routes are prefixed with /api. You can modify this prefix in the plugin's config file by setting the prefix field to null or false.


Each route file should export a default function. This function handles HTTP requests and can return a response directly.

The function receives two parameters: request and reply. These objects provide methods to interact with the request and response.

Example 1: Simple GET request

export default (request, reply) => {
if (request.method !== 'GET') {
throw new Error('Method not allowed')

const userId =

// ... perform some action with userId

return { message: `User ID is ${userId}` }

Example 2: POST request with body parsing

export default (request, reply) => {
if (request.method !== 'POST') {
reply.status(405).send('Method not allowed')

const userData = request.body

// ... interact with database, e.g., Prisma

reply.status(200).send(JSON.stringify({ success: true, userData }))

Returning a value from the route function will automatically send a response with the value as the body. The same is true for throwing an error.

If you need to manually send a response, use the reply object. This object provides methods to set the status code, headers, and body.

Don't want to use Robo's wrappers? Access the raw request and response objects using request.req and reply.res.

Throwable Responses

Did you know that throwing an error in your route function will automatically send a response with the error message? This is a handy way to handle errors in your API routes.

export default (request, reply) => {
if (!request.query.key) {
throw new Error('API key is required')

// ... perform some action with the key

return { message: 'Success!' }

What's more, you can customize the response by throwing a RoboResponse object. This object allows you to set the status code, headers, and body of the response.

export default (request, reply) => {
if (!request.query.key) {
throw new RoboResponse({
statusCode: 401,
headers: { 'WWW-Authenticate': 'Bearer' },
body: 'Unauthorized'

// ... perform some action with the key

return { message: 'Success!' }

API Reference

Here's a detailed breakdown of the methods and properties available in the request and reply objects, along with their TypeScript types:


reqIncomingMessageRaw request object.
bodyT (generic, default: Record<string, unknown>)Access the request body.
methodHttpMethodGet the HTTP method.
queryRecord<string, string | string[]>Access query parameters.
paramsRecord<string, unknown>Get URL parameters.


resServerResponseRaw response object.
code(statusCode: number) => RoboReplySet the HTTP status code.
send(data: string) => RoboReplySend the response content.
header(name: string, value: string) => RoboReplySet a response header.
hasSentbooleanIndicates if the response has been sent.

These types can be imported from the plugin's package for enhanced TypeScript support.

import type { RoboRequest, RoboReply } from '@robojs/server'

Plugin Configuration

Customize your API plugin using these config fields:

Config FieldTypeDescription
portnumberThe port on which the server will listen.
prefixstring/falseCustom URL prefix for routes or disable it.
engineBaseServerCustom server engine implementation.


export default {
port: 5000, // Custom port
prefix: false, // Disable the '/api' prefix
engine: CustomServer // Custom server engine

In this configuration, port is set to 5000, prefix is disabled (routes will not have the /api prefix), and a custom server engine is specified.

Alternatively, use the PORT environment variable.

Server Engine

The API plugin uses Node's http module by default. If you have Fastify installed, it will automatically switch to Fastify for enhanced performance.

You can create your own server engine by extending the BaseServer class and implementing its abstract methods. Then, specify your custom server engine in the plugin's config file.

More on GitHub

Robo.js Logo

MIT © 2024 Robo.js By WavePlay