|
| 1 | +# Frontend Development Setup |
| 2 | + |
| 3 | +This guide covers setting up the ThingConnect Pulse frontend React application for local development. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- **Node.js 18+** (LTS recommended) |
| 8 | +- **npm** (comes with Node.js) |
| 9 | +- **Backend server** running on `http://localhost:8080` |
| 10 | + |
| 11 | +## Quick Start |
| 12 | + |
| 13 | +### 1. Install Dependencies |
| 14 | + |
| 15 | +```bash |
| 16 | +cd thingconnect.pulse.client |
| 17 | +npm install |
| 18 | +``` |
| 19 | + |
| 20 | +### 2. Environment Configuration |
| 21 | + |
| 22 | +Copy the example environment file: |
| 23 | + |
| 24 | +```bash |
| 25 | +cp .env.example .env |
| 26 | +``` |
| 27 | + |
| 28 | +The `.env` file should contain: |
| 29 | + |
| 30 | +```env |
| 31 | +# Backend API Configuration |
| 32 | +VITE_API_BASE_URL=http://localhost:8080 |
| 33 | +VITE_API_TIMEOUT=30000 |
| 34 | +
|
| 35 | +# Development Settings |
| 36 | +VITE_ENABLE_DEVTOOLS=true |
| 37 | +VITE_POLLING_INTERVAL=5000 |
| 38 | +
|
| 39 | +# Feature Flags (for future use) |
| 40 | +VITE_ENABLE_REALTIME=false |
| 41 | +``` |
| 42 | + |
| 43 | +### 3. Start Development Server |
| 44 | + |
| 45 | +```bash |
| 46 | +npm run dev |
| 47 | +``` |
| 48 | + |
| 49 | +The frontend will be available at `https://localhost:55610` (or similar port). |
| 50 | + |
| 51 | +## Backend Integration |
| 52 | + |
| 53 | +### CORS Configuration |
| 54 | + |
| 55 | +The frontend runs on HTTPS while the backend runs on HTTP. The backend **must** have CORS configured to allow frontend requests: |
| 56 | + |
| 57 | +```csharp |
| 58 | +// In ThingConnect.Pulse.Server/Program.cs |
| 59 | +builder.Services.AddCors(options => |
| 60 | +{ |
| 61 | + options.AddPolicy("AllowFrontend", policy => |
| 62 | + { |
| 63 | + policy.WithOrigins("https://localhost:55610", "http://localhost:55610", "https://localhost:5173", "http://localhost:5173") |
| 64 | + .AllowAnyHeader() |
| 65 | + .AllowAnyMethod() |
| 66 | + .AllowCredentials(); |
| 67 | + }); |
| 68 | +}); |
| 69 | + |
| 70 | +// And in the middleware pipeline: |
| 71 | +app.UseCors("AllowFrontend"); |
| 72 | +``` |
| 73 | + |
| 74 | +### API Endpoints |
| 75 | + |
| 76 | +The frontend connects to these backend endpoints: |
| 77 | + |
| 78 | +- `GET /api/status/live` - Live endpoint status data |
| 79 | +- `GET /api/history/endpoint/{id}` - Historical data for specific endpoint |
| 80 | +- `POST /api/config/apply` - Apply YAML configuration |
| 81 | +- `GET /api/config/versions` - List configuration versions |
| 82 | + |
| 83 | +## Development Features |
| 84 | + |
| 85 | +### Live Reloading |
| 86 | + |
| 87 | +Vite provides hot module replacement (HMR) for instant updates during development. |
| 88 | + |
| 89 | +### Environment Variables |
| 90 | + |
| 91 | +All environment variables must be prefixed with `VITE_` to be available in the frontend: |
| 92 | + |
| 93 | +- `VITE_API_BASE_URL` - Backend API base URL |
| 94 | +- `VITE_API_TIMEOUT` - API request timeout in milliseconds |
| 95 | +- `VITE_ENABLE_DEVTOOLS` - Enable React Query DevTools |
| 96 | +- `VITE_POLLING_INTERVAL` - Live data refresh interval in milliseconds |
| 97 | + |
| 98 | +### TypeScript |
| 99 | + |
| 100 | +The project uses TypeScript with strict type checking. Type definitions are in: |
| 101 | + |
| 102 | +- `src/api/types.ts` - API response types |
| 103 | +- `src/types/env.d.ts` - Environment variable types |
| 104 | + |
| 105 | +## Common Commands |
| 106 | + |
| 107 | +```bash |
| 108 | +# Start development server |
| 109 | +npm run dev |
| 110 | + |
| 111 | +# Build for production |
| 112 | +npm run build |
| 113 | + |
| 114 | +# Preview production build |
| 115 | +npm run preview |
| 116 | + |
| 117 | +# Run linter |
| 118 | +npm run lint |
| 119 | + |
| 120 | +# Fix linting issues |
| 121 | +npm run lint:fix |
| 122 | + |
| 123 | +# Type checking |
| 124 | +npm run type-check |
| 125 | +``` |
| 126 | + |
| 127 | +## Troubleshooting |
| 128 | + |
| 129 | +### CORS Errors |
| 130 | + |
| 131 | +If you see CORS errors in the browser console: |
| 132 | + |
| 133 | +1. Ensure the backend is running on `http://localhost:8080` |
| 134 | +2. Verify CORS is configured in `Program.cs` |
| 135 | +3. Check the frontend origin is included in the CORS policy |
| 136 | +4. Restart both frontend and backend servers |
| 137 | + |
| 138 | +### API Connection Issues |
| 139 | + |
| 140 | +1. Verify `VITE_API_BASE_URL` in `.env` matches your backend URL |
| 141 | +2. Check the backend server is running and accessible |
| 142 | +3. Ensure no firewall is blocking the connection |
| 143 | +4. Look for network errors in browser DevTools |
| 144 | + |
| 145 | +### Port Conflicts |
| 146 | + |
| 147 | +If port 55610 is busy, Vite will automatically find the next available port. Check the terminal output for the actual URL. |
| 148 | + |
| 149 | +### Build Issues |
| 150 | + |
| 151 | +1. Clear node_modules and reinstall: |
| 152 | + ```bash |
| 153 | + rm -rf node_modules package-lock.json |
| 154 | + npm install |
| 155 | + ``` |
| 156 | + |
| 157 | +2. Clear Vite cache: |
| 158 | + ```bash |
| 159 | + npm run dev -- --force |
| 160 | + ``` |
| 161 | + |
| 162 | +## Development Workflow |
| 163 | + |
| 164 | +1. **Start Backend**: Ensure backend is running first |
| 165 | +2. **Start Frontend**: Run `npm run dev` in the frontend directory |
| 166 | +3. **Open Browser**: Navigate to the URL shown in terminal |
| 167 | +4. **Live Development**: Changes auto-reload in browser |
| 168 | +5. **API Testing**: Use browser DevTools to monitor API calls |
| 169 | + |
| 170 | +## Performance |
| 171 | + |
| 172 | +The development server includes: |
| 173 | + |
| 174 | +- **Hot Module Replacement** for instant updates |
| 175 | +- **React Query DevTools** for API state inspection |
| 176 | +- **Source maps** for debugging |
| 177 | +- **TypeScript checking** in the background |
| 178 | + |
| 179 | +## Production Build |
| 180 | + |
| 181 | +To test a production build locally: |
| 182 | + |
| 183 | +```bash |
| 184 | +npm run build |
| 185 | +npm run preview |
| 186 | +``` |
| 187 | + |
| 188 | +The preview server runs on `http://localhost:4173` by default. |
| 189 | + |
| 190 | +## Architecture |
| 191 | + |
| 192 | +- **Build Tool**: Vite |
| 193 | +- **Framework**: React 19 with TypeScript |
| 194 | +- **UI Library**: Chakra UI v3 |
| 195 | +- **State Management**: React Query (TanStack Query) |
| 196 | +- **Routing**: React Router v7 |
| 197 | +- **Charts**: Custom SVG sparkline components |
| 198 | +- **HTTP Client**: Axios with interceptors |
| 199 | + |
| 200 | +## Browser Support |
| 201 | + |
| 202 | +- Chrome 90+ |
| 203 | +- Firefox 88+ |
| 204 | +- Safari 14+ |
| 205 | +- Edge 90+ |
| 206 | + |
| 207 | +Modern browsers with ES2020 support are required. |
0 commit comments