Deploying an Astro Static Site with API Routes on Deployxa

Astro is the fastest static site framework in 2026, and for good reason: it produces HTML-first output with zero JavaScript by default, which means pages load instantly. For content-heavy sites (blogs, documentation, marketing pages), Astro is hard to beat. But Astro also supports SSR (server-side rendering) and API routes, which means it can handle dynamic content and backend logic. This makes it a versatile choice for AI-generated apps that need both static content and dynamic features. Deployxa's zero-config engine handles the Astro deployment automatically, detecting the framework from your package.json and astro.config.mjs and configuring the build and start commands. Here is how to deploy an Astro static site with API routes on Deployxa.

The direct answer is that Deployxa auto-detects Astro from your package.json (which includes astro) and astro.config.mjs. It configures the build and start commands based on the output mode: for static output (the default), the build command is astro build and the output is served via a static file server. For SSR output (via @astrojs/node), the build command is astro build and the start command is node ./dist/server/entry.mjs. You do not write a Dockerfile, you do not configure the server manually, and you do not manage the build output. The platform handles all of it, just as it does for Next.js and SvelteKit apps.

Why Astro Is a Great Choice for Content-Heavy Sites

Three reasons explain why Astro is a great choice for content-heavy sites. First, it is HTML-first: by default, Astro produces static HTML with zero JavaScript, which means pages load instantly and are SEO-friendly. For blogs, documentation, and marketing pages, this is ideal. Second, it is framework-agnostic: Astro lets you use React, Vue, Svelte, or Solid components within the same site, which means you can leverage your existing component library. Third, it supports islands: Astro's "islands architecture" lets you add interactive components (which ship JavaScript) only where needed, which means the page stays fast even with some interactivity. For more on SEO, see our article on why AI-generated apps have no SEO.

The Architecture: Astro Static or SSR + Container

Here is how Deployxa deploys an Astro app.

The static output (default)

For static output, the ingestion service detects that output is not set (or is set to 'static') in astro.config.mjs. It configures the build to produce a dist/ directory with static HTML, CSS, and JS files, which are served via a static file server.

The SSR output

For SSR output (via @astrojs/node), the ingestion service detects that output is set to 'server' in astro.config.mjs. It configures the build to produce a dist/server/entry.mjs standalone Node server, which runs in a persistent container.

The API routes

Astro supports API routes via the src/pages/api/ directory. Each file in this directory exports a GET, POST, PUT, or DELETE function that handles the corresponding HTTP method. API routes require SSR output (they do not work with static output).

The reverse proxy

Traefik v3 routes traffic from your custom domain to the Astro container (for SSR) or to the static file server (for static output), with automatic SSL via Let's Encrypt.

Step-by-Step: Deploying an Astro App with API Routes

Here is the exact workflow for a typical Cursor-generated Astro app.

Step 1: Create your Astro app

npm create astro@latest my-app
cd my-app
npm install

Step 2: Install the Node adapter (for SSR and API routes)

npm install @astrojs/node

Step 3: Configure astro.config.mjs

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
  server: {
    host: '0.0.0.0',
    port: process.env.PORT || 3000,
  },
});

Step 4: Create an API route

In src/pages/api/health.ts:

import type { APIRoute } from 'astro';

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

Step 5: Create a content page

In src/pages/index.astro:

---
const posts = [
  { title: 'Hello World', slug: 'hello-world' },
  { title: 'My Second Post', slug: 'my-second-post' },
];
---


  
    
    My Astro Blog
    
  
  
    My Astro Blog
    
      {posts.map((post) => (
        {post.title}
      ))}

Step 6: Push to GitHub

git init
git add .
git commit -m "astro app with api routes"
git remote add origin https://github.com/yourname/my-app.git
git push -u origin main

Step 7: Connect to Deployxa

In the Deployxa dashboard, connect your repository. Deployxa auto-detects Astro:

[ingest] Detected Node.js project
[ingest] Framework: astro
[ingest] Runtime: node 20.x
[ingest] Output: server
[ingest] Adapter: @astrojs/node
[ingest] Build command: astro build
[ingest] Start command: node ./dist/server/entry.mjs
[ingest] Port: $PORT

Step 8: Configure environment variables

