InertiaTest - Mojolicious + InertiaJS + Svelte Demo

This project demonstrates how to integrate InertiaJS with Mojolicious, using Svelte as the frontend framework. It implements a complete InertiaJS adapter for Mojolicious and provides a working example application.

🎯 Features

• Complete InertiaJS Protocol Implementation - Full support for the InertiaJS protocol
• Svelte Frontend - Modern, reactive UI components
• Helper-based API - Clean, Mojolicious-style helpers
• Asset Versioning - Automatic cache busting with Vite integration
• Shared Data - Global and per-request shared data
• Form Validation - Seamless validation error handling
• Flash Messages - Success and error message support
• Partial Reloads - Optimize performance with selective data loading
• Development Tools - Hot reload and development server integration

📋 Requirements

• Perl 5.20+ with Carton
• Node.js 16+ with npm
• Modern browser with JavaScript enabled

🚀 Quick Start

1. Clone and Setup

   git clone <repository-url>
   cd inertia-mojo
   ./script/setup.sh
   

2. Start Development Server

   ./script/dev.sh
   

3. Visit the Application

   • Main app: http://localhost:3000
   • Vite HMR: http://localhost:5173

📁 Project Structure

inertia-mojo/
├── lib/
│   ├── InertiaTest.pm                    # Main application class
│   ├── InertiaTest/Controller/           # Controllers
│   │   ├── Example.pm                    # Basic pages and forms
│   │   └── Users.pm                      # CRUD example
│   └── Mojolicious/Plugin/
│       └── Inertia.pm                    # InertiaJS plugin
├── client/                               # Frontend (Svelte)
│   ├── src/
│   │   ├── app.js                        # Inertia app entry point
│   │   ├── app.css                       # Global styles
│   │   ├── Pages/                        # Svelte page components
│   │   └── Shared/                       # Shared components
│   ├── package.json                      # Node dependencies
│   └── vite.config.js                    # Build configuration
├── templates/
│   └── inertia/app.html.ep               # Root HTML template
├── public/dist/                          # Built assets
├── script/                               # Development scripts
├── t/                                    # Tests
└── cpanfile                             # Perl dependencies

🔧 Plugin API

Basic Usage

# In your Mojolicious app
$self->plugin('Inertia' => {
    version => sub { '1.0.0' },
    shared => {
        auth => sub ($c) { $c->session('user') }
    }
});

# In your controller
$c->inertia('ComponentName', { prop1 => 'value1' });

Available Helpers

# Main rendering helper
$c->inertia('Users/Index', { users => \@users });

# Share data across requests
$c->inertia_share(flash => 'Success!');

# Handle redirects
$c->inertia_location('/dashboard');

# Optional props for expensive data
$c->inertia('Dashboard', {
    stats => $c->inertia_optional(sub { expensive_query() })
});

# Version management
$c->inertia_version('abc123');

Configuration Options

$app->plugin('Inertia' => {
    # Asset version (for cache busting)
    version => sub ($c) { 
        return $c->_read_manifest_version() || time();
    },
    
    # Shared data (available to all responses)
    shared => {
        auth => sub ($c) { 
            return { user => $c->session('user') };
        },
        csrf_token => sub ($c) { $c->csrf_token },
    },
    
    # Root view template
    root_view => 'inertia/app',
    
    # Manifest file location
    manifest_path => 'public/dist/.vite/manifest.json',
});

🧪 Testing

Run the test suite:

carton exec -- prove -l t/

Run with verbose output:

carton exec -- prove -lv t/

🌐 Demo Pages

The application includes several demonstration pages:

• Home (/) - Welcome page with basic information
• About (/about) - Technology overview
• Users (/users) - Complete CRUD example
  • List all users
  • View individual user
  • Create new user
  • Edit existing user
  • Delete user
• Forms (/forms) - Form validation demo

📖 Example Components

Svelte Page Component

<script>
  import Layout from '../Shared/Layout.svelte'
  import { useForm } from '@inertiajs/svelte'
  
  export let users = []
  
  let form = useForm({
    name: '',
    email: ''
  })
  
  function submit() {
    $form.post('/users')
  }
</script>

<Layout>
  <h1>Users</h1>
  
  <!-- Your component content -->
  
</Layout>

Controller Action

sub index ($self) {
    my @users = $self->app->db->select('users')->hashes;
    
    $self->inertia('Users/Index', {
        users => \@users,
        can => {
            create => $self->can_create_users,
            edit => $self->can_edit_users,
        }
    });
}

🛠️ Development

Installing Dependencies

# Perl dependencies
carton install

# Node.js dependencies
cd client && npm install

Building Assets

cd client
npm run build    # Production build
npm run dev      # Development server

Running Tests

carton exec -- prove -l t/

🏗️ Production Deployment

1. Install dependencies

   carton install --deployment
   cd client && npm ci
   

2. Build assets

   cd client && npm run build
   

3. Start application

   carton exec -- ./app.pl daemon -l http://*:8080
   

🔍 Troubleshooting

Common Issues

1. "Can't locate Mojo/Base.pm"

   • Run: carton install

2. "Vite dev server not detected"

   • Run: cd client && npm run dev

3. Assets not loading

   • Check that public/dist/ contains built assets
   • Run: cd client && npm run build

Debug Mode

Set environment variable for detailed logging:

MOJO_LOG_LEVEL=debug ./script/dev.sh

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

This project is provided as a demonstration and educational resource.

🙏 Acknowledgments

• Mojolicious - The web framework that makes this possible
• InertiaJS - For the brilliant SPA-without-API concept
• Svelte - For the excellent frontend framework
• Vite - For fast development builds