00:05
Using InertiaJS with AdonisJS is rather simplistic because AdonisJS has a whole configuration step that allows it to configure InertiaJS into any AdonisJS project.
00:14
So if you have a pre-existing project, you can easily add InertiaJS to it at any point in time. Just go ahead and CD into whatever that project is,
00:21
and then run node ace add at AdonisJS/inertia, and that command will both install the InertiaJS package into
00:29
your project as well as configure it all in that one command. So if I open the documentation up here, all the steps provided here within the C steps performed by the configuration command.
00:39
If you're looking for this inside of the AdonisJS documentation, scroll down to the views and templates, go into Inertia, and this is underneath the installation section. So I've just expanded this little panel
00:48
out here and it walks through all the steps. So it's going to configure the Inertia provider inside of our providers array, add in the middleware, create a configuration file for us, the Inertia layout edge view,
00:57
the CSS as well as the JavaScript files needed to instantiate your application on the client side, a welcome page, error pages. It's also going to update your V configuration to add
01:07
the InertiaJS plugin and add a test route to your start routes file. We, however, don't have a project quite yet. So we need to start with one of
01:15
the starter kits that comes with InertiaJS pre-configured. So let's go ahead and hide our browser back away. Let's clear that out and go back out a directory so that we can create a brand new project.
01:24
So we'll just walk through the same flow that we would whenever we're creating an AdonisJS project. So npm init AdonisJS@latest, and we'll define our project name.
01:33
So plot my course. We'll hit "Enter" and it will walk us through the steps needed to create a project. First, it's going to ask us which starter kit we want to use to make things simple on ourselves. We're going to start with the Inertia starter kit
01:42
because that's what this series is all about. Hit "Enter" there. For authentication, we're going to be using sessions. This stores the authentication state whenever we get to that point inside of the session cookie so that we
01:52
don't really need to worry about it at all on the front end. Everything's dealt with on the back end. So we'll use session there. I'm going to be using Postgres, but if you have one of these other database drivers
02:01
already set up on your system, feel free to use it. Lucid's pretty much going to normalize everything for us anyway, so that won't make much of a difference. So I'm going to be using Postgres.
02:10
Again, use whatever you'd like there. Then you have the option to select your front-end adapter. There's view three, react, felt, solid, or you can skip this and configure it manually.
02:19
We're going to be working with view three throughout this series, but for most things, especially the InertiaJS adapter-based things, you're going to be able to reapply it to
02:27
whatever front-end it is that you would like to actually use. So we'll be using view three throughout this series, and it's going to ask you whether or not you want to set up server-side rendering.
02:36
Just after this lesson, we're going to have a lesson specifically on what the difference is between client-side and server-side rendering. So we won't cover that right now in too much detail,
02:44
but server-side rendering does require some additional steps that we need to worry about, and it'd be great to be able to show that in this series. So we're going to be going forward with server-side rendering,
02:53
even though it doesn't really benefit our project in any way. More on that in the next lesson. For now, let's just move forward with server-side rendering for the application if you're following along.
03:01
Then it's going to go through and actually start with our project, getting it all set up on our machine and configured. Awesome. Looks like all of that completed successfully.
03:09
So we can go ahead and clear that out and CD into our application here. We'll leave it there for now, and we'll go ahead and open it up inside of our text editor here. I'm using Visual Studio Code.
03:19
I'm going to go up to File, Open Folder, go into Code. I have this inside of a lessons directory, and there it is right there. Just hit "Open" and voila.
03:27
Now, as you'll see here within our output panel, we are missing an environment variable for DB database. Because we selected a database driver whenever we were setting up our project,
03:35
it's going to fill out our environment variable as such. So we need to fill out those missing environment variable values. So we can dive into our .emv. Go ahead and just close out this output panel.
03:45
You can see the two that we're missing here are DB password and DB database. If you are using Postgres, you have installed locally on your system and you haven't changed any defaults, then these are most likely going to be
03:55
your connection details for your host port and user. That's exactly the case for me. Furthermore, since I'm just on my local machine, the actual password for my Postgres user is just password, and then we have our DB database.
04:05
You want to go into whatever database it is that you're using and create a brand new database for yourself. I already have one created called PlotMyCourse. We are good to go ahead and give this file a save,
04:14
close it out, and call that ready to go. Let's go ahead and take a quick step through our project structure, specifically the InertiaJS things. First and foremost, you're probably going to notice that we have
04:23
a specific inertia directory here off the root of our project. If we go ahead and expand this, we'll see that we have a separate app, CSS,
04:29
pages, and a separate TS config file within here as well. Pages is going to be exactly what you expect it to be. It's going to be relatively similar to the resource pages if you were
04:39
to start with a basic EdgeJS rendered AdonisJS project. It's going to have a homepage welcoming you to your project. That's there to get you going.
04:47
It's also going to have error pages like not found and server error to render out in production should either a 404 or 500 based error be thrown.
04:56
Then close those out. The CSS directory is going to get us started with some app.css stylings. For right now, we can go ahead and ignore that.
05:04
Then we have our app file with an app.ts as well as an ssr.ts file within it. This ssr file is here only because we specified to
05:13
use server-side rendering whenever we were setting up our project. Whenever we are using ssr, InertiaJS is going to require one of each, one for the server-side rendering and one for the client-side rendering.
05:23
We can start by taking a look at our client-side app. You can see that we have some reference imports right there, as well as some typical imports,
05:30
an app name that's coming from our metaenv or defaulting to AdonisJS. This metaenv is really just our environment variables, which if we take a look at that again,
05:39
we don't have that variable defined. It will just default to AdonisJS for us here. Then we get into instantiating our Inertia application. As we send out requests with InertiaJS,
05:49
we'll have a little progress bar that goes across the top of our application. This is where we can set the color of that bar, and we'll just track the progress of that request as it goes out.
05:58
Then we have the ability to specify the title of the application. This is what's displayed inside of the browser title, and it will get injected into the head of our document.
06:07
Then we have resolve, which resolves the actual page components. We'll see this in working later on, but within our controllers,
06:13
we're able to specify a name of the page that we want to render out for any given route. That name is provided into this resolve function, and this resolve function is in charge of finding and
06:23
returning back the component that should be used to render out that page. You'll see that for that, we're looking inside of our pages directory and applying the name onto it.
06:32
So we're going to look inside of our pages directory for any page paths that we provide in. Then it's just importing that component and resolving it and returning it back there.
06:40
Again, we'll work with this resolve method a little bit more later on. For now, we'll scroll on down to our setup function, which is where InertiaJS actually sets up our application.
06:49
I'm going to go ahead and save this file just to get rid of the red squigglies. That's just a lint taking care of those issues automatically for me. You can see setup is provided in an L.
06:57
This is the target element for our application route, which is standard if you're working with any client-side application, you'll have a mounting element and that's exactly what this is.
07:06
Then we have our Inertia application, which is the app component that Inertia will wrap the actual page component with, and that we need to provide into the render method for
07:15
the client-side library that we're using, in our case, we're using Vue. Then we have the default props, which are passed into the rendering of that component there as well.
07:24
Then Inertia also comes with a plugin that we need to instantiate on our app with. Create SSR app comes from Vue. So if we scroll up to our imports, you can see it right here.
07:33
H also comes from Vue. If you're not familiar with Vue, H is the render function for Vue. So it's just going to render out the Vue component.
07:40
Then the use methods, how we attach in plugins with Vue, and then mount is how we actually mount the application so that it gets started on the mount element that we specify,
07:49
which is again, that L that comes through from setup. So before we close this file out, let's go ahead and circle back to what these references are.
07:56
Now, our Inertia.js application uses a separate TS config from our AdonisJS application right down here.
08:03
This is because AdonisJS uses some things that aren't applicable on the client side. So whenever we actually get to our Vue, React, Svelte, whatever application,
08:11
we need to have a separate TS config for that client-side application separate from our AdonisJS TS config on our server.
08:19
So that's why we have two different TS configs going on within this project. The one inside of our inertia directory will be used for our Inertia application, and the one inside of our application root will be
08:28
used for the AdonisJS application, and they are scoped as such. So if we take a look at the AdonisJS one, you can see that it's excluding our inertia path.
08:37
If we take a look at the inertia one, it's including anything within this particular directory. Back to our app.ts file, specifically these references.
08:46
Since Inertia and AdonisJS application are using two separate TS configs, if we ever want to share types from AdonisJS into our Inertia application,
08:54
whatever it might be on the front end, these reference directives inside of our application give TypeScript a way to be able to recognize what those types are from
09:02
AdonisJS application despite using that separate TS configuration. Now, for the most part, our SSR application will be
09:10
a more simplified version of our client-side application. The main difference here is that our application isn't actually going to be mounted to a mounting element,
09:18
but rather is going to be directly provided the page and a method to be able to render that page to a string. Rather than mounting the element and rendering on the client-side,
09:26
the HTML for the initial render is server-side rendered and then kicked back with the actual document as HTML directly from our server.
09:34
Meaning that we don't need to mount it, we just need to define our application and set it up in a way to where it can render the same as our client-side application
09:44
would so that we don't get any hydration mismatches. Now, a hydration mismatch happens whenever the server-side rendering doesn't match the initial client-side rendering.
09:52
So we have the HTML come back directly from our server inside of our document. The HTML for the application there needs to directly match
09:59
the HTML rendered out initially from our client as well, whenever that mounts and takes over. Otherwise, we'll get what's known as a hydration mismatch.
10:07
Now, these view and inertia applications are then mounted inside of an EdgeJS layout called inertia layout instead of our resources views. If we open this up, we'll see just like we
10:17
would with a typical AdonisJS application. We have our Vite call right there for our script mounting points. The page component chunk is then also passed in so that it is readily available for us.
10:26
Then we have our inertia head, which takes care of metadata that we're able to set directly from our inertia application, and our inertia body, which takes care of the mounting element,
10:35
the initial state, and the like. So hopefully, you're a little bit comfortable with what's going on here. We'll dig into this in much more depth as we get going with the series. For now, the main thing that you need to know is that we have
10:45
an inertia directory that holds our actual inertia application with whatever client-side library it is that we're using. It has its own application mounting points for both app, and if you're using SSR,
10:54
we'll have a separate one for SSR. As you add plugins and global components, you want to add them to both of these because the output from both needs to match otherwise you'll
11:03
get what's known as a hydration mismatch. We have CSS for our inertia-specific CSS, and pages that are the mounting point for
11:10
actual pages that we want to render out inside of our application. Then of course, both the inertia application and our AdonisJS application have their own TS configurations,
11:20
because there's some things that AdonisJS needs that our inertia application doesn't and vice versa.
