Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mia-z/buxt
HTTP/REST server for Bun that uses filesystem based routing
https://github.com/mia-z/buxt
bun bunjs rest rest-api routing typescript
Last synced: 3 months ago
JSON representation
HTTP/REST server for Bun that uses filesystem based routing
- Host: GitHub
- URL: https://github.com/mia-z/buxt
- Owner: mia-z
- Archived: true
- Created: 2022-11-03T10:59:49.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2022-11-10T14:19:13.000Z (about 2 years ago)
- Last Synced: 2024-04-24T13:17:57.148Z (8 months ago)
- Topics: bun, bunjs, rest, rest-api, routing, typescript
- Language: TypeScript
- Homepage:
- Size: 111 KB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
---
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
``` typescript
//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 \/routes and \/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
``` typescript
//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
``` typescript
//index.ts
import CreateServer from "buxt";
const server = await CreateServer(3000, "src/api");
await server.listen();
```
### Create a server with config object
``` typescript
//index.ts
import CreateServer from "buxt";
const server = await CreateServer({
port: 3000,
routeRoot: "api",
cors: true,
corsConfig: {
origins: [ "*" ]
}
});
await server.listen();
```
### Definitions for config
``` typescript
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}`
``` typescript
//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.
``` typescript
//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.