Web App Updates & Deployment
This manual provides the standard operating procedures (SOPs) for updating, building, and deploying the PlugZero Analytics web application (plugzero-analytics).
🏗️ 1. Development Environment
The PlugZero frontend is a decoupled Next.js 16 application built with React 19.
Pre-requisites
- Node.js: Version 20.x or higher.
- Package Manager:
npm(Refer topackage-lock.json).
Initial Setup
Ensure the local environment file .env.local is present in the root directory.
# Location: plugzero-analytics/.env.local
NEXT_PUBLIC_BACKEND_API_URL=http://127.0.0.1:8000/apiInstall Dependencies
Run npm install to synchronize your node_modules.
Start Development
Run npm run dev. The app will be available at http://localhost:3000.
🚀 2. Update & Build Pipeline
When preparing an update for production, follows this checklist to avoid build-time failures.
A. Code Quality (Linting)
PlugZero uses ESLint 9. You MUST fix all critical errors before attempting a build:
npm run lintB. Production Build
Next.js optimizes the application by pre-rendering pages and tree-shaking unused code.
npm run build- Output: The compiler generates an optimized version of the app in the
.nextdirectory. - Verification: Ensure no “Type Errors” or “CSS Syntax Errors” appear in the terminal.
C. Local Verification
Test the production build locally before the actual push:
npm run start🌐 3. Deployment Strategy
Infrastructure Protocol
- Production URL: Usually managed via Vercel or a dedicated Node.js server.
- API Mapping: Ensure production variables point to the live API:
api.plugzero.plughathon.com.ng.
Server-Side Synchronization
When updating the frontend, ensure the backend services (Redis, Celery, and Django) are healthy. Use our standard startup script:
# Location: /Users/arop/Projects/plugzero/start_backend.sh
./start_backend.sh🛠️ 4. Troubleshooting Updates
| Issue | Likely Cause | Solution |
|---|---|---|
| Styles not updating | CSS Cache / Tailwind Build | rm -rf .next && npm run build |
| API Connection Refused | Incorrect Env Variable | Verify NEXT_PUBLIC_BACKEND_API_URL. |
| Build Fail: “tw-animate” | Missing Dev Dependency | Run npm install tw-animate-css manually. |
Note: Next.js automatically handles font and image optimization. If you add new assets to public/, they will be optimized during the next build cycle.