Skip to content

NETLIFY_DEPLOYMENT_COMPLETE_GUIDE.md

Latest commit

 

History

History
294 lines (225 loc) · 7.61 KB

NETLIFY_DEPLOYMENT_COMPLETE_GUIDE.md

File metadata and controls

294 lines (225 loc) · 7.61 KB

🚀 Complete Netlify Deployment Guide - MMU Digital Campus

⚠️ IMPORTANT: Avoiding "Page Not Found" Errors

This guide ensures ZERO 404 errors when deploying your React + Vite SPA to Netlify.

📋 Pre-Deployment Checklist

✅ Files Already Configured (Ready to Deploy)

  • netlify.toml - ✅ TOML syntax validated and error-free
  • public/_redirects - ✅ SPA routing configured
  • public/sitemap.xml - ✅ SEO optimization
  • Build configuration - ✅ Vite optimized for production
  • Environment variables - ✅ Properly configured

🔧 Step 1: Verify Configuration Files

1.1 Check netlify.toml (Already Fixed)

Our netlify.toml is validated and includes:

[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "18"
  NODE_ENV = "production"
  GENERATE_SOURCEMAP = "false"

# SPA redirect rules for React Router
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

1.2 Verify _redirects File

Check that public/_redirects contains:

/*    /index.html   200

1.3 Verify Build Output

Run local build to confirm:

npm run build

✅ Should create dist/ folder with index.html

🌐 Step 2: Deploy to Netlify

Option A: GitHub Integration (Recommended)

2.1 Connect Repository

  1. Go to netlify.com and log in
  2. Click "New site from Git"
  3. Choose GitHub and authorize Netlify
  4. Select repository: SK3CHI3/MMU-E-LRNG-

2.2 Configure Build Settings

Netlify will auto-detect from netlify.toml, but verify:

  • Branch to deploy: main
  • Build command: npm run build
  • Publish directory: dist
  • Node.js version: 18

2.3 Environment Variables

In Netlify dashboard → Site settings → Environment variables:

Required Variables:

NODE_VERSION=18
NODE_ENV=production
GENERATE_SOURCEMAP=false

Supabase Variables (if using):

VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

2.4 Deploy

  1. Click "Deploy site"
  2. Wait for build completion (2-3 minutes)
  3. Site will be available at: https://random-name.netlify.app

Option B: Manual Deploy (Alternative)

# 1. Build the project
npm run build

# 2. Install Netlify CLI
npm install -g netlify-cli

# 3. Login to Netlify
netlify login

# 4. Deploy
netlify deploy --prod --dir=dist

🔍 Step 3: Verify Deployment

3.1 Test Homepage

  • ✅ Visit your Netlify URL
  • ✅ Homepage should load correctly

3.2 Test SPA Routing

  • ✅ Navigate to different pages using menu
  • ✅ Refresh any page (should NOT show 404)
  • ✅ Enter URLs directly in browser (should work)

3.3 Test Specific Routes

Test these URLs directly:

  • https://your-site.netlify.app/login
  • https://your-site.netlify.app/register
  • https://your-site.netlify.app/dashboard
  • https://your-site.netlify.app/guest

All should work without 404 errors!

🚨 Troubleshooting Common Issues

Issue 1: "Page Not Found" on Refresh

Cause: Missing SPA redirect configuration Solution:

  1. Verify public/_redirects file exists with content: /* /index.html 200
  2. Verify netlify.toml has redirect rule
  3. Redeploy site

Issue 2: "Page Not Found" on Direct URL Access

Cause: Same as Issue 1 Solution: Same as Issue 1

Issue 3: Build Fails - "vite: command not found" (Exit Code 127)

Cause: Vite dependency not found during build Solution:

  1. ✅ FIXED: Updated netlify.toml with npm install && npm run build
  2. ✅ FIXED: Added .nvmrc file with Node.js version 18
  3. ✅ VERIFIED: Vite is in devDependencies and build works locally
  4. Verify NODE_VERSION=18 in Netlify environment variables
  5. Check build logs for dependency installation errors

Issue 4: Build Fails - General

Cause: Missing dependencies or wrong Node version Solution:

  1. Check build logs in Netlify dashboard
  2. Verify NODE_VERSION=18 in environment variables
  3. Check package.json for correct dependencies

Issue 5: Environment Variables Not Working

Cause: Variables not prefixed with VITE_ or not set in Netlify Solution:

  1. Prefix client-side variables with VITE_
  2. Set variables in Netlify dashboard (not in code)
  3. Redeploy after setting variables

Issue 6: Assets Not Loading

Cause: Incorrect asset paths Solution:

  1. Check Vite configuration
  2. Verify assets are in public/ folder
  3. Check browser console for 404 errors

🔒 Step 4: Security & Performance

4.1 Security Headers (Already Configured)

Our netlify.toml includes:

  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block
  • X-Content-Type-Options: nosniff
  • Referrer-Policy: strict-origin-when-cross-origin

4.2 Caching (Already Configured)

  • Static assets: 1 year cache
  • Fonts: 1 year cache
  • Images: 1 year cache

4.3 Performance Optimization

  • Gzip compression: ✅ Automatic
  • Asset optimization: ✅ Vite handles
  • Code splitting: ✅ Implemented

🌐 Step 5: Custom Domain (Optional)

5.1 Add Custom Domain

  1. In Netlify dashboard → Domain settings
  2. Click "Add custom domain"
  3. Enter domain: mmu-elearning.ac.ke

5.2 DNS Configuration

Point your domain to Netlify:

  • A Record: 75.2.60.5
  • AAAA Record: 2600:1f14:e22:d200::1
  • Or CNAME: your-site-name.netlify.app

5.3 SSL Certificate

  • ✅ Automatic SSL provisioning
  • ✅ Free Let's Encrypt certificate
  • ✅ Usually ready in 24-48 hours

📊 Step 6: Post-Deployment Verification

6.1 Complete Testing Checklist

  • Homepage loads correctly
  • All navigation links work
  • Page refresh works on all routes
  • Direct URL access works
  • Mobile responsiveness verified
  • Authentication flow functional
  • Guest portal accessible
  • Announcements popup works
  • Forms submit correctly
  • Images and assets load

6.2 Performance Check

Run Lighthouse audit:

  • Performance: Should be 90+
  • Accessibility: Should be 90+
  • Best Practices: Should be 90+
  • SEO: Should be 90+

🎯 Expected Results

✅ What Should Work

  • ✅ Homepage loads instantly
  • ✅ All routes accessible via navigation
  • ✅ Page refresh works on any route
  • ✅ Direct URL access works
  • ✅ Back/forward browser buttons work
  • ✅ Mobile and desktop responsive
  • ✅ Fast loading times
  • ✅ SEO optimized

❌ What Should NOT Happen

  • ❌ No "Page Not Found" errors
  • ❌ No 404 errors on refresh
  • ❌ No broken navigation
  • ❌ No missing assets
  • ❌ No slow loading times

📞 Support & Resources

If You Still Get 404 Errors

  1. Check Deploy Logs: Netlify dashboard → Deploys → View logs
  2. Verify Files: Download deploy and check for index.html in root
  3. Test Locally: Run npm run build && npx serve dist
  4. Check Browser Console: Look for JavaScript errors

Helpful Resources

🎉 Success!

Your MMU Digital Campus should now be:

  • ✅ Deployed successfully on Netlify
  • ✅ Zero 404 errors on any route
  • ✅ Fast and responsive on all devices
  • ✅ SEO optimized for search engines
  • ✅ Production ready for users

Live URL: https://your-site-name.netlify.app

🚀 Deployment Complete - No More Page Not Found Errors!