Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt

Use this file to discover all available pages before exploring further.

Deno is a modern, secure runtime for JavaScript and TypeScript. It is built with Rust and emphasizes security by requiring explicit permissions for file, network, or environment access. Deno supports TypeScript natively, includes a standard library, and utilizes URL-based module imports instead of a centralized package manager, providing a streamlined and secure alternative for server-side development and scripting. Deno can only be used on Application Hosting; it cannot be deployed as a static site.

​
Configuration

Deno runs TypeScript directly, eliminating the need for a separate build or installation step. With Sevalla:
  • Dependencies are cached automatically on the first build.
  • Your app can be started using deno task start or any custom start command you configure.
The following is an example deno.json file: 
{
  "tasks": {
    "start": "deno run --allow-net --allow-env --allow-read src/index.ts"
  }
}
Ensure your start command includes all necessary permission flags for production:
  • --allow-net - Enables network access (required for HTTP servers).
  • --allow-env - Access to environment variables.
  • --allow-read - File system read access (if needed).
  • --allow-write - File system write access (if needed).

​
Containerization

​
Dockerfile

The build for Dockerfiles is fully customizable. The following is an example Dockerfile for Deno: 
FROM denoland/deno:latest

WORKDIR /app

COPY . .

RUN deno cache src/main.ts

EXPOSE 3000

ENV PORT=3000

CMD ["deno", "run", "--allow-net", "--allow-env", "src/main.ts"]

​
Nixpacks

Nixpacks automatically detects Deno projects by looking for:
  1. deno.json or deno.jsonc in the project root.
  2. Deno imports in TypeScript files.
  3. deps.ts file (common Deno convention).
Once detected, Nixpacks will:
  • Install the latest Deno runtime.
  • Cache dependencies from remote imports.
  • Execute your start command as defined in deno.json .
For example, if you have a deno.json with a start task, as follows: 
{
  "tasks": {
    "start": "deno run --allow-net --allow-env src/index.ts"
  }
}
Nixpacks will automatically install Deno and run deno task start to start your application.

​
Custom configuration with nixpacks.toml

You can customize the Nixpacks build process by defining a nixpacks.toml file and using Nixpacks-specific environment variables. This allows you to fine-tune how dependencies are installed, how your application is built, and which runtime settings are applied. The following is an example nixpacks.toml configuration: 
# nixpacks.toml

[phases.setup]
nixPkgs = ["deno"]

[phases.install]
# Cache dependencies by running a command that imports them
cmds = ["deno cache src/index.ts"]

[phases.build]
# Optional: Run build steps if needed
cmds = ["deno task build"]

[start]
cmd = "deno task start"

​
Common Nixpacks configurations

Basic Deno application 
# nixpacks.toml
[phases.setup]
nixPkgs = ["deno"]

[start]
cmd = "deno run --allow-net --allow-env src/index.ts"
Deno with specific version 
# nixpacks.toml
[phases.setup]
nixPkgs = ["deno"]

[phases.install]
cmds = ["deno upgrade --version 1.40.0"]

[start]
cmd = "deno task start"
Deno with additional system dependencies 
# nixpacks.toml
[phases.setup]
# Add additional system packages if needed (e.g., for image processing)
nixPkgs = ["deno", "imagemagick", "ffmpeg"]

[phases.install]
cmds = ["deno cache src/index.ts"]

[start]
cmd = "deno task start"
Monorepo with custom build path 
# nixpacks.toml (in monorepo root)
[phases.setup]
nixPkgs = ["deno"]

[phases.install]
cmds = ["cd apps/api && deno cache src/index.ts"]

[start]
cmd = "cd apps/api && deno task start"
Deno with environment-specific builds 
# nixpacks.toml
[phases.setup]
nixPkgs = ["deno"]

[phases.build]
# Generate static files or run build tasks
cmds = [
  "deno task build",
  "deno run --allow-read --allow-write scripts/generate-config.ts"
]

[start]
cmd = "deno task start"
For more information about Nixpacks with Deno, refer to the Nixpacks Deno documentation.

​
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 Deno application, we recommend the following best practices:
  • Enable the CDN for all production applications.
  • Set appropriate Cache-Control headers on API routes to ensure proper caching behavior.
  • Purge the CDN cache after deploying critical updates to avoid serving stale content.
  • Use versioned URLs for static assets, for example /static/app.v123.js.

​
Optimizing Deno for CDN

​
Static files with cache headers

// src/index.ts
import { serveFile } from "https://deno.land/std@0.208.0/http/file_server.ts";

Deno.serve({ port: Number(Deno.env.get("PORT") || "3000") }, async (req) => {
  const url = new URL(req.url);

  // Serve static assets with caching
  if (url.pathname.startsWith("/static/")) {
    try {
      const filePath = `./public${url.pathname}`;
      const response = await serveFile(req, filePath);

      response.headers.set(
        "Cache-Control",
        "public, max-age=31536000, immutable"
      );
      return response;
    } catch {
      return new Response("Not Found", { status: 404 });
    }
  }

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

    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 Deno 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 Deno for edge caching

// src/index.ts
Deno.serve({ port: Number(Deno.env.get("PORT") || "3000") }, (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 Deno 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 health check

// src/index.ts
Deno.serve({ port: Number(Deno.env.get("PORT") || "3000") }, (req) => {
  const url = new URL(req.url);

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

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

​
Graceful shutdown

Deno supports graceful shutdown signals. For custom cleanup logic, such as closing database connections, use SIGTERM and SIGINT, for example: 
// src/index.ts
import { pool } from "./lib/db.ts";

const abortController = new AbortController();

Deno.serve(
  {
    port: Number(Deno.env.get("PORT") || "3000"),
    signal: abortController.signal,
  },
  (req) => {
    // ... your routes
  }
);

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

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

  // Stop server
  abortController.abort();

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

Deno.addSignalListener("SIGINT", async () => {
  console.log("Received SIGINT, closing connections...");
  await pool.end();
  abortController.abort();
  Deno.exit(0);
});

​
S3

You can integrate your Deno application with S3 (Sevalla S3, AWS S3, or any S3-compatible storage) using the AWS SDK or JavaScript v3.

​
Setup

  1. Install dependencies (auto-cached on first run):
import {
  S3Client,
  ListBucketsCommand,
  PutObjectCommand,
  GetObjectCommand,
  DeleteObjectCommand,
} from "npm:@aws-sdk/client-s3@^3.400.0";
  1. Configure environment variables:
S3_REGION=us-east-1
S3_ENDPOINT=https://s3.sevalla.com  # Optional: for S3-compatible services
S3_ACCESS_KEY_ID=your_access_key_here
S3_SECRET_ACCESS_KEY=your_secret_key_here