Skip to main content
Nuxt is a high-performance, open-source framework built on Vue.js. It provides a powerful environment for building full-stack applications, static sites, and server-rendered experiences with minimal configuration. Nuxt can be deployed using either Application Hosting (SSR) or Static Site Hosting (SSG). The primary difference lies in how you configure the nuxt.config.ts file. If not all pages are prerendered, you should use Application Hosting; otherwise, you should use 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. SSR is ideal when your site includes:
  • Personalized user experiences, such as dashboards and profiles.
  • Real-time or frequently changing data that must be fetched on every request.
  • Dynamic routes that cannot be known ahead of time, making static pre-rendering impractical.
  • Authentication-dependent content, where access and rendering vary based on the user’s session or permissions.

​
Configuration

To configure your Nuxt application for Sevalla, we recommend you follow these best practices:
  • Use Nitro’s built-in caching (defineCachedEventHandler) for expensive operations.
  • Apply Nuxt Route Rules for static generation and edge caching.
  • Use Nuxt Image for optimized image delivery.
  • Enable compression in your Nitro config.
  • Prerender pages that don’t require SSR.
Nuxt requires runtimeConfig for handling environment variables, ensuring they are properly injected and kept server-only unless explicitly exposed. The following is an example nuxt.config.ts file for deploying a Nuxt.js app on Sevalla: 
// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'node-server',
    compressPublicAssets: true,
  }
})

​
Containerization

​
Dockerfile

The build for Dockerfiles is fully customizable. The following is an example Dockerfile for Nuxt.js: 
FROM node:lts-alpine

WORKDIR /app

COPY package.json package-lock.json* ./

RUN npm ci

COPY . .

RUN npm run build

EXPOSE 3000

ENV PORT=3000
ENV HOST=0.0.0.0

CMD ["npm", "start"]

​
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: 
# nixpacks.toml

# Override phases
[phases.setup]
nixPkgs = ["nodejs-22_x", "pnpm"]

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

[phases.build]
cmds = ["pnpm run build"]

# Set start command
[start]
cmd = "node .output/server/index.mjs"

# Environment variables available at build time
[variables]
NODE_ENV = "production"
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 a Nuxt.js application is: 
 "build": "nuxt build"
You can also add additional logic before the build runs, for example: 
"build": "echo \"Hi mom!\" && nuxt 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 Nuxt.js application, we recommend the following best practices:
  • Enable the CDN for all production applications to ensure global, low-latency delivery.
  • Use the <NuxtImg> component for automatic image optimization and responsive formats.
  • 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.
  • Rely on Nuxt’s versioned assets in the _nuxt/ directory, which are safe to cache indefinitely.
  • Store static files in the public/ directory, allowing the CDN to serve them efficiently.

​
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 Nuxt.js 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 Nuxt.js 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 Nuxt.js 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 .output/public/_nuxt/), 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: 
// server/api/public-data.ts
export default defineEventHandler(async (event) => {
  const data = await fetchPublicData();

  setResponseHeader(event, "Cache-Control", "public, s-maxage=3600");

  return data;
});

​
Server route caching with Nitro

Nuxt.js uses Nitro’s caching capabilities for server routes: 
// server/api/products.ts
export default defineCachedEventHandler(
  async (event) => {
    const products = await fetchProducts();

    return products;
  },
  {
    maxAge: 60 * 60, // Cache for 1 hour
    name: "products",
    getKey: () => "all-products",
  }
);
Custom cache with more control 
// server/api/products.ts
export default defineEventHandler(async (event) => {
  const cached = await useStorage("cache").getItem("products");

  if (cached) {
    return cached;
  }

  const products = await fetchProducts();

  await useStorage("cache").setItem("products", products, {
    ttl: 60 * 60, // 1 hour
  });

  return products;
});

​
Route rules for page caching

You can use route rules to cache specific pages: 
// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // Static page generated at build time
    "/about": { prerender: true },

    // SWR (Stale-While-Revalidate) - serve cached, update in background
    "/blog/**": { swr: 3600 },

    // ISR (Incremental Static Regeneration)
    "/products/**": { isr: 3600 },

    // Disable caching for dynamic content
    "/api/user/**": { cache: false },
  },
});

<!-- pages/blog/[slug].vue -->
<script setup lang="ts">
const route = useRoute();
const slug = route.params.slug as string;

// Data is automatically cached based on route rules
const { data: post } = await useFetch(`/api/posts/${slug}`);
</script>

