Backend

@robojs/server provides file-based HTTP routing (your file names and folder structure automatically become endpoints) for your activity's server-side logic. Files in /src/api become API endpoints.

VS Code file explorer showing the src/api directory expanded with route files like hello.ts, token.ts, and a users subdirectory with [id].ts, illustrating file-based routing

FocusThe src/api directory structure showing file-to-route mappingZoom100%NotesShow VS Code file explorer with src/api expanded: hello.ts, token.ts, data.ts, and users/[id].ts. Demonstrates the file-based routing concept.

Creating Routes

Each file in src/api/ maps to an endpoint. The file name determines the route path. For example, src/api/hello.ts becomes GET /api/hello.

hello.tsGET /api/hello

data.tsPOST /api/data

[id].ts/api/users/:id

Return a string or object from the default export:

src/api/hello.ts

export default () => {
  return { message: 'Hello, world!' }
}

src/api/hello.js

export default () => {
  return { message: 'Hello, world!' }
}

Request and Response

Use RoboRequest to read query parameters, body, and headers. Return an object for JSON responses, or use RoboResponse for custom status codes and headers:

src/api/data.ts

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

export default async (req: RoboRequest) => {
  const body = await req.json()
  return { received: body }
}

src/api/data.js

export default async (req) => {
  const body = await req.json()
  return { received: body }
}

Access query parameters through req.query and URL parameters through req.params.

The Token Endpoint

Every activity template includes src/api/token.ts, which exchanges an OAuth2 authorization code for an access token while keeping your client secret secure on the server. See Authentication for the full implementation and details on the OAuth2 flow.

Nested Routes

Create subdirectories for nested route paths. Dynamic segments use [param] syntax in the file name:

File path	Route
`src/api/users.ts`	`/api/users`
`src/api/users/[id].ts`	`/api/users/:id`
`src/api/guilds/[guildId]/members.ts`	`/api/guilds/:guildId/members`

Access dynamic parameters through req.params:

src/api/users/[id].ts

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

export default (req: RoboRequest) => {
  const { id } = req.params
  return { userId: id }
}

src/api/users/[id].js

export default (req) => {
  const { id } = req.params
  return { userId: id }
}

Browser or API client showing a JSON response from /api/users/123, returning { userId: '123' }, demonstrating dynamic route parameters

FocusThe API response showing the dynamic parameter extracted from the URLZoom100%NotesShow browser or DevTools hitting localhost:3000/api/users/123 displaying { userId: '123' }. Demonstrates dynamic segments.

HTTP Methods

The default export handles all HTTP methods. Use named exports for method-specific handlers:

src/api/users.ts

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

export const GET = () => {
  return { users: [] }
}

export const POST = async (req: RoboRequest) => {
  const body = await req.json()
  return { created: body }
}

src/api/users.js

export const GET = () => {
  return { users: [] }
}

export const POST = async (req) => {
  const body = await req.json()
  return { created: body }
}

Supported named exports: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD.

Server Configuration

Configure the server plugin in config/plugins/robojs/server.ts:

config/plugins/robojs/server.ts

export default {
  port: 3000,
  cors: true
}

config/plugins/robojs/server.js

export default {
  port: 3000,
  cors: true
}

Option	Type	Default	Description
`port`	number	3000	Server port
`cors`	boolean	false	Enable CORS
`prefix`	string	`/api`	Route prefix

The PORT environment variable overrides the port option.

Next Steps

Frontend

Client-side development with Vite.

Authentication

Authenticate users in your activity.

Multiplayer

Add real-time multiplayer with state sync.