Masonite Inertia

Introduction

Inertia is a new approach to building classic server-driven web apps. From their own web page:

Inertia allows you to create fully client-side rendered, single-page apps, without much of the complexity that comes with modern SPAs. It does this by leveraging existing server-side frameworks.

Inertia requires an adapter for each backend framework.

This repo contains the Masonite server-side adapter for Inertia.js. You can find the legacy Inertia PingCRM demo with Masonite here demo (WIP).

This package is compatible with both Masonite 2.X and Masonite 3.X.

A new documentation 📚 is coming in January 2021, stay tuned !

Features

Almost all features of the official server-side adapters are present 😃

Shared data
Partial reloads
Lazy loaded props
Set root view in a provider
Set root view per view
Enable sharing Masonite routes (prefer using masonite-js-routes)
Enable sharing Masonite flash messages

Official Masonite Documentation

New to Masonite ? Please first read the Official Documentation. Masonite strives to have extremely comprehensive documentation 😃. It would be wise to go through the tutorials there. If you find any discrepencies or anything that doesn't make sense, be sure to comment directly on the documentation to start a discussion!

Also be sure to join the Slack channel!

Installation

Requirements

To get started you will need the following:

Masonite 3.X.X (use masonite-inertia>=3.0) or Masonite 2.3.X (use masonite-inertia>=2.X<3.0)
Laravel Mix installed (new Masonite 2.3 projects come with this installed already)
a Node.js environment (npm or yarn)

pip install masonite-inertia

Install NPM dependencies

First we'll need to install some NPM packages (we are using Vue here as frontend framework and inertia-vue as Inertia.js client-side adapter): You can find more info on this on Inertia.js documentation.

$ npm install vue @inertiajs/inertia @inertiajs/inertia-vue

Configuration

Add InertiaProvider to your project in config/providers.py:

# config/providers.py
# ...
from masonite.inertia import InertiaProvider

# ...
PROVIDERS = [
    # ...

    # Third Party Providers
    InertiaProvider,
]

Inertia adapter comes with a middleware that will control some of the flow of data. Add InertiaMiddleware to your project in config/middleware.py:

# config/middleware.py
# ...
from masonite.inertia import InertiaMiddleware

# ...
HTTP_MIDDLEWARE = [
    LoadUserMiddleware,
    CsrfMiddleware,
    #...
    InertiaMiddleware,
]

Finally publish the package configuration (to get config/inertia.py) to your project:

python craft install:inertia

Congratulations! You have now setup Inertia in your project! For more information on how to use Inertia.js got to its documentation.

Install demo (optional)

To get started quickly, you can scaffold a demo to your project, by running:

python craft inertia:demo

This will automatically :

publish a demo controller
publish two routes
create a demo view
update npm dependencies and webpack.mix.js
create Vue 3 demo app in resources/js

Then run npm install && npm run watch and start the server python craft serve.

Finally browse to http://localhost:8000/inertia 🚀!

Usage [Doc In Progress]

How to use Inertia.js with Masonite adapter

We will create two routes and a controller which will load the two components scaffolded with previous command and see Inertia.js behaviour. In order to create Inertia response in our Controller, we are going to use newly available response InertiaResponse. And that's it !

If you scaffolded the inertia demo you will already have the files, else:

$ craft controller InertiaController

This will create a controller InertiaController but you can name it whatever you like. It would be good to keep the standard of whatever setup you have now for your home page. Then create two routes to that controller if you don't have them already:

ROUTES = [
    Get('/', 'InertiaController@index'),
    Get('/helloworld', 'InertiaController@helloworld')
]

And finally create the controller methods. We just need to use the new InertiaResponse to render our controller.

# app/controllers/InertiaController.py
from masonite.inertia import InertiaResponse

## ..
def inertia(self, view: InertiaResponse):
    return view.render('Index')

def helloworld(self, view: InertiaResponse):
  return view.render('HelloWorld')

## ..

This controller will render the view based on template templates/app.html and will load the Vue components into it depending on the route. Note that instead of specifying a Jinja template like we normally do we can just specify a page here. So since we have ../pages/Index.vue we specify to render Index here.