Deploy to Vercel

Overview

Vercel is the recommended platform for hosting the Nectr Next.js 15 frontend. This guide covers deploying the React 19 dashboard with proper API connectivity and authentication.

The frontend on Vercel communicates with the backend on Railway. Deploy the backend first before proceeding with this guide.

Prerequisites

Before deploying to Vercel, ensure you have:

A Vercel account
Backend deployed to Railway (see Railway Deployment)
Your Railway backend URL (e.g., https://nectr-production.up.railway.app)

Deployment Steps

Import Project

Log in to Vercel
Click Add New → Project
Import your Nectr GitHub repository
Vercel will automatically detect Next.js

Configure Root Directory

The Next.js app is in the nectr-web/ subdirectory:

In the project settings, set Root Directory to nectr-web
Vercel will detect vercel.json with this configuration:

vercel.json

{
  "rootDirectory": "nectr-web",
  "framework": "nextjs"
}

If you already have vercel.json in your repo root, Vercel will automatically use these settings.

Set Environment Variables

Add the following environment variable in Vercel project settings:

NEXT_PUBLIC_API_URL=https://your-backend.up.railway.app

Important: Replace your-backend.up.railway.app with your actual Railway backend URL.

Do NOT include a trailing slash in NEXT_PUBLIC_API_URL. The frontend appends paths like /api/v1/repos.

Deploy

Click Deploy
Vercel will build and deploy automatically
Monitor the build logs for any errors
Once deployed, copy your Vercel URL (e.g., https://nectr.vercel.app)

Update Backend Environment

Return to Railway and update the FRONTEND_URL environment variable:

FRONTEND_URL=https://nectr.vercel.app

This ensures CORS is configured correctly for authentication cookies.

Update GitHub OAuth App

If you haven’t already, update your GitHub OAuth App’s Homepage URL:

https://nectr.vercel.app

The Authorization callback URL should remain pointing to Railway:

https://your-backend.up.railway.app/auth/github/callback

Verify Deployment

Test Landing Page

Visit your Vercel URL and verify the landing page loads correctly.

Test Authentication

Click Sign in with GitHub
Complete OAuth flow
Verify you’re redirected to /dashboard
Check that the dashboard loads data from the backend

Check API Connectivity

Open browser DevTools → Network tab and verify:

API requests go to your Railway backend URL
Requests include credentials: 'include' for cookies
CORS headers are present in responses

Frontend Architecture

The Next.js frontend uses:

Next.js 15 with App Router
React 19 with Server Components
TailwindCSS 4 for styling
Axios for API requests with credentials

API Client Configuration

The frontend’s API client is configured in nectr-web/src/lib/api.ts:

nectr-web/src/lib/api.ts

import axios from 'axios';

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  withCredentials: true,  // Send httpOnly cookies
});

export default api;

Environment Variable Usage

The NEXT_PUBLIC_API_URL variable is used throughout the app:

Example: useRepos hook

const { data } = await api.get('/api/v1/repos');
// Resolves to: https://your-backend.up.railway.app/api/v1/repos

Continuous Deployment

Vercel automatically deploys on every push:

Push changes to your main branch
Vercel detects the commit
Builds the Next.js app with npm run build
Deploys with zero-downtime
Previous deployment remains active until new one is ready

Preview Deployments

Vercel creates preview deployments for every pull request:

Unique URL per PR
Isolated from production
Automatic cleanup when PR is closed

Preview deployments use the same NEXT_PUBLIC_API_URL as production. Consider creating a staging backend for testing.

Custom Domain

Add a custom domain to your Vercel project:

Add Domain

Go to Vercel project Settings → Domains
Add your domain (e.g., nectr.yourdomain.com)

Configure DNS

Add a CNAME record in your DNS provider:

Type:  CNAME
Name:  nectr
Value: cname.vercel-dns.com

Wait for Verification

