Astro

Astro is a modern, content-focused web framework designed to build fast, lightweight, and highly optimized websites. Its core philosophy is “Ship Less JavaScript”, meaning Astro renders as much of your site as possible to static HTML and only loads JavaScript in the browser when necessary. Astro can be deployed using either Application Hosting (SSR) or Static Site Hosting (SSG). The deployment mode is determined by how you configure your astro.config.mjs file. Astro’s defineConfig.output setting can only be set to static or serveryou cannot mix both modes within a single project. By default, Astro generates a fully static site (SSG). To use SSR, you must explicitly opt in by settingprerender: false. If any part of your application uses prerender: false, includes server-only code, or depends on dynamic rendering, you should use Application Hosting instead of Static Site Hosting.

Application Hosting

Choose Application Hosting (Server-Side Rendering) when your application requires server-side logic or dynamic behavior that static files cannot provide.

Configuration

We recommend the following best practices for configuring Astro as an SSR on Sevalla:

Use Astro’s partial hydration (client:* directives) only for components that need interactivity.
Leverage static generation (SSG) whenever possible for better performance.
Use output: "server" only for pages that truly require SSR.
Enable compression middleware in your Node adapter for smaller responses.
Optimize images using Astro’s built-in <Image /> component.
Sanitize and validate environment variables, and never expose secrets using the PUBLIC_ prefix.
Use HTTPS in production for secure communication.
Implement rate limiting for API routes to prevent abuse.
Add an /api/health endpoint for health checks.
Configure structured logging for easier debugging and observability.
Monitor build sizes and server response times to maintain performance.

The following is an example astro.config.mjs file for deploying an Astro SSR app on Sevalla:

// astro.config.mjs
import { defineConfig } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  output: "server", // Enable SSR
  adapter: node({
    mode: "standalone", // Required for Sevalla deployments
  }),
  server: {
    host: true, // Listen on all network interfaces
    port: process.env.PORT || 4321,
  },
});

Containerization

Dockerfile

The build for Dockerfiles is fully customizable. The following is an example Dockerfile for Astro:

# Dockerfile for Astro on Sevalla

FROM node:lts-alpine AS deps
WORKDIR /app

COPY package*.json ./
RUN npm ci

FROM node:lts-alpine AS builder
WORKDIR /app

COPY --from=deps /app/node_modules ./node_modules
COPY . .

RUN npm run build

FROM node:lts-alpine AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=3000

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 astrouser

COPY --from=builder --chown=astrouser:nodejs /app/dist ./dist
COPY --from=builder --chown=astrouser:nodejs /app/package*.json ./

RUN npm ci --only=production

USER astrouser

EXPOSE 3000

CMD ["node", "./dist/server/entry.mjs"]

Nixpacks

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:

[phases.setup]
nixPkgs = ["nodejs", "yarn"]

[phases.install]
cmds = ["yarn install --frozen-lockfile"]

[phases.build]
cmds = ["yarn build"]

[start]
cmd = "yarn start"

Nixpacks will automatically detect your project’s lock file and select the appropriate package manager during deployment. Additionally, you can specify the Node.js version used during the build by setting the NIXPACKS_NODE_VERSIONenvironment variable.

Buildpacks

If you’re using Buildpacks, you cannot modify the underlying build phases directly or control dependencies. You must rely on the runtime environment that Buildpacks detects. You can influence the build process by adjusting the build script in your package.json. Buildpacks will run whatever command you specify under the build script. For example, the standard command used to compile an Astro application is:

 "build": "astro build"

You can also add additional logic before the build runs, for example:

"build": "echo \"Hi mom!\" && astro build"

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 Astro application, we recommend the following best practices:

Enable the CDN for all production applications.
Use Astro’s <Image> component for automatic image optimization and responsive delivery.
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.
Leverage Astro’s fingerprinted assets in the _astro/ directory for safe long-term caching.
Organize static files in the public/ directory for optimal delivery through the CDN.
Use getStaticPaths for dynamic routes to pre-render content at build time.
Combine static generation with incremental builds for frequently updated content.

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 Astro application, we recommend the following best practices:

Set appropriate Cache-Control headers on server-rendered pages to control caching behavior.
Combine edge caching with the CDN to cover both dynamic and static assets.
Monitor cache efficiency using the cf-cache-status header returned by Cloudflare.

Fully static pages are cached indefinitely by default, providing maximum performance. Edge caching works best when you combine static and dynamic content with proper cache headers. Below are strategies to optimize your Astro application on Sevalla for edge caching.

`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 Astro 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 (e.g., files in dist/_astro/), 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.

For example:

// src/pages/api/public-data.ts
import type { APIRoute } from "astro";

export const GET: APIRoute = async () => {
  const data = await fetchPublicData();

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

API routes with edge caching

Edge-cache API responses by returning appropriate headers in your API routes. This speeds up API responses for repeated requests and reduces load on your origin server.

// src/pages/api/products.ts
import type { APIRoute } from "astro";

export const GET: APIRoute = async () => {
  const products = await fetchProducts();

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

Time-based revalidation

Use short-lived caching for content that updates frequently. This ensures frequently updated pages remain fresh and balances edge caching with dynamic content delivery.

---
// src/pages/news.astro
export const prerender = false;

const cacheTime = 300; // 5 minutes
const news = await fetchNews();

Astro.response.headers.set(
  'Cache-Control',
  `public, s-maxage=${cacheTime}`
);
---

<div>
  {news.map(item => (
    <article>{item.title}</article>
  ))}
</div>

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.
Close connections cleanly (e.g., database pools, Redis) to prevent resource leaks.
Test deployments in staging with monitoring scripts to validate health checks.

Basic health check

// src/pages/api/health.ts
import type { APIRoute } from "astro";

export const GET: APIRoute = async () => {
  return new Response(
    JSON.stringify({
      status: "ok",
      timestamp: new Date().toISOString(),
    }),
    {
      status: 200,
      headers: { "Content-Type": "application/json" },
    }
  );
};

Multi-tenancy

Sevalla fully supports multi-tenancy. You can build multi-tenant Astro applications using wildcard domains, allowing you to serve multiple tenants from separate subdomains efficiently and securely. Use the following best practices for multi-tenancy on Sevalla with your Astro application:

Use wildcard domains to serve subdomain-based tenants (e.g., tenant1.app.com).
Add custom domains individually for tenants who have their own domains.
Cache tenant data to reduce database queries and improve performance.
Validate tenant existence before rendering pages to prevent errors or unauthorized access.
Isolate tenant data in the database using separate schemas or a tenant_id column.
Leverage free SSL certificates, which are automatically provided for both wildcard and custom domains.

Astro multi-tenant implementation

Below is a reference architecture for extracting tenant information from the hostname and injecting it into Astro’s request lifecycle. Extract tenant from subdomain (middleware)

// src/middleware.ts
import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware(async (context, next) => {
  const hostname = context.request.headers.get("host") || "";
  const subdomain = hostname.split(".")[0];

  // Skip for main domain
  if (subdomain === "www" || subdomain === "yourdomain") {
    return next();
  }

  // Add tenant to locals for access in pages
  context.locals.tenantId = subdomain;

  return next();
});

Use tenant information in pages

---
// src/pages/index.astro
import { getTenantData } from '../lib/tenant';

const tenantId = Astro.locals.tenantId;
const tenant = await getTenantData(tenantId);
---

<html>
  <head>
    <title>Welcome to {tenant?.name || 'Our Platform'}</title>
  </head>
  <body>
    <h1>Welcome to {tenant?.name}</h1>
    <p>Tenant ID: {tenantId}</p>
  </body>
</html>

Tenant metadata lookup

// src/lib/tenant.ts
import { pool } from "./db";

export async function getTenantData(tenantId: string | undefined) {
  if (!tenantId) return null;

  const result = await pool.query(
    "SELECT * FROM tenants WHERE subdomain = $1",
    [tenantId]
  );

  return result.rows[0] || null;
}

Tenant-aware API routes

// src/pages/api/data.ts
import type { APIRoute } from "astro";
import { getTenantData } from "../../lib/tenant";

export const GET: APIRoute = async ({ locals }) => {
  const tenant = await getTenantData(locals.tenantId);

  if (!tenant) {
    return new Response(JSON.stringify({ error: "Tenant not found" }), {
      status: 404,
      headers: { "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(tenant), {
    headers: { "Content-Type": "application/json" },
  });
};

Custom domains per tenant

Tenants may want to use their own domains instead of subdomains. Sevalla supports this through domain mapping.

// src/middleware.ts
import { defineMiddleware } from "astro:middleware";
import { getTenantByDomain } from "./lib/tenant";

export const onRequest = defineMiddleware(async (context, next) => {
  const hostname = context.request.headers.get("host") || "";
  const tenant = await getTenantByDomain(hostname);

  context.locals.tenantId = tenant?.id || hostname.split(".")[0];

  return next();
});

Troubleshooting common SSR issues

Cannot use import.meta.env on the client

Use the PUBLIC_ prefix for any environment variables that must be exposed to client-side code.
Keep all server-only variables unprefixed and ensure they are accessed only in server-side modules.

Route handler not found

Confirm the file is located in the correct directory: src/pages/.
Check that the file uses a supported extension: .astro, .js, or .ts.
Verify that your output mode in astro.config.mjs matches your intended deployment (e.g., server for SSR).

Static Site Hosting

Static Site Generation (SSG) pre-renders all pages as static HTML files at build time, delivering fast and reliable performance. Use SSG when your site includes:

Content that changes infrequently, such as blog posts, documentation, or product catalogs.
Pages that can be pre-rendered for all users without personalization.
Requirements for maximum performance and minimal hosting costs.
A global audience, as static pages benefit from fast CDN distribution.

Configuration

To deploy a static Astro site on Sevalla, set output: "static" in your astro.config.mjs file and ensure that no pages or components use prerender: false, which would force SSR. /

export default defineConfig({
  output: "static", // SSG by default
  adapter: node({
    mode: "standalone",
  }),
});

Creating SSG pages

All .astro pages are automatically pre-rendered at build time in static mode:

---
// src/pages/my-static-page.astro
// This page is automatically static (SSG)
const data = await fetchData(); // Runs at build time
---

<html>
  <body>
    <h1>Static Page</h1>
    <p>Built at: {new Date().toISOString()}</p>
  </body>
</html>

Dynamic routes with SSG

Generate multiple pages from data using getStaticPaths():

---
// src/pages/blog/[slug].astro
export async function getStaticPaths() {
  const posts = await fetchBlogPosts();

  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post }
  }));
}

const { post } = Astro.props;
---

<html>
  <body>
    <h1>{post.title}</h1>
    <div set:html={post.content} />
  </body>
</html>

This generates a static page for each blog post at build time.

Hey 👋

Quick starts

Projects

Applications

Databases

Object storage

Load balancers

Static sites

Templates

Sevalla API

Billing

Company settings

Integration

User settings

Support

Service information

Application Hosting

Configuration

Containerization

Dockerfile

Nixpacks

Buildpacks

CDN

Edge caching

`Cache-Control`

API routes with edge caching

Time-based revalidation

Health checks

Multi-tenancy

Astro multi-tenant implementation

Custom domains per tenant

Troubleshooting common SSR issues

Cannot use import.meta.env on the client

Route handler not found

Static Site Hosting

Configuration

Creating SSG pages

Dynamic routes with SSG

​Application Hosting

​Configuration

​Containerization

​Dockerfile

​Nixpacks

​Buildpacks

​CDN

​Edge caching

​Cache-Control

​API routes with edge caching

​Time-based revalidation

​Health checks

​Multi-tenancy

​Astro multi-tenant implementation

​Custom domains per tenant

​Troubleshooting common SSR issues

​Cannot use import.meta.env on the client

​Route handler not found

​Static Site Hosting

​Configuration

​Creating SSG pages

​Dynamic routes with SSG

​​

Application Hosting

Configuration

Containerization

Dockerfile

Nixpacks

Buildpacks

CDN

Edge caching

`Cache-Control`

API routes with edge caching

Time-based revalidation

Health checks

Multi-tenancy

Astro multi-tenant implementation

Custom domains per tenant

Troubleshooting common SSR issues

Cannot use import.meta.env on the client

Route handler not found

Static Site Hosting

Configuration

Creating SSG pages

Dynamic routes with SSG