If your app uses environment variables (e.g., DATABASE_URL for API routes), add them in the Deployxa dashboard. In Astro, environment variables are accessed via import.meta.env, with the PUBLIC_ prefix for client-side variables. For more on environment variables, see our article on the vibe coder's guide to environment variables.

Step 9: Deploy

Click Deploy. The build runs astro build, which produces the dist/ directory with the standalone Node server. The container starts with node ./dist/server/entry.mjs, and your app is live within 60 to 90 seconds.

Step 10: Add a custom domain

Add a custom domain in the Deployxa dashboard. SSL is provisioned automatically.

Step 11: Verify with deployxa doctor

Run deployxa doctor to verify health. The 14-point readiness engine checks SSL, DNS, environment variables, health endpoints, and container status.

Common Pitfalls and Troubleshooting

The first pitfall is choosing the wrong output mode. Astro supports two output modes: static (default) and server. If you need API routes or SSR, you must set output: 'server' and install the Node adapter. If you only need static pages, leave output unset (or set to 'static') for faster performance. The second pitfall is the PORT environment variable. Astro's Node adapter listens on port 3000 by default, but Deployxa assigns a dynamic port via the PORT environment variable. The fix is to set server.port in astro.config.mjs to process.env.PORT || 3000. The third pitfall is the ORIGIN environment variable. Astro's Node adapter uses the ORIGIN environment variable for CSRF protection, similar to SvelteKit and Nuxt 3. The fix is to set ORIGIN in the Deployxa dashboard to your app's URL. The fourth pitfall is client-side JavaScript. Astro's default is zero JavaScript, which means components are rendered to HTML at build time. If you need interactivity (e.g., a dropdown, a modal), you need to use a client directive (e.g., client:load, client:visible, client:idle) on the component. The fifth pitfall is framework integration. If you use React, Vue, or Svelte components in Astro, you need to install the corresponding integration (e.g., @astrojs/react, @astrojs/vue, @astrojs/svelte) and add it to the integrations array in astro.config.mjs.

Performance: Astro vs Next.js vs SvelteKit

Astro, Next.js, and SvelteKit are three leading meta-frameworks in 2026. Astro produces the smallest initial load (0KB of JavaScript by default), because it renders components to HTML at build time. Next.js and SvelteKit produce larger initial loads (50-300KB of JavaScript), because they ship a runtime. For content-heavy sites (blogs, documentation, marketing pages), Astro is the best choice. For apps with lots of interactivity, SvelteKit or Next.js might be better, because they handle client-side state more naturally. Deployxa supports all three equally, with the AutoRepairService and the zero-config engine handling each framework automatically. For more on performance, see our article on SPA vs SSR hardware sizing.

Advanced Astro Patterns

Beyond the basics, Astro apps benefit from several advanced patterns. The first is content collections. Astro's content collections let you define a schema for your Markdown content, which provides type safety and validation. This is great for blogs and documentation sites. The second is image optimization. Astro's astro:assets module optimizes images automatically (resizing, format conversion, lazy loading), which improves performance. The third is integrations. Astro has a rich ecosystem of integrations (Tailwind, React, Vue, Svelte, MDX, etc.) that extend its functionality. The fourth is middleware. Astro supports middleware (via src/middleware.ts) that runs on every request, which is useful for authentication, logging, and A/B testing. The fifth is testing. Astro has built-in support for testing via vitest, which makes it easy to write unit and integration tests. For more on testing, see our article on building a self-healing CI/CD pipeline. For more on framework deep-dives, see our articles on deploying a SvelteKit app and deploying a Nuxt 3 app.

Conclusion: Astro Without the Configuration

Astro is the fastest static site framework in 2026, and its SSR mode with API routes makes it versatile. Deploying it should be as simple as pushing to Git. Deployxa's zero-config engine makes it so: no Dockerfile, no adapter configuration, no build management. Stop configuring adapters and start shipping.

Ready to deploy your Astro app? Drag your project to Deployxa Drop for an instant live preview, or install the CLI with npm i -g @deployxa/cli and deploy from your terminal. For more on framework deep-dives, see our articles on deploying a SvelteKit app and deploying a Nuxt 3 app. Learn about deploying a Remix app with Postgres and deploying a Hono API in our companion articles. Explore our free developer tools to speed up your workflow.