Flaxon Inertia

Inertia.js integration plugin for Flaxon framework.

Table of Contents

• What is Inertia.js?

• Features

• Installation

• Quick Start

  • 1. Install and Configure Plugin
  • 2. Create Root Template
  • 3. Setup Frontend
  • 4. Create Pages

• Configuration

  • Environment Variables
  • With Flaxon Config

• Advanced Usage

  • Shared Data
  • Lazy Props
  • Flash Messages
  • Server-Side Rendering (SSR)
  • Custom User Mapper

• Routes

• Testing

• Frontend Examples

  • React
  • Vue 3
  • Svelte

• Security Best Practices

• Roadmap

• Contributing

• License

• Support

• Related Plugins

What is Inertia.js?

Inertia.js is a framework that lets you build full-stack applications with a Python backend and modern JavaScript frontend (React, Vue, Svelte) without building a separate REST API. It serves as the "glue" that binds your backend and frontend together.

Features

• 🚀 Full-stack development — Build modern apps with Python backend + JS frontend
• 📦 No API required — Backend and frontend communicate seamlessly
• ⚡ Fast development — No need to maintain separate API endpoints
• 🔄 Partial reloads — Only update what changes
• 📊 Shared data — Automatically share data across pages
• 🎯 Lazy loading — Load data on demand for better performance
• 💬 Flash messages — Easy session-based notifications
• 🖥️ SSR Support — Optional server-side rendering
• 🎨 Framework agnostic — Works with React, Vue, Svelte, and more

Installation

pip install flaxon-inertia

For server-side rendering support:

pip install flaxon-inertia[ssr]

Quick Start

1. Install and Configure Plugin

from flaxon import Flaxon
from flaxon_inertia import InertiaPlugin

app = Flaxon("my-app")

app.plugins.load_plugin(InertiaPlugin(
    root_template="templates/app.html",
    asset_version="v1.0.0",
))

@app.get("/")
async def home():
    return inertia.render("Home", {
        "title": "Welcome to Flaxon Inertia",
        "features": ["Fast", "Modern", "Python"],
    })

2. Create Root Template

<!-- templates/app.html -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Flaxon Inertia</title>
    <link rel="stylesheet" href="/css/app.css">
</head>
<body>
    <div id="app" data-page="{{ page | tojson }}"></div>
    <script src="/js/app.js"></script>
</body>
</html>

3. Setup Frontend

// app.js
import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
    resolve: name => import(`./pages/${name}.vue`),
    setup({ el, App, props, plugin }) {
        createApp({ render: () => h(App, props) })
            .use(plugin)
            .mount(el)
    },
})

4. Create Pages

<!-- pages/Home.vue -->
<script setup>
defineProps({
    title: String,
    features: Array,
})
</script>

<template>
    <div>
        <h1>{{ title }}</h1>
        <ul>
            <li v-for="feature in features" :key="feature">
                {{ feature }}
            </li>
        </ul>
    </div>
</template>

Configuration

Environment Variables

# Asset version for cache busting
INERTIA_ASSET_VERSION=v1.0.0

# SSR configuration
INERTIA_SSR_ENABLED=true
INERTIA_SSR_HOST=localhost
INERTIA_SSR_PORT=13714

# Root template location
INERTIA_ROOT_TEMPLATE=templates/app.html

With Flaxon Config

app = Flaxon("my-app", config={
    "INERTIA_ROOT_TEMPLATE": "templates/app.html",
    "INERTIA_ASSET_VERSION": "v1.0.0",
    "INERTIA_SSR_ENABLED": True,
    "INERTIA_SSR_HOST": "localhost",
    "INERTIA_SSR_PORT": 13714,
})

plugin = InertiaPlugin.from_config(app.config)
app.plugins.load_plugin(plugin)

Advanced Usage

Shared Data

Share data across all pages:

from flaxon_inertia import share

@share("user")
def get_user(request):
    """Share user data across all pages."""
    return request.session.get("user")

@share("notifications")
async def get_notifications(request):
    """Share notifications across all pages."""
    return await notification_service.get_for_user(request.user)

