Skip to main content
Bun is a fast, modern JavaScript runtime built with Zig and powered by the JavaScriptCore engine. It focuses on high performance, offering quick startup times, fast package installs, and a built-in HTTP server. Bun includes a package manager, bundler, test runner, and TypeScript/JSX transpiler out of the box, providing an all-in-one environment for building JavaScript applications. Key features include:
  • Native Bun HTTP server using Bun.serve() .
  • No build step required - TypeScript runs directly.
  • Built-in TypeScript support - No transpilation needed.
  • Fast startup - Instant server boot.
  • Minimal dependencies - Only @types/bun for development.
  • Health check endpoint included.
Bun can only be used on Application Hosting; it cannot be deployed as a static site.

​
Configuration

With Bun, no build step is required. Bun runs TypeScript directly, so you don’t need a separate build command. Sevalla will automatically:
  1. Run bun install to install dependencies.
  2. Execute bun run start to start your server.
The following is an example package.json file for deploying Bun on Sevalla: 
{
  "scripts": {
    "start": "bun run src/index.ts"
  }
}

​
Containerization

​
Dockerfile

The build for Dockerfiles is fully customizable. The Dockerfile below follows best practices for building and running a Bun application in Sevalla. It:
  • Uses official oven/bun image for optimal performance.
  • Installs dependencies with --frozen-lockfile for deterministic builds.
  • Exposes port 3000 by default.
  • Runs the application using bun run start .
  • Excludes unnecessary files via .dockerignore (node_modules, .git, .env, etc.).
FROM oven/bun

WORKDIR /app

COPY package.json ./

RUN bun install --frozen-lockfile

COPY . .

EXPOSE 3000

ENV PORT=3000

CMD ["bun", "run", "start"]

​
Nixpacks

Nixpacks detects Bun projects automatically by locating a package.json and bun.lock file in your application. It then installs the Bun runtime, runs bun install to fetch dependencies, and uses the start script from your package.json file to configure how your application is launched.
You must use Nixpacks v1.39 or newer for proper Bun support. You can set the Nixpacks version within Applications > Application name > Settings > Update build strategy.
When using Nixpacks in Sevalla for your Bun application:
  • Ensure your package.json has a valid start script.
  • Nixpacks respects your bun.lock file for deterministic builds.
  • All standard Sevalla features (CDN, scaling, processes) work with Nixpacks.
  • Nixpacks uses Node 18 by default, but Bun requires Node 22. To ensure compatibility, set the NIXPACKS_NODE_VERSION environment variable to 22.

​
CDN

Sevalla provides a premium, Cloudflare-powered CDN for Application Hosting at no additional cost. To get the most out of Sevalla’s CDN when deploying your Bun application, we recommend the following best practices:
  • Enable the CDN for all production applications to ensure global, low-latency delivery.
  • Set appropriate Cache-Control headers on API routes to ensure proper caching behavior.
  • Purge CDN cache after critical deployments to ensure users receive updated content.
  • Use versioned URLs for static assets (e.g., /static/app.v123.js).

​
Optimizing Bun server for CDN

​
Static files with cache headers

// src/index.ts
const server = Bun.serve({
  port: process.env.PORT || 3000,
  fetch(req) {
    const url = new URL(req.url);

    // Serve static assets with caching
    if (url.pathname.startsWith("/static/")) {
      const file = Bun.file(`./public${url.pathname}`);

      return new Response(file, {
        headers: {
          "Cache-Control": "public, max-age=31536000, immutable",
          "Content-Type": file.type,
        },
      });
    }

    // API endpoint with shorter cache
    if (url.pathname === "/api/data") {
      const data = { message: "Hello from Bun!" };

      return new Response(JSON.stringify(data), {
        headers: {
          "Content-Type": "application/json",
          "Cache-Control": "public, max-age=3600, s-maxage=3600",
        },
      });
    }

    return new Response("Not Found", { status: 404 });
  },
});

​
Edge caching

Edge caching stores your Sevalla site cache on Cloudflare’s 260+ global data centers, delivering responses from the location nearest to each visitor for faster performance. To maximize the benefits of Sevalla’s Edge Caching for your Bun application, we recommend the following best practices:
  • Set appropriate Cache-Control headers in loaders to control caching behavior.
  • Combine edge caching with the CDN for a complete caching strategy.

