Deploying a Next.js App to Vercel Step by Step

Make sure you have these three things ready:

1. A working Next.js app: It should run locally with npm run dev and build without errors with npm run build.
2. A GitHub account: Your code needs to be in a GitHub repository. Vercel also supports GitLab and Bitbucket, but GitHub is the smoothest integration.
3. Your environment variables: If your app uses a database (Supabase), API keys (Daraja, Paystack), or any secrets, have them ready. You will enter them in Vercel's dashboard.

Check your build locally first. This catches most deployment failures before they happen:

npm run build

# If this fails locally, it will fail on Vercel too.
# Fix all errors before deploying.

If your project is not on GitHub yet:

# Initialize Git (if not already done)
git init

# Create a .gitignore if you do not have one
npx gitignore node

# Stage and commit
git add .
git commit -m "Initial commit"

# Create a repository on github.com, then:
git remote add origin https://github.com/yourusername/your-app.git
git branch -M main
git push -u origin main

Make sure your .gitignore excludes node_modules, .env.local, .next, and any other generated or secret files.

Go to vercel.com and sign in with your GitHub account.

1. Click "Add New Project" on your Vercel dashboard.
2. Vercel shows your GitHub repositories. Find yours and click "Import".
3. Vercel auto-detects that it is a Next.js project and pre-fills the build settings:
   Framework Preset: Next.js
Build Command: next build (or npm run build)
   Output Directory: .next
4. You usually do not need to change these defaults.

If Vercel does not auto-detect your framework, check that your package.json has Next.js as a dependency and that it has a build script.

Before clicking Deploy, expand the "Environment Variables" section. Add every variable from your .env.local file:

NEXT_PUBLIC_SUPABASE_URL = https://xyzcompany.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY = eyJhbGciOiJIUzI1NiIs...
DARAJA_CONSUMER_KEY = your_production_key
DARAJA_CONSUMER_SECRET = your_production_secret
DATABASE_URL = postgresql://user:pass@host:5432/db

Important notes:

• Use your production credentials, not sandbox ones.
• Variables starting with NEXT_PUBLIC_ are exposed to the browser. Only use this prefix for values that are safe to be public.
• You can scope variables to specific environments: Production, Preview (pull request deploys), and Development.

You can also add environment variables later from your project settings. If you change them after deployment, you need to redeploy for the changes to take effect:

# Using the Vercel CLI
vercel env add DARAJA_CONSUMER_KEY

# Trigger a redeployment
vercel --prod

Click "Deploy". Vercel clones your repository, installs dependencies, runs npm run build, and deploys the output. You will see a build log in real time.

When it finishes, Vercel gives you a URL like your-app.vercel.app. Your site is live.

Adding a custom domain:

1. Go to your project settings in Vercel, then Domains.
2. Enter your domain name (e.g., myapp.co.ke).
3. Vercel tells you which DNS records to add. Typically:

# For a root domain (myapp.co.ke)
Type: A
Name: @
Value: 76.76.21.21

# For a subdomain (www.myapp.co.ke)
Type: CNAME
Name: www
Value: cname.vercel-dns.com

Add these records at your domain registrar (e.g., KE Hostmaster for .co.ke domains, Namecheap, or Google Domains). DNS propagation can take a few minutes to a few hours.

Vercel automatically provisions an SSL certificate for your domain, so your site will be served over HTTPS.

Build fails with TypeScript errors:

Next.js in production mode type-checks your entire project. Errors that do not show during npm run dev (which only checks the page you are viewing) will fail the build. Fix all TypeScript errors locally with npx tsc --noEmit.

Build fails with "Module not found":

A dependency is missing from package.json. Maybe you installed it globally instead of locally. Run npm install missing-package and commit the updated package.json.

Environment variable is undefined:

Check three things: (1) the variable is set in Vercel's environment settings, (2) it is scoped to the correct environment (Production vs Preview), and (3) you redeployed after adding it.

API routes return 500 errors:

Check the Vercel function logs in your project dashboard under Deployments, then click on the deployment and view Functions. The error message will tell you what went wrong.

Page loads but looks broken (no styles):

Check your Tailwind configuration. Make sure content in tailwind.config.ts includes all files that use Tailwind classes. Also check that you are not importing CSS files from the wrong path.

// tailwind.config.ts
export default {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './src/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  // ...
};