// developer guide

How Backends Work

Connect your GitHub repo to a live backend using Vercel or Railway — and understand what's actually happening.

What is a Backend?

Your frontend (HTML, React, etc.) runs in the user's browser. The backend runs on a server — it handles logic, talks to databases, authenticates users, and returns data. The browser never sees the backend code directly; it only sees responses.

REQUEST / RESPONSE CYCLE
Browser
frontend
→ HTTP →
Server
your backend
→ query →
Database
Postgres, Mongo…
GET /api/listings
Route handler runs
JSON response

A backend is just code that listens for requests. It could be a Node.js Express app, a Python FastAPI service, or a set of serverless functions. The platform (Vercel or Railway) is what runs that code and makes it reachable from the internet.

Connecting a GitHub Repo

Both Vercel and Railway work the same fundamental way: you authorize them to read your GitHub repo, pick the repo, and they take it from there. Every push to main triggers a new deploy automatically.

01

Authorize GitHub

Grant the platform OAuth access to your repos (you can scope it to specific repos only).

02

Pick your repo & branch

Select which repo to deploy and which branch is your production branch (usually main).

03

Set environment variables

Add secrets (API keys, DB connection strings) as env vars in the dashboard — never in code.

04

Deploy

The platform clones your repo, runs your build command, and starts serving traffic.

BLUF: Your GitHub repo is the source of truth. The platform is just the engine that runs it.

Vercel

Vercel is built for frontend frameworks — Next.js especially (they created it). Its backend story is serverless functions: short-lived, stateless functions that spin up per request and disappear. No always-on server.

// pages/api/listings.js ← Vercel auto-routes this as /api/listings
export default function handler(req, res) {
  const data = { listings: ["123 Main St", "456 Oak Ave"] };
  res.status(200).json(data);
}

Drop a file in /api — Vercel turns it into an endpoint. No Express setup, no port config, no server to manage.

  • Zero-config deploy for Next.js, Nuxt, SvelteKit, Astro
  • Edge Network — your functions run close to users globally
  • Preview deployments on every PR automatically
  • Generous free tier (Hobby plan)
  • Functions max out at 60s execution — no long-running processes
  • No persistent disk, no background jobs, no websockets (on free)

Railway

Railway runs your code as a persistent service inside a container. If you have an Express app, a FastAPI server, or a worker process, Railway runs it continuously — just like a real server, without you managing infrastructure.

# Railway detects this automatically, or you set it in dashboard
# Start command: node server.js

// server.js — a real persistent Express server
const express = require('express');
const app = express();

app.get('/api/listings', (req, res) => {
  res.json({ listings: ["123 Main St"] });
});

app.listen(process.env.PORT || 3000);

Railway also provisions databases (Postgres, MySQL, Redis, MongoDB) as separate services in the same project. Your backend env var gets the connection string automatically — no copy-pasting credentials.

  • Runs any language, any framework — Node, Python, Go, Ruby, Rust
  • One-click Postgres/Redis provisioning inside your project
  • Persistent processes — websockets, background workers, cron jobs all work
  • No cold starts — your server is always running
  • Free tier is limited ($5 credit/month then usage-based)
  • Less magic for Next.js — you configure more yourself

Side-by-Side

Vercel
// serverless · frontend-first
  • Functions only (no persistent server)
  • Best for: Next.js, JAMstack, API routes
  • Global edge CDN included
  • PR preview URLs out of the box
  • Max function duration: 60s (Pro)
  • No built-in DB (use Neon, PlanetScale, etc.)
Railway
// containers · backend-first
  • Full persistent server process
  • Best for: Express, FastAPI, workers, cron
  • Run any language or runtime
  • Built-in Postgres, Redis, MySQL
  • No execution time limits
  • Websockets and long polling work

When to Use Which

Use Case Platform Why
Next.js full-stack app Vercel Designed for it. Zero config.
Standalone Express / FastAPI API Railway Needs a persistent server process.
Background job / queue worker Railway Vercel functions die after the request.
Websocket / real-time app Railway Needs persistent connections.
Simple CRUD API with Postgres Either Railway has it built in; Vercel + Neon is equally easy.
Static site + a few API endpoints Vercel Free tier, instant deploy, no overhead.
Scraper / long-running task Railway Functions time out; Railway doesn't.

Environment Variables & Secrets

Neither platform stores secrets in your code — you set them in the dashboard and they're injected at runtime. Your .env file never leaves your machine.

# .env (local dev, in .gitignore)
DATABASE_URL=postgresql://localhost:5432/mydb
OPENAI_API_KEY=sk-...

# In your code — works the same locally and in production
const db = connect(process.env.DATABASE_URL);
const ai = process.env.OPENAI_API_KEY;
Rule: If it's a secret, it's an env var. If it's in your repo, it's not a secret.