Skip to main content

​
Deployment Platform

The application is deployed on Vercel, the platform built by the creators of Next.js. Vercel provides:
  • Zero-config deployments for Next.js applications
  • Automatic CI/CD from GitHub
  • Preview deployments for every pull request
  • Edge network for global performance
  • Built-in analytics and monitoring
Vercel automatically detects Next.js projects and configures optimal build settings.

​
Deployment Workflow

The project follows a Git-based deployment workflow:

​
Branch Strategy

  • main - Production branch (protected)
  • feature/* - Feature development branches
  • fix/* - Bug fix branches
  • refactor/* - Code refactoring branches

​
Feature Development Process

1

Create a feature branch

Start by creating a new branch from main:
git checkout main
git pull origin main
git checkout -b feature/your-feature-name
2

Develop and test locally

Make changes and test in your local environment:
bun run dev
bun run typecheck
bun run lint
3

Commit and push changes

Follow conventional commit format:
git add .
git commit -m "feat: add inventory dashboard"
git push origin feature/your-feature-name
Use conventional commit prefixes:
  • feat: - New features
  • fix: - Bug fixes
  • refactor: - Code refactoring
  • style: - UI/styling changes
  • docs: - Documentation updates
  • chore: - Maintenance tasks
4

Create a pull request

Create a PR using GitHub CLI or web interface:
gh pr create --title "Feature: inventory dashboard" --body "Adds new inventory management dashboard with real-time stock levels"
5

Review preview deployment

Vercel automatically creates a preview deployment for your PR. The preview URL will be posted as a comment by the Vercel bot.
# Check deployment status
vercel ls
Share the preview URL with stakeholders for review.
6

Merge after approval

Important: Wait for user approval before merging.
# Merge via CLI (after approval)
gh pr merge --merge
Never merge PRs automatically. Always wait for explicit user approval.
7

Production deployment

Once merged to main, Vercel automatically deploys to production.The deployment typically completes in 1-2 minutes.

​
Vercel Configuration

​
Automatic Deployments

Vercel monitors your GitHub repository:
BranchDeployment TypeURL Pattern
mainProductionyour-app.vercel.app
Feature branchesPreviewyour-app-git-branch-name.vercel.app
Pull requestsPreviewyour-app-pr-123.vercel.app

​
Build Settings

Vercel automatically detects Next.js and uses optimal settings: 
{
  "buildCommand": "next build",
  "outputDirectory": ".next",
  "installCommand": "bun install",
  "devCommand": "next dev"
}

​
Environment Variables

Manage environment variables in Vercel dashboard:
1

Access Vercel dashboard

Navigate to your project settings: https://vercel.com/your-org/your-app/settings
2

Add environment variables

Go to Settings → Environment VariablesAdd variables for different environments:
  • Production
  • Preview
  • Development
3

Reference in code

Access environment variables in your application:
// Server-side (RSC, API routes)
const apiKey = process.env.API_KEY

// Client-side (must be prefixed with NEXT_PUBLIC_)
const publicKey = process.env.NEXT_PUBLIC_API_URL
Never commit sensitive data to git. Use environment variables for API keys, database credentials, and secrets.

​
Local Environment Variables

For local development, create a .env.local file:
.env.local
# Database
DATABASE_URL="postgresql://..."

# API Keys
API_KEY="your-api-key"

# Public variables (accessible in browser)
NEXT_PUBLIC_API_URL="https://api.example.com"
The .env.local file is automatically ignored by git.

​
Deployment Commands

​
Using Vercel CLI

Install Vercel CLI for manual deployments: 
bun add -g vercel

​
Checking Deployment Status

# List all deployments
vercel ls

# Get deployment details
vercel inspect <deployment-url>

# View deployment logs
vercel logs <deployment-url>

​
GitHub Integration

​
Pull Request Workflow

When you create a PR, Vercel automatically:
  1. Builds your changes
  2. Deploys to a preview URL
  3. Comments on the PR with the preview link
  4. Runs checks and reports build status

​
PR Checks

Vercel runs these checks on every PR:
  • ✓ Build successful
  • ✓ Type checking passed
  • ✓ No build errors
  • ✓ Preview deployment ready

​
Using GitHub CLI

Manage PRs efficiently with GitHub CLI: 
# Create PR
gh pr create --title "Title" --body "Description"

# List PRs
gh pr list

# View PR status (avoid deprecated API)
gh pr view <pr-number> --json title,state,url,mergeable,reviewDecision

# Check if merged
gh pr view <pr-number> --json state,mergedAt,mergedBy,url

# Merge PR (after approval only)
gh pr merge <pr-number> --merge
Always use gh pr view --json with specific fields to avoid errors from GitHub’s deprecated Projects API.

​
Build Optimization

The production build is automatically optimized:

​
Next.js Optimizations

  • Code splitting - Automatic per-route code splitting
  • Image optimization - Automatic image resizing and WebP conversion
  • Font optimization - Self-hosted Google Fonts with zero layout shift
  • JavaScript minification - Automatic via SWC compiler
  • CSS optimization - PostCSS with Tailwind purging

​
Build Output

Run bun run build to see build analysis: 
bun run build

# Output shows:
# - Page sizes
# - First Load JS size
# - Static pages (○)
# - Server-rendered pages (ƒ)
# - Edge runtime pages (ℇ)

​
Monitoring & Analytics

​
Vercel Analytics

Enable analytics in Vercel dashboard:
  • Web Vitals - Core Web Vitals metrics
  • Real User Monitoring - Performance data from real users
  • Audience insights - Visitor demographics

​
Error Tracking

Integrate error tracking (optional): 
bun add @vercel/analytics @vercel/speed-insights
app/layout.tsx
import { Analytics } from '@vercel/analytics/react'
import { SpeedInsights } from '@vercel/speed-insights/next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
        <SpeedInsights />
      </body>
    </html>
  )
}

​
Rollback Strategy

If issues occur in production:
1

Identify the issue

Check Vercel dashboard for deployment logs and errors.
2

Instant rollback

In Vercel dashboard:
  1. Go to Deployments
  2. Find the last working deployment
  3. Click ⋯ → Promote to Production
3

Fix and redeploy

git checkout main
git revert <commit-hash>
git push origin main

​
Production Checklist

Before merging to production:
  • All tests pass locally
  • TypeScript compilation succeeds (bun run typecheck)
  • Linting passes (bun run lint)
  • Code is formatted (bun run format)
  • Preview deployment reviewed and approved
  • No console errors in browser
  • Dark mode tested
  • Responsive design verified
  • Environment variables configured
  • No sensitive data in code

​
Best Practices

Never push directly to main. Always create a PR and review the preview deployment first.
The main branch should always be deployable. Use feature branches for all changes.
Run all quality checks before creating a PR:
bun run typecheck && bun run lint && bun run format
Follow the commit convention for clear history:
feat: add new feature
fix: resolve bug in component
refactor: improve code structure
Keep an eye on Vercel dashboard for build failures and performance metrics.

​
Troubleshooting

​
Build Failures

If the Vercel build fails:
  1. Check build logs in Vercel dashboard
  2. Run bun run build locally to reproduce
  3. Fix errors and push changes
  4. Vercel automatically retries the build

​
Preview Deployment Issues

If preview URL doesn’t load:
  1. Wait for build to complete (check status in PR)
  2. Clear browser cache
  3. Check Vercel function logs for runtime errors

​
Environment Variable Issues

If environment variables aren’t working:
  1. Verify variables are set in Vercel dashboard
  2. Check environment (Production/Preview/Development)
  3. Client-side variables must start with NEXT_PUBLIC_
  4. Redeploy to apply new variables

​
Next Steps

Development Setup

Set up your local development environment

Vercel Documentation

Explore Vercel platform documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us