Deployment Guide

Overview

School Science is a static React application built with Vite, making it easy to deploy to various hosting platforms. This guide covers deployment to popular services.

Vercel Deployment (Recommended)

Vercel offers the fastest and easiest deployment for Vite applications, with zero configuration required.

Automatic Deployment from GitHub

Push to GitHub

Ensure your code is pushed to a GitHub repository:

git add .
git commit -m "Prepare for deployment"
git push origin main

Connect to Vercel

Visit vercel.com
Sign up or log in with your GitHub account
Click “Add New Project”
Import your School Science repository

Configure Project

Vercel auto-detects Vite settings:

Framework Preset: Vite
Build Command: npm run build
Output Directory: dist
Install Command: npm install

These are correct - no changes needed!

Deploy

Click “Deploy” and wait 1-2 minutes. Your site will be live at:

https://your-project.vercel.app

Every push to your main branch automatically triggers a new deployment. Preview deployments are created for pull requests.

Vercel Configuration File

The project includes vercel.json for proper SPA routing:

vercel.json

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

This ensures all routes (like /proyecto/franklin-bell) work correctly.

Vercel CLI Deployment

Deploy directly from terminal:

# Install Vercel CLI
npm install -g vercel

# Login
vercel login

# Deploy
vercel

# Deploy to production
vercel --prod

Netlify Deployment

Netlify is another excellent option for static sites.

Automatic Deployment from GitHub

Connect Repository

Visit netlify.com
Click “Add new site” → “Import an existing project”
Connect your GitHub account and select repository

Configure Build Settings

Set these build parameters:

Build command: npm run build
Publish directory: dist
Base directory: (leave empty)

Deploy Site

Click “Deploy site” and wait for build to complete.Your site will be live at:

https://random-name-123456.netlify.app

Add Redirect Rules

Create public/_redirects file for SPA routing:

public/_redirects

