Skip to main content

Vite Migration Notes

Overview​

The application has been migrated from Webpacker to Vite for modern JavaScript builds.

Key Changes​

Build Tool​

  • Before: Webpacker 4.2.2 with webpack-dev-server
  • After: Vite 5.4 with vite-plugin-ruby

Directory Structure​

  • Before: app/javascript/
  • After: app/frontend/

React Component Mounting​

  • Before: Used react-rails gem and react_component helper with react_ujs
  • After: Custom ReactComponentHelper that uses data-react-component attributes

Layout Tags​

  • Before: javascript_pack_tag and stylesheet_pack_tag
  • After: vite_client_tag and vite_javascript_tag

Development​

Running the Development Server​

# Start all services (Rails, Vite, Sidekiq)
foreman start -f Procfile.dev

# Or start Vite separately
bin/vite dev

Building Assets​

# Development build
RAILS_ENV=development rails assets:precompile

# Production build
RAILS_ENV=production rails assets:precompile

Linting​

# Lint JavaScript/TypeScript
yarn lint

# Lint Ruby
bundle exec rubocop

React Components​

Mounting Components in Views​

Use the react_component helper (now provided by ReactComponentHelper):

<%= react_component 'ComponentName', { prop1: 'value', prop2: 123 } %>

Component Registration​

All components used in views must be imported and registered in app/frontend/entrypoints/application.tsx:

import ComponentName from '../components/ComponentName'

const components = {
  ComponentName,
  // ... other components
}

Configuration Files​

  • vite.config.mts - Vite configuration
  • config/vite.json - Vite Ruby configuration
  • tsconfig.json - TypeScript configuration
  • .eslintrc.js - ESLint configuration

CI/CD​

  • GitHub Actions workflows automatically build assets during CI
  • Node.js 20.x is required
  • Vite assets are built during rails assets:precompile

Dependencies​

Core Dependencies​

  • vite (^5.4.0)
  • vite-plugin-ruby (^5.1.1)
  • @vitejs/plugin-react (^4.7.0)
  • react (^16.13.0)
  • react-dom (^16.13.0)

Development Dependencies​

  • typescript (^4.9.5)
  • @typescript-eslint/parser (^8.47.0)

Troubleshooting​

Vite Dev Server Not Starting​

  • Check that port 3036 is available
  • Ensure Node.js 20.x is installed

Assets Not Loading​

  • Make sure bin/vite dev is running in development
  • Check that assets were precompiled for production

React Component Not Mounting​

  • Verify component is imported in app/frontend/entrypoints/application.tsx
  • Check browser console for JavaScript errors
  • Ensure props are JSON-serializable

Migration Completed​

Date: November 23, 2025 Original Setup: Webpacker 4.2.2 + react-rails 2.6.2 New Setup: Vite 5.4 + vite_rails 3.0.19