# Or directly in plugin config
app.plugins.load_plugin(InertiaPlugin(
    root_template="templates/app.html",
    shared_data={
        "app_name": "My App",
        "user": get_user,
        "notifications": get_notifications,
    }
))

Lazy Props

Load data only when needed:

from flaxon_inertia import lazy

@app.get("/dashboard")
async def dashboard(request):
    return inertia.render("Dashboard", {
        # Loaded immediately
        "user": request.user,
        
        # Loaded on demand (partial reload)
        "stats": lazy(lambda: get_dashboard_stats()),
        "recent_activity": lazy(lambda: get_recent_activity()),
        "notifications": lazy(lambda: get_notifications()),
    })

Flash Messages

Show temporary notifications:

@app.post("/users")
async def create_user(request):
    data = await request.json()
    user = await create_user(data)
    
    return inertia.redirect(
        "/users",
        flash={"success": f"User {user.name} created!"}
    )

@app.post("/login")
async def login(request):
    if not await authenticate(request):
        return inertia.redirect(
            "/login",
            flash={"error": "Invalid credentials"}
        )
    
    return inertia.redirect(
        "/dashboard",
        flash={"success": "Welcome back!"}
    )

Server-Side Rendering (SSR)

Enable SSR for better SEO and performance:

app.plugins.load_plugin(InertiaPlugin(
    root_template="templates/app.html",
    ssr_enabled=True,
    ssr_host="localhost",
    ssr_port=13714,
))

Start the SSR server:

node ssr.js

Custom User Mapper

Map Inertia page data to your app's user model:

def map_user(google_user):
    """Map Google user to app user for Inertia."""
    return {
        "id": google_user.id,
        "name": google_user.name,
        "email": google_user.email,
        "avatar": google_user.picture,
    }

# Use with OAuth plugin
@app.get("/auth/google/callback")
async def google_callback(request):
    # ... OAuth flow ...
    user = map_user(google_user)
    return inertia.redirect(
        "/dashboard",
        flash={"success": f"Welcome {user['name']}!"}
    )

Routes

Route	Method	Description
Any	GET/POST	Inertia handles routing via frontend

All routes are handled by Inertia's client-side routing. The backend only needs to render the initial page and handle form submissions.

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=flaxon_inertia

# Run specific test
pytest tests/test_response.py -v

Frontend Examples

React

import { createRoot } from 'react-dom/client'
import { createInertiaApp } from '@inertiajs/react'

createInertiaApp({
    resolve: name => import(`./pages/${name}.jsx`),
    setup({ el, App, props }) {
        createRoot(el).render(<App {...props} />)
    },
})

Vue 3

import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
    resolve: name => import(`./pages/${name}.vue`),
    setup({ el, App, props, plugin }) {
        createApp({ render: () => h(App, props) })
            .use(plugin)
            .mount(el)
    },
})

Svelte

import { mount } from 'svelte'
import { createInertiaApp } from '@inertiajs/svelte'

createInertiaApp({
    resolve: name => import(`./pages/${name}.svelte`),
    setup({ el, App, props }) {
        mount(App, { target: el, props })
    },
})

Security Best Practices

✅ Use CSRF protection for form submissions

✅ Validate all input data

✅ Use secure cookies for sessions

✅ Sanitize data before passing to frontend

✅ Keep asset versions unique per deployment

Roadmap

Version	Features
0.1.0	Basic Inertia integration, response handling, shared data
0.2.0	Partial reloads, lazy props, flash messages
0.3.0	Server-side rendering (SSR) support
0.4.0	Vite/Webpack integration helpers
0.5.0	TypeScript type definitions
0.6.0	CSRF protection built-in

Contributing

Fork the repository

Create a feature branch

Add tests for new features

Ensure all tests pass

Submit a pull request

License

MIT License - See LICENSE file for details.

Support

📚 Documentation

🐛 Issue Tracker

💬 Discussions

🌐 Inertia.js Website

Related Plugins

flaxon-sentry - Sentry error tracking

flaxon-oauth-google - Google OAuth authentication