Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
218 lines (163 loc) · 4.67 KB

DEPLOYMENT.md

File metadata and controls

218 lines (163 loc) · 4.67 KB
Raw

Deployment Guide for Recalla PWA

Development

npm install          # Install dependencies
npm run dev         # Start development server (http://localhost:5173)
npm run build       # Build for production
npm run preview     # Preview production build

Deploy to GitHub Pages (Recommended - Automated)

This repository includes a GitHub Actions workflow for automatic deployment!

Quick Setup (3 steps):

  1. Enable GitHub Pages:

    • Go to Settings → Pages
    • Set Source to "GitHub Actions"

  2. Push to main branch:

    git push origin main

  3. Access your app:

    • Wait 2-3 minutes for the workflow to complete
    • Visit: https://officiallygod.github.io/Recalla/

For detailed instructions and troubleshooting, see GITHUB_ACTIONS_GUIDE.md

The workflow automatically:

  • ✅ Installs dependencies
  • ✅ Builds your app
  • ✅ Deploys to GitHub Pages
  • ✅ Runs on every push to main
  • ✅ Can be triggered manually from Actions tab

Deploy to Vercel (Alternative)

  1. Push your code to GitHub
  2. Go to vercel.com and sign up
  3. Click "New Project" and import your repository
  4. Vercel will auto-detect Vite - just click "Deploy"

That's it! Vercel will:

  • Build your app automatically
  • Provide HTTPS
  • Enable PWA features
  • Give you a live URL

Deploy to Netlify

  1. Sign up at netlify.com
  2. Click "New site from Git"
  3. Connect your GitHub repository
  4. Build settings:
    • Build command: npm run build
    • Publish directory: dist
  5. Click "Deploy site"

Deploy to GitHub Pages (Manual Method)

If you prefer manual deployment instead of automated GitHub Actions:

  1. Install the gh-pages package:
npm install --save-dev gh-pages
  1. Add to package.json:
{
  "homepage": "https://yourusername.github.io/Recalla",
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  }
}
  1. Update vite.config.js:
export default defineConfig({
  base: '/Recalla/',
  // ... rest of config
})
  1. Deploy:
npm run deploy

Deploy to Cloudflare Pages

  1. Sign up at pages.cloudflare.com
  2. Connect your GitHub repository
  3. Build settings:
    • Build command: npm run build
    • Build output directory: dist
    • Node version: 18 or higher
  4. Deploy

Deploy to Any Static Host

Build the app:

npm run build

Upload the contents of the dist/ folder to your hosting:

  • AWS S3 + CloudFront
  • Firebase Hosting
  • Azure Static Web Apps
  • DigitalOcean App Platform
  • Railway
  • Render

Environment Variables

If you add environment variables later (for API keys, etc.), create a .env file:

VITE_API_URL=your_api_url
VITE_API_KEY=your_api_key

Access in code:

const apiUrl = import.meta.env.VITE_API_URL

HTTPS Requirement

PWA features (service worker, installation) require HTTPS in production. All hosting services listed above provide HTTPS automatically.

Testing Production Build Locally

npm run build
npm run preview

Open http://localhost:4173 to test the production build locally.

Custom Domain

Most hosting providers allow custom domains:

  1. Vercel: Project Settings → Domains → Add
  2. Netlify: Site Settings → Domain Management → Add custom domain
  3. Cloudflare: Configure in Pages settings

Performance Tips

  1. Image Optimization: Use WebP format for images
  2. Code Splitting: Vite handles this automatically
  3. Lazy Loading: Use React.lazy() for route components
  4. Bundle Analysis: Add rollup-plugin-visualizer

Troubleshooting

Build fails

  • Ensure Node.js version is 18+
  • Clear cache: rm -rf node_modules dist && npm install
  • Check for TypeScript errors if using TS

PWA not working

  • Must be served over HTTPS (except localhost)
  • Check service worker registration in DevTools
  • Clear browser cache and reload

Routing issues (404 on refresh)

Add a _redirects file (Netlify) or vercel.json (Vercel):

Netlify (public/_redirects):

/*    /index.html   200

Vercel (vercel.json):

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

Cache Busting

Vite automatically adds content hashes to filenames for cache busting. When you deploy a new version:

  1. Users will automatically get the latest version
  2. Service worker will update in the background
  3. No manual cache clearing needed

Monitoring

Consider adding:

  • Google Analytics
  • Sentry for error tracking
  • Web Vitals monitoring

Updates

To update dependencies:

npm update
npm audit fix

For major version updates:

npx npm-check-updates -u
npm install