Production Build

Build, optimize, and deploy the MLM CMMS application for production environments

Overview

The MLM CMMS application uses Vite as its build tool to create optimized production bundles. This guide covers the complete build process, optimization strategies, and deployment configuration.

Build Configuration

Vite Configuration

The application’s build is configured in vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import pkg from './package.json' with { type: 'json' }

export default defineConfig({
  plugins: [react(), tailwindcss()],
  define: {
    __APP_VERSION__: JSON.stringify(pkg.version),
  },
})

Key Features:

• React Fast Refresh for development
• TailwindCSS v4 integration via Vite plugin
• Automatic version injection from package.json

Package.json Scripts

The application provides multiple build scripts:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "build:qa": "vite build --mode qa",
    "build:prod": "vite build --mode production",
    "preview": "vite preview",
    "lint": "eslint .",
    "preversion": "npm run lint && npm run build",
    "postversion": "git push && git push --tags"
  }
}

Build Process

Development Build

For local development with hot module replacement:

npm run dev

This starts a development server at http://localhost:5173 with:

• Fast HMR (Hot Module Replacement)
• Source maps for debugging
• Unminified code

QA/Staging Build

For QA and staging environments:

1. Configure QA Environment

   Create .env.qa with QA-specific variables:

   VITE_SUPABASE_URL=https://qa-project.supabase.co
   VITE_SUPABASE_ANON_KEY=your_qa_anon_key
   VITE_WEB_PUSH_PUBLIC_KEY=your_qa_vapid_key
   
2. Run QA Build

   npm run build:qa
   

   This command:

   1. Uses .env.qa for environment variables
   2. Creates optimized build in dist/
   3. Applies production optimizations
3. Test Build Locally

   npm run preview
   

   Serves the built files at http://localhost:4173 for testing.

Production Build

For production deployment:

1. Set Production Environment

   Create .env.production with production credentials:

   VITE_SUPABASE_URL=https://prod-project.supabase.co
   VITE_SUPABASE_ANON_KEY=your_prod_anon_key
   VITE_WEB_PUSH_PUBLIC_KEY=your_prod_vapid_key
   
2. Run Pre-build Validation

   npm run lint
   

   Ensures code quality before building.

3. Execute Production Build

   npm run build:prod
   

   This performs:

   • TypeScript compilation (tsc -b)
   • Vite production build
   • Asset optimization and minification
   • Chunk splitting for optimal loading
   • Source map generation (optional)

Build Output

After building, the dist/ directory contains:

dist/
├── index.html              # Entry HTML file
├── assets/
│   ├── index-[hash].js    # Main JavaScript bundle
│   ├── vendor-[hash].js   # Third-party dependencies
│   ├── index-[hash].css   # Compiled styles
│   └── [various assets]   # Images, fonts, etc.
├── _headers               # HTTP security headers
├── _redirects             # SPA routing redirect rules
├── sw.js                  # Service Worker for PWA
├── manifest.webmanifest   # PWA manifest
└── offline.html          # Offline fallback page

Asset Optimization

Vite automatically applies:

Code Splitting

Automatically splits vendor dependencies and route-based chunks for faster initial load.

Minification

Minifies JavaScript and CSS using esbuild for maximum compression.

Tree Shaking

Removes unused code from the final bundle.

Asset Hashing

Adds content hashes to filenames for optimal cache busting.

HTTP Headers Configuration

The public/_headers file configures security and caching headers:

