buxt

Lightweight filesystem-based router for creating REST APIs.

Note

This project is currently very early development, and I wouldn't recommend it for production. Feel free to use it as you like and if you find any problems then submit an issue via github issues tab.

Features/Roadmap

• Nested routing
• Route parameters
• Catch-all routes on same level as named routes
• Implement response handling logic fully
• Middleware
• CORS solution
• Advanced Logging
• Authentication
• Websockets
• ESLint plugin

Installation

bun a buxt

Getting started

Starting a basic server with the default values

//index.ts
import CreateServer from "buxt";

await CreateServer(3000).then(s => s.listen());

//routes/example_endpoint.ts
import type { BuxtRequest, BuxtResponse } from "buxt"; //typings arent required, but useful!

export default async function(req: BuxtRequest, res: BuxtResponse) {
    res.send("Hello!");
}

Thats it!

Usage

By default, the app will search for exported functions under <project-root>/routes and <project-root>/src/routes, unless specified when creating the server.

Aside from the previous example, there are three other ways of creating and starting a buxt server:

Create a server with default route root using port 3000

//index.ts
import CreateServer from "buxt";

const server = await CreateServer(3000);
await server.listen();

Create a server with default route root using port 3000 and a custom root route path

//index.ts
import CreateServer from "buxt";

const server = await CreateServer(3000, "src/api");
await server.listen();

Create a server with config object

//index.ts
import CreateServer from "buxt";

const server = await CreateServer({
    port: 3000,
    routeRoot: "api",
    cors: true,
    corsConfig: {
        origins: [ "*" ]
    }
});
await server.listen();

Definitions for config

type BuxtConfig = {
    port: number,
    routeRoot: string,
    cors?: boolean = false,
    corsConfig?: CorsConfig = null
}

type CorsConfig = {
    origins: string[],
    allowedMethods?: HttpMethod[] = ["GET", "OPTIONS", "POST"]
}

type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "HEAD" | "PATCH";

Route parameters

Route parameters work like they do in Next.js - they're denoted by a variable name surrounded by square brackets, eg: routes/user/[user].ts

They can then be accessed on the BuxtRequest object under req.routeParameters.{variable_name}

//routes/user/[user].ts
import type { BuxtRequest, BuxtResponse } from "buxt";

export default async function(req: BuxtRequest, res: BuxtResponse) {
    res.send("Hello " + req.routeParameters.user);
}

Enabling Cors

You must create a server using a config object to enable cors responses.

//index.ts
import CreateServer from "buxt";

const server = await CreateServer({
    port: 3000,
    routeRoot: "api",
    cors: true,
    corsConfig: {
        origins: [ "localhost:3000", "localhost:3001", "https://miaz.xyz/", "http://miaz.xyz" ],
        allowedMethods: [ "GET", "POST", "OPTIONS", "PUT", "DELETE"]
    }
});

Firstly, make sure the cors key is set to true, then pass in a CorsConfig object. The CorsConfig's origins key cannot be null. If you're allowing all origins then simply make it a single item array with ["*"].

Reminder that you cannot combine wildcard routes and non-wildcard routes; if you attempt to do this then it will throw an error.

Big thanks to lau1994 and their project Bunrest (really nice express-like server built for Bun) which has helped me a lot getting this project started.