Skip to content
This repository was archived by the owner on May 6, 2023. It is now read-only.
/ buxt Public archive

HTTP/REST server for Bun that uses filesystem based routing

Notifications You must be signed in to change notification settings

mia-z/buxt

Folders and files

NameName
Last commit message
Last commit date
Nov 10, 2022
Nov 5, 2022
Nov 10, 2022
Nov 3, 2022
Nov 10, 2022
Nov 9, 2022
Nov 10, 2022
Nov 10, 2022
Nov 9, 2022
Nov 10, 2022
Nov 9, 2022
Nov 10, 2022
Nov 10, 2022
Nov 5, 2022

Repository files navigation


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 using port 3000 with default route root

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

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

Create a server 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.