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)

// 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.

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 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.

// websocket.ts
import type { WebSocketHandler } from "bun";

export const BunextWebsocket: WebSocketHandler<any> = {
    message(ws, message) {
        console.log(`WS Message => ${message}`);
    },
};

// 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.

4.5 KiB Raw Blame History