LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Vite Migration Guide
Initial Migration Date: 2025-10-19 From: Create React App (react-scripts 5.0.1) To: Vite 6.0.5 + @vitejs/plugin-react 4.3.4
Vite 7 Upgrade Date: 2026-02-04 Current Version: Vite 7.3.1 + @vitejs/plugin-react 4.4.0 + Vitest 3.2.4
Overview
The Unstract frontend has been migrated from Create React App to Vite for improved development experience and build performance. The project uses Bun as the package manager.
What Changed
1. Build Tool & Configuration
Removed
react-scriptsdependencysrc/setupProxy.js(proxy configuration)- CRA-specific eslintConfig from package.json
- Webpack and Babel dependencies
Added
vite(v7.3.1)@vitejs/plugin-react(v4.4.0)vitest(v3.2.4) for testingvite.config.jsfor build configuration
2. File Structure Changes
Before (CRA):
frontend/
├── public/
│ └── index.html
├── src/
│ ├── index.js
│ └── setupProxy.js
└── package.json
After (Vite):
frontend/
├── index.html ← Moved to root
├── public/ ← Static assets only
├── src/
│ └── index.js
├── vite.config.js ← New config file
└── package.json
3. Environment Variables
IMPORTANT: All environment variables must now use the VITE_ prefix.
Migration Mapping
REACT_APP_BACKEND_URL → VITE_BACKEND_URL
REACT_APP_ENABLE_POSTHOG → VITE_ENABLE_POSTHOG
REACT_APP_FAVICON_PATH → VITE_FAVICON_PATH
REACT_APP_CUSTOM_LOGO_URL → VITE_CUSTOM_LOGO_URL
Code Changes Required
// Before (CRA):
const backendUrl = process.env.REACT_APP_BACKEND_URL;
const isDev = process.env.NODE_ENV === 'development';
// After (Vite):
const backendUrl = import.meta.env.VITE_BACKEND_URL;
const isDev = import.meta.env.MODE === 'development';
4. Package.json Scripts
{
"scripts": {
"dev": "vite", // New: preferred dev command
"start": "vite", // Updated: now runs Vite
"build": "vite build", // Updated: Vite build
"preview": "vite preview", // New: preview production build
"test": "vitest" // Updated: Vitest instead of Jest
}
}
5. HTML Entry Point
Location: Moved from public/index.html to index.html (root)
Changes:
- Removed
%PUBLIC_URL%placeholders - Changed
href="%PUBLIC_URL%/manifest.json"tohref="/manifest.json" - Added
<script type="module" src="/src/index.js"></script>
6. Proxy Configuration
Before (setupProxy.js):
module.exports = (app) => {
app.use('/api/v1', createProxyMiddleware({
target: process.env.REACT_APP_BACKEND_URL,
changeOrigin: true,
}));
};
After (vite.config.js):
export default defineConfig({
server: {
proxy: {
'/api': {
target: env.VITE_BACKEND_URL,
changeOrigin: true,
secure: false,
},
},
},
});
Docker Build Configuration
Dockerfile Changes for Vite
The docker/dockerfiles/frontend.Dockerfile has been updated for Vite:
1. Environment Variables:
# Changed from REACT_APP_ to VITE_ prefix
ENV VITE_BACKEND_URL=""
2. Runtime Config Injection:
Since Vite processes all <script> tags during build, the runtime config script is injected AFTER the build:
# Inject runtime config script into index.html after build
RUN sed -i 's|</head>| <script src="/config/runtime-config.js"></script>\n </head>|' /usr/share/nginx/html/index.html
3. Runtime Config Script Updated:
The generate-runtime-config.sh script now supports both VITE_ and REACT_APP_ prefixes for backward compatibility:
window.RUNTIME_CONFIG = {
faviconPath: "${VITE_FAVICON_PATH:-${REACT_APP_FAVICON_PATH}}",
logoUrl: "${VITE_CUSTOM_LOGO_URL:-${REACT_APP_CUSTOM_LOGO_URL}}"
};
Vite Configuration for Docker
Vite is configured to use polling for file watching, which is critical for Docker volume mounts:
// vite.config.js
export default defineConfig({
server: {
watch: {
usePolling: true,
interval: 100,
},
},
});
HMR Configuration
Hot Module Replacement is configured for containerized environments:
// vite.config.js
server: {
host: '0.0.0.0',
port: 3000,
hmr: {
port: 3000,
clientPort: env.WDS_SOCKET_PORT ? Number(env.WDS_SOCKET_PORT) : 3000,
},
}
Performance Optimizations
Manual Chunk Splitting
Vite configuration includes optimized chunk splitting for better caching:
build: {
rollupOptions: {
output: {
manualChunks: {
'react-vendor': ['react', 'react-dom', 'react-router-dom'],
'antd-vendor': ['antd', '@ant-design/icons'],
'pdf-vendor': [
'@react-pdf-viewer/core',
'@react-pdf-viewer/default-layout',
'@react-pdf-viewer/highlight',
'@react-pdf-viewer/page-navigation',
'pdfjs-dist',
],
},
},
},
}
Dependency Pre-bundling
Common dependencies are pre-bundled for faster cold starts:
optimizeDeps: {
include: [
'react',
'react-dom',
'react-router-dom',
'antd',
'@ant-design/icons',
],
}
Migration Checklist for Developers
- Update local
.envfiles to useVITE_prefix - Update any custom environment variables in deployment configs
- Verify all
process.env.REACT_APP_*references are updated toimport.meta.env.VITE_* - Test development server:
bun startorbun run dev - Test production build:
bun run build - Verify HMR works correctly in Docker environment
- Check proxy configuration for backend API calls
Common Issues & Solutions
Issue: Environment variables not loading
Solution: Ensure variables use VITE_ prefix and are accessed via import.meta.env
// ❌ Wrong
console.log(process.env.REACT_APP_BACKEND_URL);
// ✅ Correct
console.log(import.meta.env.VITE_BACKEND_URL);
Issue: HMR not working in Docker
Solution: Verify polling is enabled in vite.config.js and CHOKIDAR_USEPOLLING=true in .env
Issue: Build output directory incorrect
Solution: Vite outputs to dist/ by default, but we've configured it to use build/ to maintain compatibility:
// vite.config.js
build: {
outDir: 'build',
}
Issue: JSX syntax errors in .js files during build
Solution: Configure esbuild to treat .js files as JSX:
// vite.config.js
esbuild: {
loader: 'jsx',
include: /src\/.*\.jsx?$/,
}
plugins: [
react({
include: '**/*.{jsx,js}',
}),
]
Issue: Runtime config script causing build failure
Problem: Vite tries to process <script src="/config/runtime-config.js"> during build, but the file doesn't exist at build time.
Solution: Remove the script tag from source index.html and inject it AFTER build in the Dockerfile:
# In docker/dockerfiles/frontend.Dockerfile
RUN sed -i 's|</head>| <script src="/config/runtime-config.js"></script>\n </head>|' /usr/share/nginx/html/index.html
Issue: Import errors for static assets
Solution: Use / prefix for public assets instead of %PUBLIC_URL%:
// ❌ Wrong (CRA)
<img src={`${process.env.PUBLIC_URL}/logo.png`} />
// ✅ Correct (Vite)
<img src="/logo.png" />
Development Commands
# Install dependencies
bun install
# Start development server
bun start
# or
bun run dev
# Build for production
bun run build
# Preview production build
bun run preview
# Run tests
bun test
# Lint code
bun run lint
# Format code
bun run format:fix
TypeScript Support
If migrating TypeScript code, add type definitions:
// src/vite-env.d.ts
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_BACKEND_URL: string
readonly VITE_ENABLE_POSTHOG: string
readonly VITE_FAVICON_PATH?: string
readonly VITE_CUSTOM_LOGO_URL?: string
}
interface ImportMeta {
readonly env: ImportMetaEnv
}
Vite 7 Upgrade (2026-02-04)
What Changed in Vite 7
- Node.js requirement: Minimum Node.js 20.19+ or 22.12+ (Node 18 dropped)
- Vitest: Upgraded from 2.x to 3.2+ (required for Vite 7 compatibility)
- Browser target: Default changed from
'modules'to'baseline-widely-available' - Modernized config:
__dirnamereplaced withimport.meta.dirname
Deprecated Features Removed in Vite 7
| Feature | Status |
|---|---|
splitVendorChunkPlugin |
Not used (we use manual manualChunks) |
| Sass legacy API | Not used (no SCSS files in project) |
Version Updates
| Package | Before | After |
|---|---|---|
| vite | ^6.0.5 | ^7.0.0 (7.3.1) |
| vitest | ^2.1.8 | ^3.2.0 (3.2.4) |
| @vitejs/plugin-react | ^4.3.4 | ^4.4.0 |
| Node.js (engines) | >=18.0.0 | >=20.19.0 |
Benefits of Vite Migration
- Faster Development Server: Near-instant server start
- Faster HMR: Updates reflect immediately without full reload
- Optimized Builds: Better tree-shaking and code splitting
- Smaller Bundle Size: Improved chunking strategies
- Modern Tooling: Built on native ES modules
- Better Docker Support: Reliable file watching with polling
Resources
- Vite Official Documentation
- Vite Migration Guide
- Environment Variables in Vite
- Vite Configuration Reference
Rollback Instructions
If you need to rollback to Create React App:
- Restore
package.jsonfrom git history - Delete
vite.config.jsandindex.html(root) - Restore
public/index.htmlandsrc/setupProxy.js - Revert environment variable changes (
VITE_*→REACT_APP_*) - Revert code changes (
import.meta.env→process.env) - Run
bun installto restore react-scripts
Support
For issues or questions about the Vite migration:
- Check this migration guide first
- Review
vite.config.jsfor current configuration - Consult Vite documentation for advanced configurations
- Check project's main CLAUDE.md for overall development guidelines