Custom Server

Bun Custom Server

By default, Brisa includes its own server with brisa start. If you have an existing backend, you can still use it with Brisa (this is not a custom server). A custom Brisa server allows you to start a server 100% programmatically in order to use custom server patterns. Most of the time, you will not need this - but it's available for complete customization.

Take a look at the following example of a custom server:

import { getServeOptions, serve } from "brisa/server";

const { server, port, hostname } = serve({
  ...await getServeOptions(),
  port: 3001,
});

console.log(
  "Server ready 🥳",
  `listening on http://${hostname}:${port}...`,
);

If you want a custom handler, you can use the following:

import { getServeOptions, serve } from "brisa/server";

const serveOptions = await getServeOptions();

const { server, port, hostname } = serve({
  fetch(req, server) {
    // Your implementation here ...

    // Brisa handler
    return serveOptions.fetch(req, server);
  },
  port: 3001,
});

See all Bun.serve options in Bun.js docs.

To run the custom server you'll need to update the scripts in package.json like so:

{
  "scripts": {
    "dev": "brisa build --dev && bun server.ts",
    "build": "brisa build",
    "start": "NODE_ENV=production bun server.ts"
  }
}

By default (without custom server) is:

{
  "scripts": {
    "dev": "brisa dev",
    "build": "brisa build",
    "start": "brisa start"
  }
}

If you use a custom server you need to handle clustering yourself.

If you use a different runtime than Bun, like Node.js, you need to handle the WebSockets, HTTP/2, and other features yourself re-using the serveOptions.

Node.js Custom Server

If you want to use a custom server with Node.js, you can use:

import http from "node:http";
import { handler } from "brisa/server/node";

const server = http.createServer(handler).listen(3001);

You can use the serve function from brisa/server/node for the same behavior:

import { serve } from "brisa/server/node";

const {server, port, hostname} = serve({ port: 3001 });

If you want to use a custom handler, you can use the Brisa handler function after your custom handler:

import http from "node:http";
import { handler } from "brisa/server/node";

const customHandler = (req, res) => {
  res.end("Hello World");
};

const server = http.createServer((req, res) => {
  customHandler(req, res);
  handler(req, res);
}).listen(3001);

If you use a Custom Server you need to handle the WebSockets, HTTP/2, and other features yourself re-using the serveOptions.

To use the serveOptions you can use the following:

import { getServeOptions } from "brisa/server";

const serveOptions = await getServeOptions();

If you use a custom server you need to handle clustering yourself.

To run the custom server you'll need to update the scripts in package.json like so:

{
  "scripts": {
    "dev": "brisa build --dev && node server.ts",
    "build": "brisa build",
    "start": "NODE_ENV=production node server.ts"
  }
}

By default (without custom server) is:

{
  "scripts": {
    "dev": "brisa dev",
    "build": "brisa build",
    "start": "brisa start"
  }
}