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, server }) => {
        // 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: In development

Allow consumer projects to create and fully customize the underlying Bun.serve() instance. Instead of Bunext owning the server entirely, the developer can provide their own server setup and integrate Bunext's request handler into it.

This enables use cases that require low-level server control:

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: Planned

Add a websocket parameter to bunext.config.ts to handle WebSocket connections without requiring a custom server. This gives most projects a zero-config path to WebSockets while the custom server feature covers advanced use cases.

Proposed config shape:

// bunext.config.ts
import type { BunextConfig } from "bunext/src/types";

const config: BunextConfig = {
    websocket: {
        message(ws, message) {
            ws.send(`echo: ${message}`);
        },
        open(ws) {
            console.log("Client connected");
        },
        close(ws, code, reason) {
            console.log("Client disconnected");
        },
    },
};

export default config;

The websocket field maps directly to Bun's WebSocketHandler interface, passed through to Bun.serve(). WebSocket upgrade requests are handled automatically by the framework before the normal request pipeline runs.

4.0 KiB Raw Blame History