139 lines
4.5 KiB
Markdown
139 lines
4.5 KiB
Markdown
# Bunext — Planned Features
|
|
|
|
Features currently in development or planned for a future release.
|
|
|
|
---
|
|
|
|
## Middleware Request Mutation
|
|
|
|
**Status:** Planned (soon)
|
|
|
|
Extend the `middleware` function in `bunext.config.ts` to support returning a `Request` object. This allows the middleware to modify the incoming request — inject headers, attach auth context, set locale — and continue through the normal routing pipeline without short-circuiting.
|
|
|
|
The full return contract:
|
|
|
|
| Return value | Behaviour |
|
|
|---|---|
|
|
| `Response` | Short-circuits — response sent immediately, no further routing |
|
|
| `Request` | Replaces the original request and continues through the pipeline |
|
|
| `undefined` | Passes through unchanged (current behaviour) |
|
|
|
|
```ts
|
|
// bunext.config.ts
|
|
const config: BunextConfig = {
|
|
middleware: async ({ req, url }) => {
|
|
// Inject an auth header and continue
|
|
const token = await verifySession(req);
|
|
if (token) {
|
|
const mutated = new Request(req, {
|
|
headers: {
|
|
...Object.fromEntries(req.headers),
|
|
"x-user-id": token.userId,
|
|
},
|
|
});
|
|
return mutated;
|
|
}
|
|
|
|
// Short-circuit if not authenticated on protected routes
|
|
if (url.pathname.startsWith("/dashboard")) {
|
|
return Response.redirect("/login", 302);
|
|
}
|
|
|
|
// Otherwise continue unchanged
|
|
return undefined;
|
|
},
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Custom Server
|
|
|
|
**Status:** Shipped
|
|
|
|
Consumer projects can create and fully customize the underlying `Bun.serve()` instance by using Bunext's exported primitives directly. Instead of Bunext owning the server, the developer provides their own `Bun.serve()` call and integrates Bunext's request handler into it.
|
|
|
|
```ts
|
|
import bunext from "bunext";
|
|
|
|
await bunext.bunextInit();
|
|
|
|
const server = Bun.serve({
|
|
routes: {
|
|
"/*": {
|
|
async GET(req) {
|
|
return await bunext.bunextRequestHandler({ req });
|
|
},
|
|
},
|
|
},
|
|
port: 3000,
|
|
});
|
|
```
|
|
|
|
Exported primitives:
|
|
|
|
| Export | Description |
|
|
|--------|-------------|
|
|
| `bunextInit()` | Initializes config, router, and bundler |
|
|
| `bunextRequestHandler({ req })` | Main Bunext request dispatcher |
|
|
| `bunextLog` | Framework logger |
|
|
|
|
Use cases:
|
|
- Custom WebSocket upgrade handling
|
|
- Custom TLS/SSL configuration
|
|
- Integrating Bunext into an existing Bun server alongside other handlers
|
|
- Custom `error` and `lowMemoryMode` options on `Bun.serve()`
|
|
|
|
---
|
|
|
|
## Sass / SCSS Support
|
|
|
|
**Status:** Planned
|
|
|
|
Add Sass/SCSS support by integrating the `esbuild-sass-plugin` package into the ESBuild pipeline alongside the existing Tailwind plugin. ESBuild does not handle `.scss`/`.sass` files natively — the plugin intercepts those file loads, compiles them via Dart Sass, and returns standard CSS to ESBuild.
|
|
|
|
Implementation is straightforward: install `esbuild-sass-plugin`, add it to the plugins array in `allPagesBundler` and `writeHMRTsxModule`. No changes to the rest of the pipeline — CSS extraction, per-page bundling, and HMR CSS swapping all work the same way.
|
|
|
|
---
|
|
|
|
## Static Export (`bunext export`)
|
|
|
|
**Status:** Planned (low priority)
|
|
|
|
Add a `bunext export` command that pre-renders all pages to static HTML files, deployable to a CDN without a running server. This is a convenience feature for projects that have no dynamic server-side requirements.
|
|
|
|
A server is a fundamental requirement for Bunext — like WordPress, it is designed to run on a server. Static export is a secondary capability for edge cases, not a primary deployment model.
|
|
|
|
---
|
|
|
|
## WebSocket Support via Config
|
|
|
|
**Status:** Shipped
|
|
|
|
The `websocket` field in `bunext.config.ts` accepts a Bun [`WebSocketHandler`](https://bun.sh/docs/api/websockets) and passes it directly to `Bun.serve()`. This gives most projects a zero-config path to WebSockets; the custom server feature covers advanced upgrade routing.
|
|
|
|
```ts
|
|
// websocket.ts
|
|
import type { WebSocketHandler } from "bun";
|
|
|
|
export const BunextWebsocket: WebSocketHandler<any> = {
|
|
message(ws, message) {
|
|
console.log(`WS Message => ${message}`);
|
|
},
|
|
};
|
|
```
|
|
|
|
```ts
|
|
// bunext.config.ts
|
|
import type { BunextConfig } from "bunext/src/types";
|
|
import { BunextWebsocket } from "./websocket";
|
|
|
|
const config: BunextConfig = {
|
|
websocket: BunextWebsocket,
|
|
};
|
|
|
|
export default config;
|
|
```
|
|
|
|
A companion `serverOptions` field is also available to pass any other `Bun.serve()` options (TLS, error handler, `maxRequestBodySize`, etc.) without needing a custom server.
|