How to Use Railway with Astro: Complete Guide

Railway is an infrastructure platform that makes deploying web applications surprisingly simple. Unlike static-only hosts, Railway gives you a full server environment with databases, cron jobs, and persistent storage. This makes it a great fit for Astro projects that use SSR, need a database, or run server-side logic alongside your frontend.

The setup takes about five minutes. You connect your repo, Railway detects your framework, and it deploys. No Dockerfiles, no YAML configs, no manual server provisioning.

Prerequisites

• Node.js 18+
• An Astro project (npm create astro@latest)
• A Railway account (free trial with $5 credit, then $5/month plus usage)
• A Git repository on GitHub

Installation

For SSR Astro projects on Railway, install the Node.js adapter:

npx astro add node

This installs @astrojs/node and configures your project for server-side rendering. For static-only sites, you can skip this step, but Railway is best utilized when you need a running server.

Configuration

Update your astro.config.mjs for SSR:

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

export default defineConfig({
  output: "server", // or "hybrid" for mixed static + SSR
  adapter: node({
    mode: "standalone",
  }),
});

Add a start script to your package.json that Railway will use:

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "start": "node ./dist/server/entry.mjs"
  }
}

Railway needs to know which port to use. Astro's Node adapter reads the PORT environment variable automatically, and Railway sets this for you. No extra config needed.

Basic Usage

Deploy to Railway through their dashboard:

1. Go to railway.app and click "New Project"
2. Select "Deploy from GitHub repo"
3. Pick your Astro repository
4. Railway auto-detects the build command and starts deploying

Railway runs npm run build and then npm run start by default. Your site will be live on a .railway.app subdomain within a couple of minutes.

To add environment variables, click on your service in Railway's dashboard and go to the Variables tab:

PUBLIC_SITE_URL=https://your-app.railway.app
DATABASE_URL=postgresql://user:pass@host:5432/db

One of Railway's strengths is adding services. Need a database? Click "New Service" > "Database" and pick PostgreSQL, MySQL, Redis, or MongoDB. Railway provisions it and gives you the connection string automatically.

// src/lib/db.ts
// Railway injects DATABASE_URL as an environment variable
import pg from "pg";

const pool = new pg.Pool({
  connectionString: import.meta.env.DATABASE_URL,
});

export default pool;

Production Tips

1. Use a custom domain. In your service settings, go to the Networking tab and add your custom domain. Railway provisions SSL automatically. Point your DNS A or CNAME record to the provided address.

2. Set up health checks. Railway can restart your service if it becomes unresponsive. Add a simple health endpoint to your Astro API routes and configure the health check URL in your service settings.

3. Monitor resource usage. Railway charges based on CPU, memory, and network usage. Check your usage dashboard regularly, especially early on, to avoid surprises. Most Astro sites use minimal resources.

4. Use Railway's built-in cron jobs. If you need scheduled tasks like rebuilding a search index or sending emails, Railway supports cron services. Create a separate service with a cron schedule instead of building it into your main app.

5. Enable automatic deploys from a specific branch. By default, Railway deploys on every push to your main branch. You can change this to deploy only from a production branch, keeping your main branch for development.

Alternatives to Consider

• Netlify or Vercel if your Astro site is mostly static and you want free hosting with a generous free tier and zero server management.
• Fly.io if you need to run your application in specific geographic regions for latency-sensitive use cases.
• Render if you want a similar platform-as-a-service experience with a slightly different pricing model and a free tier for web services.

Wrapping Up

Railway is the right choice when your Astro project needs more than static hosting. Database connections, server-side rendering, background jobs, and custom server logic all work out of the box. The developer experience is polished, the pricing is transparent, and you can go from code to production in minutes.