Neolithic Populous Metropolis

    buxt
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.20-alpha • Public • Published


    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

    • [x] Nested routing
    • [x] Route parameters
    • [ ] Catch-all routes on same level as named routes
    • [x] Implement response handling logic fully
    • [ ] Middleware
    • [x] 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.

    Install

    npm i buxt

    DownloadsWeekly Downloads

    29

    Version

    0.0.20-alpha

    License

    MIT

    Unpacked Size

    125 kB

    Total Files

    18

    Last publish

    Collaborators

    • miaz