Vercel will automatically verify and issue SSL certificates.

Update Environment Variables

Update FRONTEND_URL in Railway to use your custom domain:

FRONTEND_URL=https://nectr.yourdomain.com

Troubleshooting

API requests failing with CORS errors

Symptom: Console shows CORS policy errorsSolution:

Verify FRONTEND_URL is set correctly in Railway
Check that NEXT_PUBLIC_API_URL points to Railway backend
Ensure Railway backend includes CORS middleware:

app.add_middleware(
    CORSMiddleware,
    allow_origins=[settings.FRONTEND_URL],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Authentication not persisting

Symptom: User logged out on page refreshSolution:

Verify cookies are being set by checking DevTools → Application → Cookies
Ensure cookies have these attributes:
- httpOnly: true
- secure: true (requires HTTPS)
- sameSite: "none" (for cross-origin)
Verify withCredentials: true in axios config

Environment variable not updating

Symptom: Changed NEXT_PUBLIC_API_URL but app still uses old valueSolution:

Environment variables are baked into the build at build time
Trigger a new deployment in Vercel after changing variables
Hard refresh the browser (Cmd+Shift+R or Ctrl+Shift+R)

Build failing in Vercel

Symptom: Vercel build logs show errorsSolution:

Check that all dependencies are in nectr-web/package.json
Verify Node.js version compatibility
Test build locally:

cd nectr-web
npm install
npm run build

Check for TypeScript errors

Performance Optimization

Enable Edge Runtime

For faster response times, consider enabling Edge Runtime for API routes:

app/api/route.ts

export const runtime = 'edge';

Image Optimization

Next.js automatically optimizes images. Use the <Image> component:

import Image from 'next/image';

<Image
  src="/logo.png"
  alt="Nectr Logo"
  width={200}
  height={50}
  priority
/>

Analytics

Vercel provides built-in analytics:

Go to project Analytics tab
View page load times, Core Web Vitals, and visitor metrics

Cost Considerations

Vercel pricing tiers:

Hobby: Free for personal projects
Pro: $20/month per user (recommended for production)
Enterprise: Custom pricing

The Hobby plan is sufficient for testing, but production apps should use Pro for better performance and support.

Monitoring & Logs

View Logs

Go to Vercel project → Deployments
Click on a deployment
View Build Logs or Function Logs

Real-Time Logs

Install Vercel CLI for real-time logs:

npm i -g vercel
vercel login
vercel logs https://nectr.vercel.app --follow

Getting Started

Core Features

Integrations

Configuration

Deployment

Overview

Prerequisites

Deployment Steps

Verify Deployment

Frontend Architecture

API Client Configuration

Environment Variable Usage

Continuous Deployment

Preview Deployments

Custom Domain

Troubleshooting

Performance Optimization

Enable Edge Runtime

Image Optimization

Analytics

Cost Considerations

Monitoring & Logs

View Logs

Real-Time Logs

Next Steps

Connect Repositories

Configure Integrations

Build docs developers (and LLMs) love

Getting Started

Core Features

Integrations

Configuration

Deployment

​Overview

​Prerequisites

​Deployment Steps

​Verify Deployment

​Frontend Architecture

​API Client Configuration

​Environment Variable Usage

​Continuous Deployment

​Preview Deployments

​Custom Domain

​Troubleshooting

​Performance Optimization

​Enable Edge Runtime

​Image Optimization

​Analytics

​Cost Considerations

​Monitoring & Logs

​View Logs

​Real-Time Logs

​Next Steps

Connect Repositories

Configure Integrations

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Steps

Verify Deployment

Frontend Architecture

API Client Configuration

Environment Variable Usage

Continuous Deployment

Preview Deployments

Custom Domain

Troubleshooting

Performance Optimization

Enable Edge Runtime

Image Optimization

Analytics

Cost Considerations

Monitoring & Logs

View Logs

Real-Time Logs

Next Steps