# How to Deploy An Astro App In Just One Click

> Deploy static site, SSR, or hybrid Astro app. Create your project, configure astro.config.mjs, add the Node adapter for SSR, and deploy on Kuberns in one click.
- **Author**: suyash-tiwari
- **Published**: 2026-01-11
- **Modified**: 2026-03-27
- **Category**: Deployment Guides
- **URL**: https://kuberns.com/blogs/how-to-deploy-an-astro-app/

---

If you're looking for the easiest way to deploy an Astro app, whether it's a static site, a server-rendered app, or a hybrid of both, you're in the right place.

Astro is built around one idea: ship less JavaScript, faster pages. Its output configuration controls everything about how your app deploys, static files to a CDN, a Node.js server for SSR, or a hybrid of both on a per-route basis. Once you understand which mode you're using, deployment is straightforward.

The fastest path recommended by developers in 2026 is [Kuberns](https://kuberns.com/). Connect your GitHub repository, add your environment variables, and click Deploy. The agentic AI reads your astro.config.mjs detects your output mode and Node adapter, runs npm run build, starts your app correctly for static or SSR, issues SSL, and enables autoscaling without a Dockerfile, a YAML file, or a platform-specific adapter.

This guide covers everything from creating a new Astro project to deploying it on Kuberns: the three output modes with working astro.config.mjs code for each, the Node.js adapter for SSR, how to configure your PORT, and the step-by-step deployment flow.

## Create Your Astro App

There are several ways to spin up a new Astro project. If you already have an existing Astro app, skip ahead to configure it for production.

### Using the Astro CLI

Open your terminal and run:
![run astro terminal](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-cli.png)

The CLI walks you through setup. When prompted:

* Where should we create your new project? Choose a directory name (e.g. my-astro-app)
* How would you like to start? "Include sample files" is a good starting point
* TypeScript? Yes, Strict is recommended for production apps
* Install dependencies? Yes
* Initialise a git repository? Yes

Once done, start the dev server to confirm everything works:
![start the server](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-server.png)

Visit http\://localhost:4321 in your browser. You should see the Astro welcome page.

### Using In-Browser Environments

If you prefer a browser-based workflow, Astro works great with StackBlitz, CodeSandbox, and GitPod. Head to[ astro.new](https://astro.new/) and pick a starter template. You can connect your browser environment to GitHub to fork the repo when you're ready to deploy.

## Deploy Astro App In One-click

Want to skip the setup entirely and go live in minutes? Use the Kuberns one-click Agentic AI to deploy without any manual configuration. Watch how this works:

<iframe width="560" height="315" src="https://www.youtube.com/embed/Mg-5xuWGI9Q?si=mJGLv_0ByUpIV4mO" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

## Configure Astro for Production

Before deploying, two things need to be set correctly in your project: your output mode and, if you're using SSR, the Node.js adapter and PORT configuration.

### Step 1: Understand Astro's Three Output Modes

Astro's output setting in astro.config.mjs controls everything about how your app builds and runs in production. Choose the one that matches what you're building.

**output: 'static: Static Site (default)**

Every page pre-renders to HTML at build time. The output is pure static files in dist/. No server needed. Best for: marketing sites, blogs, documentation, and landing pages.
![static site](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-static-site.png)

**Build output:**
![build output](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-static-output.png)
No adapter needed. No server needed. Kuberns serves static files directly with a global CDN and SSL.

***

**output: 'server: Server-Side Rendering (SSR)**

Every page renders on demand at request time. A Node.js server handles all routes. Best for: apps with authentication, user-specific content, e-commerce, and dynamic data fetched at request time.
![ssr server](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-ssr.png)

**Build output:**
![ssr build output](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-ssr-output.png)

***

**output: 'hybrid': Hybrid (mostly static, some SSR)**

Pages are static by default. Individual routes can opt into SSR with export const prerender = false. Best for: sites that are mostly static but have a few dynamic routes (e.g. a blog with a contact form, or a docs site with a search API).
![astro hybrid](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-hybrid.png)

**In any page that needs SSR:**
![ssr hybrid output](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-hybrid-fetch.png)

All other pages remain statically pre-rendered at build time.

### Step 2: Add the Node.js Adapter (SSR and Hybrid only)

Skip this step if you're deploying a static site; no adapter needed.

For output: 'server' or output: 'hybrid', run one command:
![node js adpater](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-adapter.png)

That's it. This installs @astrojs/node and updates your astro.config.mjs automatically with the correct adapter configuration. Kuberns detects it from there, no extra setup on your end.

### Step 3: Add a Start Script (SSR and Hybrid only)

Skip this for static sites, Kuberns serves dist/ directly, nothing to configure.

For SSR and Hybrid, add one line to the scripts block in your package.json:
![start script](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astro-start-command.png)

That's the only change. Kuberns reads this to know how to start your app after the build completes.

Make sure dist/, node\_modules/, and .env are in your .gitignore, Kuberns installs dependencies and builds fresh from source on every deployment.

> 💡 Building an Astro site with a React or Node.js backend? See our [React deployment](https://kuberns.com/blogs/deploying-react-app/) guide and [Node.js deployment](https://kuberns.com/blogs/how-to-deploy-nodejs-app/) guide, both deploy as separate Kuberns services alongside your Astro frontend.

## Deploy Your Astro App on Kuberns

Kuberns is an agentic AI cloud platform. For Astro apps, the AI reads your astro.config.mjs, detects your output mode, runs npm run build, serves the dist/ output for static sites or starts node ./dist/server/entry.mjs for SSR apps, all automatically, with SSL and CI/CD built in.

### Step 1: Create Your Account and Project

Go to[ kuberns](https://kuberns.com) and click "Deploy with AI". Create your account and add basic details of your account.
![sign up on kuberns](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/deploying-on-kuberns.png)

Kuberns has a free tier to start. After that, $7 gets you $14 in compute credits, 2X value to apply toward your deployment.[ See what each tier includes](https://kuberns.com/pricing/)

### Step 2: Connect GitHub

Click "Connect to GitHub", authorise Kuberns, then select your Astro repository and the branch you want to deploy from (main). That's all the configuration you do.
![connect github to kuberns](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/kuberns-registration.png)
The AI reads your astro.config.mjs, detects your output mode, sets the build command to npm run build, and identifies whether to serve dist/ (static) or start node ./dist/server/entry.mjs (SSR/Hybrid), automatically. You confirm, not configure.

### Step 3: Set Environment Variables

Go to the Environment section. Click "Add Env Vars" to add key-value pairs, or "Upload .env file" to import your local file in one go.
![add env variables to kuberns](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/environment-variable-kuberns.png)
Any secrets your Astro app needs, API keys, database URLs, public config, live here. All values are encrypted at rest and never appear in build logs. For Astro-specific variable naming (PUBLIC\_ vs secret), see the environment variables section below.

### Step 4: Click Deploy

Hit Deploy. Kuberns Agentic AI takes it from here, no more decisions from you.
![click deploy to run with ai](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/kuberns-ai-deploying.png)
The AI installs dependencies, runs npm run build, and delivers your app live with HTTPS, CI/CD on every future GitHub push, and autoscaling already running. The whole process typically takes under three minutes.

Your Astro app is live. Check build logs and real-time monitoring from the dashboard.

[Deploy your Astro app on Kuberns](https://dashboard.kuberns.com/login)

> 💡 Deploying an Astro blog or documentation site with a headless CMS? See our [Next.js deployment](https://kuberns.com/blogs/deploy-nextjs-app/) guide for a comparison. Astro is often the better choice for content-first sites, Next.js for apps with complex state and API routes.

### Environment Variables in Astro (The PUBLIC\_ Distinction)

Astro handles environment variables differently from most frameworks, and it's important to get this right before deploying.

**Variables prefixed with PUBLIC\_** are included in the client-side JavaScript bundle. They're accessible in browser code and visible to users who inspect the page source. Use these for API endpoints, feature flags, or public configuration.

**Variables without the PUBLIC\_** prefix are only available on the server in the .astro file frontmatter, API routes, and middleware. They never reach the browser. Use these for API keys, database URLs, and secrets.
![Env variables in astro](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/astr-env.png)

## Ship Your Astro App Now

Your Astro project is configured. Your GitHub repository is ready. Four steps on Kuberns,  connect, add environment variables, click Deploy, watch the build, and your app is live with HTTPS, CI/CD, and autoscaling.

Whether it's a static blog, an SSR e-commerce site, or a hybrid docs portal, the deployment path is the same. Push code. Watch it ship.

[Deploy your Astro app on Kuberns ](https://dashboard.kuberns.com)

## Frequently Asked Questions

### How do I deploy an Astro app in 2026?

Create your Astro project with npm create astro\@latest. Configure astro.config.mjs with your output mode. For SSR, add the Node adapter with npx astro add node and update the start script in package.json. Push to GitHub. Connect on Kuberns, add environment variables, click Deploy. The AI detects your output mode, runs npm run build, and serves or starts your app automatically.

### What is the difference between Astro static, SSR, and hybrid deployment?

Static (output: 'static') pre-renders all pages at build time, pure HTML/CSS/JS in dist/, no server needed, best for blogs and marketing sites. Server (output: 'server') renders all pages on demand via a Node.js server, best for apps with auth, user-specific content, or dynamic data. Hybrid (output: 'hybrid') is static by default with opt-in SSR per route, best for mostly static sites with a few dynamic pages.

### Do I need an adapter to deploy Astro on Kuberns?

For static sites, no, Kuberns serves dist/ directly without any adapter. For SSR and Hybrid, you need @astrojs/node, install it with npx astro add node. Unlike Netlify and Vercel which require their own platform-specific adapters (@astrojs/netlify, @astrojs/vercel), Kuberns uses the standard Node.js adapter, which means your deployment isn't tied to one platform.

### How do I set environment variables for an Astro app?

Add variables in the Kuberns Environment dashboard before deploying. Variables prefixed with PUBLIC\_ are accessible in both server and browser code, use them for API endpoints and public config. Variables without the prefix are server-side only, use them for secrets and database URLs. In your Astro code, access them with import.meta.env.VARIABLE\_NAME.

### Why is my Astro SSR app returning 404 on all routes?

The most common cause is a missing or incorrect start script in package.json. It should be "start": "node ./dist/server/entry.mjs". Also confirm that astro.config.mjs has output: 'server' and adapter: node() set correctly. Build locally and confirm dist/server/entry.mjs exists before pushing.

### Can I deploy an Astro app without Docker?

Yes. On Kuberns, push your project to GitHub with astro.config.mjs and package.json configured. Kuberns handles the entire build and deployment pipeline, no Dockerfile, no container setup, no YAML. The AI detects Astro, runs the build, and serves the output appropriately for your output mode.

---
- [More Deployment Guides articles](https://kuberns.com/blogs/category/deployment-guides/1/)
- [All articles](https://kuberns.com/blogs/)