Bun + SolidJS SSR in Production: The Boring Stack

Explore a stable, high-performance stack for server-side rendering: Bun and SolidJS. This guide details setting up Bun with SolidJS SSR for robust production applications.

In the fast-evolving JavaScript ecosystem, the desire for the "next big thing" often overshadows the reliability of established or steadily maturing tools. For server-side rendered (SSR) applications, achieving predictable performance and maintainability is often prioritized over chasing experimental features. This post outlines a pragmatic approach to building production-ready SSR applications using Bun and SolidJS.

Bun provides a fast JavaScript runtime and a comprehensive toolkit, while SolidJS offers exceptional performance and a highly optimized reactivity system. Together, they form a robust, albeit "boring," stack suitable for demanding production environments.

Why Bun for SSR?

Bun is an all-in-one JavaScript toolkit that includes a runtime, package manager, and bundler. Its key advantages for SSR include:

Speed: Bun's JavaScript runtime is significantly faster than Node.js in many common benchmarks, leading to quicker server response times and improved cold start performance for serverless deployments.
Built-in Features: It simplifies the development environment by integrating a bundler (supporting TypeScript and JSX out-of-the-box) and a package manager. This reduces configuration overhead and dependency bloat.
Web Standard APIs: Bun implements many Web APIs natively, making code more portable and easier to write. This includes fetch, WebSocket, and ReadableStream.

For SSR, these benefits translate directly into faster page loads and a more streamlined deployment process.

Why SolidJS for SSR?

SolidJS is a declarative JavaScript library for creating user interfaces, similar to React, but with a different rendering model that yields superior performance.

Fine-grained Reactivity: SolidJS compiles templates directly to DOM operations and uses fine-grained reactivity, updating only the parts of the UI that change. This minimizes runtime overhead on the client.
No Virtual DOM: Unlike React, SolidJS does not use a virtual DOM. This eliminates reconciliation overhead, resulting in faster updates and a smaller client-side bundle size.
Efficient Hydration: SolidJS's SSR mechanism produces highly optimized HTML and efficiently hydrates the client-side application. It only ships the necessary JavaScript to make the page interactive, avoiding unnecessary re-renders.
Developer Experience: While its reactivity model is different, SolidJS offers a familiar JSX syntax and component-based architecture, making it approachable for developers coming from React or similar libraries.

When combined, Bun's speed and SolidJS's efficiency create a powerful foundation for SSR applications.

Setting Up the Project

To get started, initialize a new Bun project:

bun init -y

Install SolidJS and its SSR dependencies:

bun add solid-js solid-start solid-start-node
bun add -d @types/node @types/bun

solid-start is SolidJS's framework for building web applications, providing features like routing and SSR helpers. solid-start-node is the adapter for Node.js environments, which Bun can largely run.

Building the SSR Application

Create an src/index.tsx file for your SolidJS application:

// src/index.tsx
import { renderToString } from "solid-js/web";
import { App } from "./app";

export function render() {
  return renderToString(() => <App />);
}

And src/app.tsx for your main SolidJS component:

// src/app.tsx
import { createSignal } from "solid-js";

export function App() {
  const [count, setCount] = createSignal(0);

  return (
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>Bun + SolidJS SSR</title>
      </head>
      <body>
        <h1>Welcome to SolidJS on Bun!</h1>
        <p>Count: {count()}</p>
        <button onClick={() => setCount(count() + 1)}>Increment</button>
      </body>
    </html>
  );
}

Now, create a server file, server.ts, that will use Bun's HTTP server and render your SolidJS application.

// server.ts
import { render } from "./src/index";

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);

    if (url.pathname === "/") {
      const html = render();
      return new Response(html, {
        headers: { "Content-Type": "text/html" },
      });
    }

    // Serve static assets (e.g., client-side JS, CSS)
    // For a real app, you'd want a proper build step for client assets
    // and a more robust static file handler.
    return new Response("Not Found", { status: 404 });
  },
});

console.log(`Listening on http://localhost:${server.port}`);

To run the server:

bun run server.ts

This setup provides the basic SSR functionality. For a complete application with client-side hydration, routing, and proper asset handling, you would typically use solid-start's build system. solid-start itself is designed to abstract away much of this complexity, but understanding the underlying mechanisms is crucial.

Considerations for Production Deployment

While the basic setup is straightforward, deploying to production requires additional considerations:

Client-Side Hydration: The example above only renders HTML. For interactivity, you'll need to compile a client-side JavaScript bundle and include it in your HTML, then hydrate your SolidJS application on the client. solid-start handles this automatically.
Static Asset Serving: In production, you'll want an efficient way to serve static files (CSS, images, client-side JavaScript). This can be done by a web server like Nginx or by integrating a static file server within your Bun application (though external web servers are often preferred for performance).
Bundling for Production: Even with Bun's built-in bundler, optimizing client-side assets for size and performance is essential. solid-start provides build commands that generate optimized client and server bundles.
Error Handling and Logging: Implement robust error handling for both server-side rendering and API routes. Integrate a logging solution for monitoring.
Environment Variables: Manage configuration using environment variables, injecting them into your Bun process during deployment.
Containerization: Packaging your application in a Docker container simplifies deployment and ensures consistency across environments.

Using solid-start is recommended for most projects as it abstracts away much of the build and deployment complexity, providing a structured way to build SolidJS applications with SSR. It leverages Vite for bundling, which works well with Bun.

The "Boring" Advantage

The combination of Bun and SolidJS delivers a predictable, high-performance foundation. It's "boring" in the best sense: reliable, efficient, and free from excessive complexity or constant paradigm shifts. This allows development teams to focus on application logic and user experience rather than wrestling with tooling or chasing the latest JavaScript framework trend.

Takeaway: For maintainers prioritizing stability, performance, and a streamlined development experience in SSR applications, Bun and SolidJS offer a robust and highly capable solution. This stack gets out of the way, letting you build fast web experiences with confidence.