00:05
configuration step that allows it to configure InertiaJS into any AdonisJS project. So if you have a pre-existing project, you can easily add InertiaJS to it at any point in time.
00:15
Just go ahead and cd into whatever that project is and then run node ace add at AdonisJS slash Inertia and that command will both install the InertiaJS
00:25
package into 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:35
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.
00:45
So I've just expanded this little panel out here and it walks through all the steps. So we're going to configure the Inertia provider inside of our providers array, add in the middleware, create a configuration file for
00:55
us, the InertiaLayout edge view, the CSS as well as the JavaScript files needed to instantiate your application on the client side, a welcome page, error pages.
01:05
It's also going to update your V configuration to add 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:25
So we'll just walk through the same flow that we would whenever we're creating an AdonisJS project. So npm init AdonisJS at latest, and we'll define our project name. So plot my course.
01:35
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. It's simple on ourselves. We're going to start with the Inertia starter kit because that's what this series is all about.
01:45
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 don't really need to worry about it at all on the front end.
01:55
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 already set up on your system, feel free to use it. Lucid's pretty much going to
02:05
visualize everything for us anyway, so that won't make much of a difference. So I'm going to be using Postgres. Again, use whatever you'd like there. And then you have the option to select your front end adapter.
02:15
There's Vue 3, React, Svelte, Solid, or you can skip this and configure it manually. We're going to be working with Vue 3 throughout this series, but for most things, especially the InertiaJS
02:25
adapter based things, you're going to be able to reapply it to whatever front end it is that you would like to actually use. So we'll be using Vue 3 throughout this series, and it's going to ask you whether or not you want to set up server-side
02:35
rendering. 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, but server-side
02:45
rendering does require some additional steps that we need to worry about, and it would be great to be able to show that in this series. So we're going to be going forward with server-side rendering, even though it doesn't really benefit our
02:55
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. Then it's going to go through and actually start with our project, getting it all set
03:05
up on our machine and configured. OK, awesome. Looks like all of that completed successfully, 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
03:15
and open it up inside of our text editor here. I'm using Visual Studio Code. 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.
03:25
Just hit Open, and voila. Now, as you'll see here within our output panel, we are missing an environment variable for dbDatabase. 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
and you can see the two that we're missing here are dbPassword and dbDatabase. If you are using PostgreSQL, you have it 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, and that's exactly the case for me. Furthermore, since I'm just on my local machine, the actual password for my PostgreSQL user is just password, and then we have our dbDatabase.
04:05
You'll 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, close it out, and call that
04:15
ready to go. So 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 a specific Inertia directory here
04:25
off the root of our project. If we go ahead and expand this, we'll see that we have a separate app, CSS, Pages, and a separate TSConfig file within here as well. Pages is going to be exactly what you expect
04:35
it to be. It's going to be relatively similar to the resource pages if you were to start with a basic EdgeJS rendered AdonisJS project. It's going to have a homepage welcoming you
04:45
to your project that's there to get you going. It's also going to have error pages like NotFound and ServerError to render out in production should either a 404 or a 500
04:55
based error be thrown, and 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. And then we have our app
05:05
file with an app.ts as well as an ssr.ts file within it. This ssr file is here only because we specified to use server-side rendering whenever
05:15
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. We can start by taking a look at our client-side
05:25
app. You can see that we have some reference imports right there as well as some typical imports. An app name that's coming from our metaenv or defaulting to AdonisJS.
05:35
This metaenv is really just our environment variables, which if we take a look at that again, we don't have that variable defined. So it will just default to AdonisJS for us here. And then we get
05:45
into instantiating our Inertia application. As we send out requests with InertiaJS, 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,
05:55
and it will just kind of track the progress of that request as it goes out. 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
06:05
injected into the head of our document. Then we have resolve, which resolves the actual page components. We'll see this in working later on, but within our controllers, we're able to specify a name
06:15
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 returning back the component
06:25
that should be used to render out that page. And you'll see that for that, we're looking inside of our pages directory and applying the name onto it. So we're going to look inside of our pages directory for any
06:35
page paths that we provide in. And then it's just importing that component and resolving it and putting it back there. Again, we'll work with this resolve method a little bit more later on. For now, we'll scroll on down
06:45
to our setup function, which is where InertiaJS actually sets up our application. I'm going to go ahead and save this file just to get rid of the red squigglies. That's just Lint taking care of those issues automatically
06:55
for me. And you can see setup is provided in an L. 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
07:05
and that's exactly what this is. 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
07:15
method for 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. And then Inertia also
07:25
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. H also comes from Vue. If you're not
07:35
familiar with Vue, H is the render function for Vue. So it's just going to render out the Vue component. Then the use method is how we attach in plugins with Vue. And then mount is how we actually
07:45
mount the application so that it gets started on the mount element that we specify, which is again that L that comes through from setup. All right. So before we close this file out, let's go ahead and circle back to what these
07:55
references are. Now, our Inertia JS application uses a separate TS config from our AdonisJS application right down here. This is because AdonisJS uses
08:05
some things that aren't applicable on the client side. So whenever we actually get to our Vue, React, Svelte, whatever application, we need to have a separate TS config for that client-side application
08:15
separate from our AdonisJS TS config on our server. 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
08:25
application, and the one inside of our application root will be 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
08:35
it's excluding our Inertia path. And if we take a look at the Inertia one, it's including anything within this particular directory. Back to our app.ts file, specifically
08:45
these references. Since Inertia and our AdonisJS application are using two separate TS configs, if we ever want to share types from AdonisJS into our Inertia application,
08:55
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 our AdonisJS application, despite using that
09:05
separate TS configuration. Now, for the most part, our SSR application will be a more simplified version of our client-side application. The main difference here is that our application
09:15
isn't actually going to be mounted to a mounting element, 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
09:25
rendering on the client-side, 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:35
This doesn't mean 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 would so that we don't
09:45
get any hydration mismatches. Now, a hydration mismatch happens whenever the server-side rendering doesn't match the initial client-side rendering. So we'll have the HTML come back directly from our server
09:55
inside of our document. The HTML for the application there needs to directly match the HTML rendered out initially from our client as well whenever that mounts and takes over.
10:05
Otherwise, we'll get what's known as a hydration mismatch. Now, these View and Inertia applications are then mounted inside of an EdgeJS layout called InertiaLayout instead of our ResourcesViews.
10:15
If we open this up, we'll see just like we 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
10:25
readily available for us. Then we have our InertiaHead which takes care of metadata that we're able to set directly from our Inertia application. And our InertiaBody which takes care of the mounting
10:35
element, the initial state, and the like. Alright, 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, it will have a separate
10:55
one for SSR. As you add plugins and global components, you'll want to add them to both of these because the output from both needs to match. Otherwise, you'll get what's known as a hydration mismatch.
11:05
We have CSS for our Inertia-specific CSS and pages that are the mounting point for actual pages that we want to render out inside of our application. And then, of course, both
11:15
the Inertia application and our AdonisJS application have their own TS configurations because there's some things that AdonisJS needs that our Inertia application doesn't and vice-versa.