/*
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  X-Frame-Options: SAMEORIGIN
  Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=()

/sw.js
  Cache-Control: no-cache, no-store, must-revalidate
  Service-Worker-Allowed: /

/manifest.webmanifest
  Cache-Control: no-cache, no-store, must-revalidate

/offline.html
  Cache-Control: no-cache, no-store, must-revalidate

/*.html
  Cache-Control: no-cache, no-store, must-revalidate

/assets/*
  Cache-Control: public, max-age=31536000, immutable

These headers are automatically applied by platforms like Netlify and Vercel that support _headers files.

Security Headers Explained

• X-Content-Type-Options: nosniff - Prevents MIME type sniffing
• Referrer-Policy - Controls referrer information sent with requests
• X-Frame-Options: SAMEORIGIN - Prevents clickjacking attacks
• Permissions-Policy - Restricts browser features for security

Caching Strategy

• Service Worker & Manifests: No caching (always fresh)
• HTML Files: No caching (ensures latest app shell)
• Hashed Assets: Immutable long-term caching (1 year)

SPA Routing Configuration

The public/_redirects file enables client-side routing:

/*    /index.html   200

This configuration:

• Redirects all routes to index.html
• Maintains the URL for React Router
• Returns HTTP 200 status (not 404)
• Enables proper SPA navigation

Without this redirect rule, direct navigation to routes like /kanban or /tickets/123 will result in 404 errors.

Deployment Platforms

Netlify Deployment

1. Connect Repository

   Connect your GitHub repository to Netlify.

2. Configure Build Settings

   • Build command: npm run build:prod
   • Publish directory: dist
   • Node version: 18 or higher
3. Set Environment Variables

   Add environment variables in Netlify dashboard:

   • VITE_SUPABASE_URL
   • VITE_SUPABASE_ANON_KEY
   • VITE_WEB_PUSH_PUBLIC_KEY
4. Deploy

   Netlify automatically builds and deploys on every push to main branch.

Vercel Deployment

1. Import Project

   Import your repository in Vercel dashboard.

2. Configure Framework

   Select “Vite” as the framework preset.

3. Override Build Settings

   • Build Command: npm run build:prod
   • Output Directory: dist
4. Add Environment Variables

   Configure production environment variables in project settings.

Static Hosting (Generic)

For any static hosting provider:

Build Locally

# Build the application
npm run build:prod

# The dist/ directory contains all files
ls -la dist/

Upload to Server

Upload the entire dist/ directory contents to your web server root:

# Example using rsync
rsync -avz dist/ user@server:/var/www/html/

# Example using SCP
scp -r dist/* user@server:/var/www/html/

Configure Server

Ensure your web server:

• Serves index.html for all non-file routes
• Applies headers from _headers (if supported)
• Serves files over HTTPS
• Supports HTTP/2 for better performance

PWA Configuration

The application includes Progressive Web App features:

Service Worker

public/sw.js provides:

• Offline support
• Asset caching strategies
• Background sync for push notifications
• Cache-first strategy for static assets

Web App Manifest

public/manifest.webmanifest defines:

• App name and icons
• Display mode (standalone)
• Theme colors
• Start URL

PWA features require HTTPS in production. Push notifications will not work over HTTP.

Build Optimization Tips

1. Analyze Bundle Size

   Add the rollup-plugin-visualizer:

   npm install --save-dev rollup-plugin-visualizer
   

   Update vite.config.ts to generate bundle analysis.

2. Lazy Load Routes

   Use React.lazy() for route-based code splitting:

   const KanbanPage = lazy(() => import('./pages/KanbanPage'))
   
3. Optimize Images

   • Use WebP format for images
   • Compress images before adding to repository
   • Use responsive images with srcset
4. Monitor Bundle Size

   Set up bundle size monitoring in CI/CD to prevent regressions.

Release Management

The project includes semantic versioning scripts:

# Patch release (0.0.x)
npm run release:patch

# Minor release (0.x.0)
npm run release:minor

# Major release (x.0.0)
npm run release:major

Each release script:

1. Runs npm run lint (via preversion)
2. Runs npm run build (via preversion)
3. Increments version in package.json
4. Creates a git commit with message “chore(release): x.x.x”
5. Creates a git tag
6. Pushes commit and tags to remote (via postversion)

Ensure all tests pass and the build succeeds before running release scripts. The preversion hook will fail if linting or building fails.

Troubleshooting

Build Fails with TypeScript Errors

# Clear TypeScript cache
rm -rf node_modules/.cache

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Run build again
npm run build

Environment Variables Not Applied

• Ensure variable names are prefixed with VITE_
• Restart the build process after changing .env files
• Verify the correct .env file is being used for your build mode

Assets Not Loading After Deployment

• Check that the base URL is correct in vite.config.ts
• Verify all files in dist/assets/ were uploaded
• Check browser console for CORS errors
• Ensure Content-Type headers are correct

Service Worker Not Updating

// Force service worker update
navigator.serviceWorker.getRegistrations().then(function(registrations) {
  for(let registration of registrations) {
    registration.unregister()
  }
})

Next Steps

Supabase Configuration

Complete the deployment by configuring Edge Functions, Storage, and Realtime in Supabase.