Skip to main content

@robojs/server

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:

Terminal
npx robo add @robojs/server

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

Terminal
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.

Routing​

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.

Usage​

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 = request.params.id

	// ... perform some action with userId

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

Example 2: POST request with body parsing

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

	const userData = await request.json()

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

	reply.code(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. It has the same effect as returning it.

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 RoboResponse.json({ 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.

Server​

The Server object can be used to get the underlying server configuration, engine instance, and wait for it to be ready.

import { Server } from '@robojs/server'

export default async () => {
	// Get the server configuration
	console.log('Config:', Server.config())

	// Get the server engine instance
	console.log('Engine:', Server.get())

	// Wait for the server to be ready
	await Server.ready()
}

RoboRequest​

RoboRequest extends the Web Request API and provides additional properties and methods for handling requests.

Method/PropertyTypeDescription
reqIncomingMessageRaw request object.
jsonunknownParse the request body as JSON.
methodHttpMethodGet the HTTP method.
queryRecord<string, string | string[]>Access query parameters.
paramsRecord<string, unknown>Get URL parameters.

Reply​

Method/PropertyTypeDescription
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
hostnamestringThe hostname on which the server will run.
portnumberThe port on which the server will listen.
prefixstring/falseCustom URL prefix for routes or disable it.
engineBaseServerCustom server engine implementation.

Example:

config/plugins/robojs/server.mjs
// File: /config/plugins/robojs/server.mjs
export default {
	hostname: '0.0.0.0', // Defaults to 'localhost'
	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​