<template>
  <article>
    <h1>{{ post?.title }}</h1>
    <div v-html="post?.content" />
  </article>
</template>

​
Cache Invalidation

Nuxt.js provides cache invalidation through Nitro’s storage layer: Clear specific cache entry: 
// server/api/revalidate.post.ts
export default defineEventHandler(async (event) => {
  const { key, secret } = await readBody(event);

  const config = useRuntimeConfig();
  if (secret !== config.revalidationSecret) {
    throw createError({
      statusCode: 401,
      message: "Invalid secret",
    });
  }

  try {
    // Clear specific cache entry
    await useStorage("cache").removeItem(key);

    return { revalidated: true };
  } catch (err) {
    throw createError({
      statusCode: 500,
      message: "Error revalidating",
    });
  }
});
Clear all cache: 
// server/api/clear-cache.post.ts
export default defineEventHandler(async (event) => {
  const { secret } = await readBody(event);

  const config = useRuntimeConfig();
  if (secret !== config.revalidationSecret) {
    throw createError({
      statusCode: 401,
      message: "Invalid secret",
    });
  }

  try {
    // Clear all cache
    await useStorage("cache").clear();

    return { cleared: true };
  } catch (err) {
    throw createError({
      statusCode: 500,
      message: "Error clearing cache",
    });
  }
});
Programmatic cache invalidation: 
// server/utils/cache.ts
export async function invalidateProductCache(productId: string) {
  await useStorage("cache").removeItem(`product-${productId}`);
}

export async function invalidateAllProducts() {
  const keys = await useStorage("cache").getKeys("product-");
  await Promise.all(keys.map((key) => useStorage("cache").removeItem(key)));
}

​
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 
// server/api/health.ts
export default defineEventHandler(() => {
  return {
    status: "ok",
    timestamp: new Date().toISOString(),
  };
});

​
Multi-tenancy

Sevalla fully supports multi-tenancy. You can build multi-tenant Nuxt.js 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 Nuxt.js 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.

​
Nuxt.js multi-tenant implementation

Below is a reference architecture for extracting tenant information from the hostname and injecting it into Nuxt’s request lifecycle. Extract tenant from subdomain using middleware: 
// server/middleware/tenant.ts
export default defineEventHandler((event) => {
  const host = getRequestHeader(event, "host") || "";
  const subdomain = host.split(".")[0];

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

  // Add tenant to event context
  event.context.tenantId = subdomain;
});
Use tenant in API routes: 
// server/api/tenant-info.ts
export default defineEventHandler(async (event) => {
  const tenantId = event.context.tenantId;

  if (!tenantId) {
    return { error: "No tenant specified" };
  }

  const tenant = await getTenantData(tenantId);

  return {
    tenant: tenant.name,
    subdomain: tenantId,
  };
});
Use tenant in pages: 
<!-- pages/index.vue -->
<script setup lang="ts">
const { data: tenant } = await useFetch("/api/tenant-info");
</script>

<template>
  <div>
    <h1>Welcome to {{ tenant?.tenant }}</h1>
  </div>
</template>
Tenant-specific data: 
// server/utils/tenant.ts
import { pool } from "./db";

export async function getTenantData(tenantId: string) {
  const result = await pool.query(
    "SELECT * FROM tenants WHERE subdomain = $1",
    [tenantId]
  );

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

​
Custom domains per tenant

Allow tenants to use their own domains (e.g., customdomain.com → tenant data). Map custom domains to tenants: 
// server/middleware/tenant.ts
export default defineEventHandler(async (event) => {
  const host = getRequestHeader(event, "host") || "";
  const tenant = await getTenantByDomain(host);

  event.context.tenantId = tenant?.id || host.split(".")[0];
});

​
​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

Use nuxt generate to build and prerender your application using Nitro’s crawler. This command is similar to running nuxt build with nitro.static enabled (or nuxt build --prerender). During generation, Nuxt builds your site, starts a temporary server, and automatically crawls pages beginning with / pre-rendering every reachable route. 
npx nuxt generate
After the build completes, you can deploy the contents of .output/public to any static hosting provider, or preview the result locally using: 
npx serve .output/public
For more information, refer to Nuxt.js documentation.

​
Redirects

To apply custom redirect rules, add a _redirects file containing your redirects to your repository’s root directory. Sevalla will automatically parse the file’s contents and apply the custom redirect rules.

​
Pretty URLs

In Sevalla, you can enable Pretty URLs to standardize your site’s URLs and improve SEO. This feature automatically enforces a trailing slash on the path of static site requests using a 301 redirect.