Download the PHP package julien-lin/react-bundle-symfony without Composer

ReactBundle v2.0 - Production-Ready React Integration for Symfony

Enterprise-grade Symfony bundle for seamless React + Vite integration

A lightweight, secure, and high-performance bundle that brings modern React development to Symfony, replacing Stimulus with production-ready components.

Languages: 🇫🇷 Français

🚀 Why ReactBundle v2.0?

✅ Production-Ready - 152 tests, 88% coverage, 100% security hardening
✅ Performance Monitored - Built-in metrics, logging, and observability
✅ Enterprise Security - XSS protection, command injection prevention, SSRF validation
✅ Zero Configuration - Works out of the box with Symfony Flex
✅ Modern Tooling - Vite-powered HMR for blazing-fast development
✅ Highly Testable - Comprehensive test suite with edge case coverage

💝 Support the project

If this bundle saves you time, consider becoming a sponsor to support ongoing development and maintenance of this open-source project.

⚡ Quick Start (5 minutes)

1. Install via Composer

Composer automatically installs npm dependencies via Symfony Flex.

2. Create React folder structure

3. Configure assets/React/index.js

4. Configure assets/js/app.jsx

5. Use in Twig templates

6. Build and run

✅ Done! Your React component is live.

📋 Table of Contents

1. Installation
2. Core Features
3. TypeScript Support
4. Advanced Usage
5. Production Deployment
6. Configuration
7. API Reference
8. Performance & Monitoring
9. Security
10. Troubleshooting
11. Contributing

📦 Installation

Via Composer

The Composer installation script will automatically install npm dependencies.

Configuration

1. The bundle registers automatically via Symfony Flex.

2. Configure the bundle in config/packages/react.yaml:

3. If npm dependencies were not automatically installed:

4. Create the file structure in your Symfony project (if it doesn't already exist):

5. Configure assets/React/index.js (entry point for your components):

6. Configure assets/js/app.jsx (must import from ../React):

Usage

Prerequisites: File Structure

Before using the bundle, make sure you have the following structure in your Symfony project:

In your Twig templates

Important: The component name in react_component() must match exactly the name used in the export of assets/React/index.js.

TypeScript Support

ReactBundleSymfony supports TypeScript out of the box. You can write your React components in TypeScript (.tsx files) for full type safety.

Quick Setup

1. Install TypeScript:

2. Create tsconfig.json:

3. Rename files to .tsx:

   • assets/js/app.jsx → assets/js/app.tsx
   • assets/React/Components/*.jsx → assets/React/Components/*.tsx
4. Use TypeScript in components:

See TYPESCRIPT.md for complete TypeScript documentation.

Docker Quick Start

Get started with Docker in 5 minutes:

See QUICK_START_DOCKER.md for complete Docker guide.

Build assets

Development with HMR

Production

Bundle structure

Recommended structure in your Symfony project

Create your React components in your Symfony project, not in the bundle:

Create a new React component

Quick workflow

Step 1: Create the component file

Create your component in assets/React/Components/YourComponent.jsx:

Step 2: Export the component in index.js

Add the export in assets/React/index.js:

Important: The name used in the export (YourComponent) must match exactly the name you will use in Twig.

Step 3: Use the component in a Twig template

In your Twig template:

Step 4: Rebuild assets

After creating or modifying a component:

Complete example

1. Create assets/React/Components/ProductCard.jsx

2. Export in assets/React/index.js

3. Use in Twig

Important notes

• ✅ Create your components in assets/React/Components/ (in your project, not in the bundle)
• ✅ Export them in assets/React/index.js with the exact name you will use in Twig
• ✅ Name is case-sensitive: ProductCard ≠ productcard ≠ Productcard
• ✅ Props are passed as JSON: use simple types (string, number, boolean, array, object)
• ✅ JavaScript functions can be passed as strings (e.g., '() => alert("test")')
• ✅ Rebuild after each modification: php bin/console react:build (or --dev for HMR)

Migration from Stimulus

ReactBundleSymfony is designed as a modern replacement for Stimulus in Symfony applications.

Quick migration:

1. Install ReactBundle: composer require julien-lin/react-bundle-symfony
2. Convert Stimulus controllers to React components
3. Replace data-controller="..." with {{ react_component(...) }}

See MIGRATION_STIMULUS.md for complete migration guide with examples.

Advanced configuration

Customize Vite server

In config/packages/react.yaml:

Environment variables

You can define VITE_SERVER_URL in your .env to customize the Vite server URL in development:

Or in config/packages/react.yaml:

Troubleshooting

Components are not displaying

• Check that {{ vite_entry_script_tags('app') }} is present in your template
• Check the browser console for JavaScript errors
• Make sure assets are compiled: php bin/console react:build
• Check that manifest.json exists in public/build/.vite/

"Component not found" error

• Check that the component is exported in assets/React/index.js of your Symfony project
• Check that the name in the export matches exactly the name used in Twig (case-sensitive)
• Check that the component file exists in assets/React/Components/
• Check that you have rebuilt the assets: php bin/console react:build
• Check the browser console to see the list of available components

HMR is not working

• Check that the Vite server is started: php bin/console react:build --dev
• Check that port 3000 (or the configured one) is not in use
• Check the configuration in vite.config.js
• Check that VITE_SERVER_URL is correctly configured

npm/Node.js errors

• Check that Node.js >= 18.0.0 is installed: node --version
• Check that npm is installed: npm --version
• If you use nvm, make sure the environment is correctly loaded

Path errors (Windows)

• The bundle now supports Windows with DIRECTORY_SEPARATOR
• If you encounter problems, check folder permissions
• Make sure paths in vite.config.js are correct

Adding npm Packages

To add npm packages (like react-icons, axios, etc.) to your project:

1. Install the package in your Symfony project root (not in the bundle):

2. Import and use it in your components:

3. Rebuild assets:

📖 Full guide: See ADDING_NPM_PACKAGES.md for detailed instructions and examples.

Support

• Complete documentation: see QUICKSTART.md
• Installation guide: see INSTALLATION.md
• Adding npm packages: see ADDING_NPM_PACKAGES.md
• Report a bug: GitHub Issues
• Become a sponsor: GitHub Sponsors

License

MIT