A full-stack implementation of Inertia.js for Node.js using Express and React. Build modern single-page applications with classic server-side routing and controllers, without the complexity of building an API.
Note: This project is based on henriquealbert/inertiajs-node-express with significant enhancements including React support, hot module replacement, testing suite, and improved developer experience.
- 🚀 Full Inertia.js Support - Complete implementation of Inertia.js protocol for Node.js/Express
- ⚛️ React Integration - Built-in React support with component-based architecture
- 🔥 Hot Module Replacement (HMR) - Instant updates during development with Vite
- 💬 Flash Messages - Built-in flash message system for user notifications
- 🔄 Live Updates - Automatic page reloads when server props change
- 📦 TypeScript - Full TypeScript support for type safety
- 🧪 Testing Suite - Comprehensive test coverage with Jest and React Testing Library
- ⚙️ Environment Configuration - Easy configuration via
.envfiles - 🎨 Modern Tooling - Vite for fast builds and development experience
Before you begin, ensure you have the following installed:
- Node.js (v18 or higher)
- npm or bun (package manager)
- Git (for cloning the repository)
-
Clone the repository
git clone <your-repo-url> cd inertiajs-node-express
-
Install dependencies
npm install # or bun install -
Configure environment variables
cp .env.example .env
Edit
.envand update the configuration:NODE_ENV=development PORT=3000 SESSION_SECRET=your-secret-key-change-this-in-production VITE_PORT=5173 VITE_HOST=localhost
-
Start the development server
npm run dev
-
Open your browser Navigate to
http://localhost:3000/hometo see the application in action.
inertiajs-node-express/
├── src/
│ ├── client/ # React frontend
│ │ ├── app.tsx # Inertia.js entry point
│ │ ├── Pages/ # React page components
│ │ │ └── Home.tsx # Example component
│ │ └── tsconfig.json # TypeScript config
│ ├── lib/ # Inertia.js library
│ │ ├── flash/ # Flash message system
│ │ ├── inertia/ # Core Inertia middleware
│ │ └── types/ # TypeScript definitions
│ └── server.ts # Express server entry point
├── tests/ # Test suite
│ ├── components/ # React component tests
│ ├── integration/ # Integration tests
│ ├── middleware/ # Middleware tests
│ └── utils/ # Test utilities
├── public/ # Static assets
│ └── build/ # Production builds
├── .env # Environment variables (gitignored)
├── .env.example # Environment template
├── vite.config.ts # Vite configuration
├── jest.config.js # Jest configuration
└── package.json # Project dependencies
Define routes in src/server.ts:
router.get("/home", async (req) => {
// Set flash messages
req.flash.setFlashMessage("success", "User created successfully");
// Render Inertia component
req.Inertia.render({
component: "home",
props: { name: "John Doe" },
url: "/home",
version: appVersion,
});
});Create components in src/client/Pages/:
// src/client/Pages/Home.tsx
import React from 'react';
import { Head } from '@inertiajs/react';
interface Props {
name: string;
success?: string[];
}
export default function Home({ name, success }: Props) {
return (
<>
<Head title="Home" />
<div>
<h1>Welcome, {name}!</h1>
{success && success.length > 0 && (
<div className="alert alert-success">
{success[0]}
</div>
)}
</div>
</>
);
}Flash messages are automatically included in component props:
// Set flash message
req.flash.setFlashMessage("success", "Operation successful");
req.flash.setFlashMessage("error", "Something went wrong");
// Access in component
const { success, error } = usePage().props;Use Inertia's redirect method:
router.post("/users", async (req) => {
// Create user logic...
req.Inertia.redirect("/home");
});# Run all tests
npm test
# or
bun test
# Run tests in watch mode
npm run test:watch
# Generate coverage report
npm run test:coverage- Unit Tests - Test individual components and functions
- Integration Tests - Test full request/response cycles
- Component Tests - Test React components with React Testing Library
See tests/README.md for detailed testing documentation.
# Development
npm run dev # Start both Vite and Express servers
npm run dev:server # Start only Express server
npm run dev:client # Start only Vite dev server
# Building
npm run build # Build both client and server
npm run build:client # Build only React client
# Production
npm start # Start production server
# Testing
npm test # Run tests
npm run test:watch # Run tests in watch mode
npm run test:coverage # Generate coverage report-
Start development servers
npm run dev
This starts both the Express server (port 3000) and Vite dev server (port 5173).
-
Make changes
- React components: Edit files in
src/client/Pages/- changes appear instantly - Server routes: Edit
src/server.ts- server restarts automatically
- React components: Edit files in
-
Hot Module Replacement
- React changes: Instant updates without page reload
- Server changes: Automatic page reload with new props
Configure your application using the .env file:
| Variable | Description | Default |
|---|---|---|
NODE_ENV |
Environment mode | development |
PORT |
Express server port | 3000 |
HOST |
Server hostname | localhost |
SESSION_SECRET |
Session encryption secret | secret |
VITE_PORT |
Vite dev server port | 5173 |
VITE_HOST |
Vite dev server host | localhost |
SESSION_SECRET in production. Generate a secure secret:
openssl rand -base64 32- Setup Guide - Detailed setup and configuration instructions
- Test Documentation - Testing guide and examples
- Inertia.js Documentation - Official Inertia.js docs
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch
git checkout -b feature/amazing-feature
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
npm test - Commit your changes
git commit -m "Add amazing feature" - Push to the branch
git push origin feature/amazing-feature
- Open a Pull Request
- Use TypeScript for all new code
- Follow existing code style and patterns
- Write tests for new features
- Update documentation as needed
- React.js support
- Hot Module Replacement (HMR)
- Comprehensive test suite
- Environment variable configuration
- Flash message system
- Template engine support (EJS)
- Vue.js support
- Svelte support
- Additional examples and documentation
This project is licensed under the MIT License - see the LICENSE file for details.
- Original Implementation - Based on henriquealbert/inertiajs-node-express
- Inertia.js - Created by Jonathan Reinink and the Inertia.js community
- Express.js - Fast, unopinionated web framework for Node.js
- React - A JavaScript library for building user interfaces
- Vite - Next generation frontend tooling
- Issues - GitHub Issues
- Discussions - GitHub Discussions
If you find this project helpful, please consider giving it a star on GitHub!