/*    /index.html   200

Commit and push this file for proper routing.

Netlify CLI Deployment

# Install Netlify CLI
npm install -g netlify-cli

# Login
netlify login

# Initialize site
netlify init

# Deploy
netlify deploy

# Deploy to production
netlify deploy --prod

GitHub Pages Deployment

Deploy to GitHub Pages for free hosting.

Configuration Steps

Update Vite Config

Modify vite.config.js to set the base path:

vite.config.js

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/SchoolScience/',  // Replace with your repo name
})

Install gh-pages Package

npm install --save-dev gh-pages

Add Deploy Scripts

Update package.json:

package.json

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  }
}

Deploy

npm run deploy

Your site will be available at:

https://yourusername.github.io/SchoolScience/

Configure GitHub Pages

Go to repository Settings → Pages
Set Source to “gh-pages” branch
Save and wait a few minutes

Remember to update the base path in vite.config.js to match your repository name exactly.

Custom Domain Setup

Vercel Custom Domain

Access Domain Settings

In Vercel dashboard, go to your project → Settings → Domains

Add Domain

Enter your domain name (e.g., schoolscience.com)

Configure DNS

Add these DNS records at your domain registrar:

Type: A
Name: @
Value: 76.76.21.21

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

Verify and Wait

Verification can take up to 48 hours for DNS propagation.

Netlify Custom Domain

Access Domain Settings

Go to Site settings → Domain management → Add custom domain

Add Domain

Enter your domain and click “Verify”

Configure DNS

Option 1 - Use Netlify DNS (easiest):

Transfer DNS management to Netlify
Update nameservers at registrar

Option 2 - External DNS:

Type: A
Name: @
Value: 75.2.60.5

Type: CNAME
Name: www
Value: your-site.netlify.app

Enable HTTPS

Netlify automatically provisions SSL certificates via Let’s Encrypt.

Environment Variables

If you add API keys or other sensitive data:

Vercel Environment Variables

Project Settings → Environment Variables

Add variables:

VITE_API_KEY=your-key-here
VITE_API_URL=https://api.example.com

Redeploy for changes to take effect

Netlify Environment Variables

Site settings → Build & deploy → Environment
Add variables with same format
Trigger manual deploy

Using in Code

Access environment variables:

const apiKey = import.meta.env.VITE_API_KEY;
const apiUrl = import.meta.env.VITE_API_URL;

Never commit API keys to Git! Always use environment variables for sensitive data.

Build Optimization

Reduce Bundle Size

Optimize your build:

vite.config.js

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'mui': ['@mui/material', '@mui/icons-material'],
          'router': ['react-router-dom'],
        },
      },
    },
    chunkSizeWarningLimit: 1000,
  },
})

Image Optimization

Compress images before adding to project
Use WebP format for better compression
Lazy load images for faster initial load

Code Splitting

Lazy load routes:

src/App.jsx

import { lazy, Suspense } from 'react';
import { Routes, Route } from 'react-router-dom';

const Home = lazy(() => import('./pages/Home'));
const ProyectoDetalle = lazy(() => import('./pages/ProyectoDetalle'));
const NotFound = lazy(() => import('./pages/404'));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/proyecto/:slug" element={<ProyectoDetalle />} />
        <Route path="*" element={<NotFound />} />
      </Routes>
    </Suspense>
  );
}

Performance Monitoring

Vercel Analytics

Enable analytics in Vercel dashboard:

Project → Analytics tab
Enable Web Analytics
View metrics:
- Page views
- Load times
- Geographic distribution
- Real User Metrics (RUM)

Lighthouse Testing

Test your deployed site:

npm install -g lighthouse
lighthouse https://your-site.vercel.app --view

Target scores:

Performance: >90
Accessibility: >95
Best Practices: >95
SEO: >90

Continuous Deployment

Automatic Deployments

Both Vercel and Netlify support:

Production: Deploys from main branch
Preview: Deploys for every pull request
Branch Deploys: Automatic deploys for specific branches

GitHub Actions

Custom deployment workflow:

.github/workflows/deploy.yml

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Troubleshooting

404 errors on refresh

Problem: Navigating to /proyecto/franklin-bell directly returns 404Solution: Add redirect rules:

Vercel: Already configured in vercel.json
Netlify: Add public/_redirects file
GitHub Pages: Not fully supported, consider hash router

Build fails on deployment

Common causes:

Missing dependencies in package.json
Environment variables not set
Build command incorrect
Node version mismatch

Solution:

Check build logs for specific error
Verify npm run build works locally
Ensure Node version matches (18.x recommended)

Assets not loading

Problem: Images or PDFs return 404Solution:

Verify files exist in public/ directory
Check paths start with / (e.g., /image/photo.jpg)
Clear CDN cache and redeploy

Slow initial load

Solutions:

Implement code splitting with lazy loading
Compress images (use WebP format)
Enable CDN caching
Reduce bundle size with tree shaking
Use Lighthouse to identify bottlenecks

Post-Deployment Checklist

After deploying, verify:

Vercel Documentation

Official Vercel deployment docs

Netlify Documentation

Official Netlify deployment docs

Vite Deployment Guide

Vite’s official deployment guide

GitHub Pages Guide

GitHub Pages documentation

Customization Guide

⌘I

Get Started

Science Projects

Guides

Overview

Vercel Deployment (Recommended)

Automatic Deployment from GitHub

Vercel Configuration File

Vercel CLI Deployment

Netlify Deployment

Automatic Deployment from GitHub

Netlify CLI Deployment

GitHub Pages Deployment

Configuration Steps

Custom Domain Setup

Vercel Custom Domain

Netlify Custom Domain

Environment Variables

Vercel Environment Variables

Netlify Environment Variables

Using in Code

Build Optimization

Reduce Bundle Size

Image Optimization

Code Splitting

Performance Monitoring

Vercel Analytics

Lighthouse Testing

Continuous Deployment

Automatic Deployments

GitHub Actions

Troubleshooting

Post-Deployment Checklist

Vercel Documentation

Netlify Documentation

Vite Deployment Guide

GitHub Pages Guide

Build docs developers (and LLMs) love

Get Started

Science Projects

Guides

​Overview

​Vercel Deployment (Recommended)

​Automatic Deployment from GitHub

​Vercel Configuration File

​Vercel CLI Deployment

​Netlify Deployment

​Automatic Deployment from GitHub

​Netlify CLI Deployment

​GitHub Pages Deployment

​Configuration Steps

​Custom Domain Setup

​Vercel Custom Domain

​Netlify Custom Domain

​Environment Variables

​Vercel Environment Variables

​Netlify Environment Variables

​Using in Code

​Build Optimization

​Reduce Bundle Size

​Image Optimization

​Code Splitting

​Performance Monitoring

​Vercel Analytics

​Lighthouse Testing

​Continuous Deployment

​Automatic Deployments

​GitHub Actions

​Troubleshooting

​Post-Deployment Checklist

​Related Resources

Vercel Documentation

Netlify Documentation

Vite Deployment Guide

GitHub Pages Guide

Build docs developers (and LLMs) love

Overview

Vercel Deployment (Recommended)

Automatic Deployment from GitHub

Vercel Configuration File

Vercel CLI Deployment

Netlify Deployment

Automatic Deployment from GitHub

Netlify CLI Deployment

GitHub Pages Deployment

Configuration Steps

Custom Domain Setup

Vercel Custom Domain

Netlify Custom Domain

Environment Variables

Vercel Environment Variables

Netlify Environment Variables

Using in Code

Build Optimization

Reduce Bundle Size

Image Optimization

Code Splitting

Performance Monitoring

Vercel Analytics

Lighthouse Testing

Continuous Deployment

Automatic Deployments

GitHub Actions

Troubleshooting

Post-Deployment Checklist

Related Resources