​
Optimizing Bun for edge caching

// src/index.ts
const server = Bun.serve({
  port: process.env.PORT || 3000,
  fetch(req) {
    const url = new URL(req.url);

    // API with edge caching
    if (url.pathname === "/api/products") {
      const products = getProducts(); // Your data fetching logic

      return new Response(JSON.stringify(products), {
        headers: {
          "Content-Type": "application/json",
          "Cache-Control": "public, max-age=60, s-maxage=3600",
        },
      });
    }

    // User-specific data (don't cache)
    if (url.pathname === "/api/user/profile") {
      return new Response(JSON.stringify({ user: "data" }), {
        headers: {
          "Content-Type": "application/json",
          "Cache-Control": "private, no-cache",
        },
      });
    }

    return new Response("Not Found", { status: 404 });
  },
});

​
Cache-Control

With Sevalla’s Cloudflare integration, Cache-Control headers are respected at the edge, giving you precise control over how content is cached and served globally. The following are some common directives you can use in your Bun application:
  • public, s-maxage=3600 - Caches the response on the CDN for 1 hour, improving performance for frequently accessed content.
  • public, max-age=31536000, immutable - Ideal for versioned static assets, allowing them to be cached for up to 1 year with no revalidation.
  • private - Prevents CDN caching and ensures the response is only cached by the end user’s browser, for personalized or sensitive data.
Sevalla does not yet support the stale-while-revalidate Cache-Control directive. To prevent unexpected caching behavior, we recommend not using this directive in your API or asset caching settings.

​
Health checks

Ensure your application remains available during deployments by implementing health checks:
  • Always implement health checks for production applications.
  • Keep checks lightweight; responses should complete in under 1 second.
  • Verify critical dependencies (e.g., databases, Redis) as part of the checks.
  • Return 200 for degraded states to allow deployments to continue smoothly.
  • Return 503 only for critical failures that require pod restarts.

​
Basic healthcheck

// src/index.ts
const server = Bun.serve({
  port: process.env.PORT || 3000,
  fetch(req) {
    const url = new URL(req.url);

    if (url.pathname === "/api/health") {
      return new Response(
        JSON.stringify({
          status: "ok",
          timestamp: new Date().toISOString(),
          runtime: "Bun",
          version: Bun.version,
        }),
        {
          headers: { "Content-Type": "application/json" },
        }
      );
    }

    return new Response("Not Found", { status: 404 });
  },
});

​
Graceful shutdown

Bun supports graceful shutdown by default. For custom cleanup logic, use SIGTERM and SIGINT , for example: 
// src/index.ts
import { pool } from "./lib/db";

const server = Bun.serve({
  port: process.env.PORT || 3000,
  fetch(req) {
    // ... your routes
  },
});

// Graceful shutdown
process.on("SIGTERM", async () => {
  console.log("Received SIGTERM, closing connections...");

  // Close database pool
  await pool.end();

  // Stop server
  server.stop();

  console.log("Server closed gracefully");
  process.exit(0);
});

process.on("SIGINT", async () => {
  console.log("Received SIGINT, closing connections...");
  await pool.end();
  server.stop();
  process.exit(0);
});

​
S3

Bun includes a built-in s3 package that integrates seamlessly with Sevalla’s object storage. You can also integrate your Bun application with AWS S3 for object storage, file uploads, and static assets.

​
Set up AWS S3

  1. Install AWS SDK dependency:
bun add @aws-sdk/client-s3
  1. Set S3 environment variables:
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your_access_key_here
S3_SECRET_ACCESS_KEY=your_secret_key_here
S3_ENDPOINT=https://s3.sevalla.com
S3_BUCKET_NAME=your_bucket_name
For production, use your Sevalla S3 service credentials or external S3-compatible provider (AWS S3, Cloudflare R2, MinIO, etc.)

​
AWS S3 Usage

The S3 client is initialized in src/s3.ts: 
import { S3Client } from "@aws-sdk/client-s3";

const s3Client = new S3Client({
  region: process.env.S3_REGION || "us-east-1",
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY_ID || "",
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY || "",
  },
  endpoint: process.env.S3_ENDPOINT,
});

export default s3Client;