Learn Inertia
This episode is for members only

Sign up to access "Learn Inertia" right now.

Get started
Already a member? Sign in to continue
Playing
27. Customising Inertia error pages

Episodes

0%
Your progress
  • Total: 2h 20m
  • Played: 0m
  • Remaining: 2h 20m
Join or sign in to track your progress

Transcript

00:00
Customizing error pages is probably not the most important thing that you will want to do when you're learning Inertia. But once you have your first Inertia app up and running, you're probably not going to want to see Laravel's default errors. And in particular, within production, you're not going to want to see the errors for your users showing in a modal window. So we're going to make the experience a lot better and go ahead and customize each of these error messages.
00:26
Let's start over with the 404 page and just go to forward slash nope. We get the default 404 page within Laravel. Now, the way that we traditionally customize this is by going over to the views section, which we know we're not spending much time in at all. Going ahead and creating an errors folder and then creating out a view with the code, the status code for the error, so in this case, 404.
00:54
So let's just say not found. And if we head over and give this a refresh, we have now successfully replaced the 404 page for Laravel. And this will work for any of the status codes that your handler throws when Laravel finds an error. Now, there's a couple of issues with this. The first one is this is still going to show a modal window within Inertia if we see this error.
01:19
Let's go ahead and just demo that really quickly by building out another custom error here. So we're going to just go and create out a let's say a 403 page, which is forbidden. And let's just write forbidden in here. And we're going to go over to our comment store controller and we are authorized to perform this.
01:39
So let's just manually abort this with a 403. So if we head over to our comments page and we post a comment, that's going to give us that custom error, but still within this Inertia modal. So, again, not the best experience for when someone is working with your app. You might want to leave it like this. It's entirely up to you.
02:01
But most of the time you'd want to render out a proper error page with the status. Now, if we take a look at this and we head over to the network tab here, when we go over to all, traditionally what's going to happen is when we post through, we're going to see a XHR request here with this data. That has not given our overall page a 403 status.
02:24
So I guess that's another issue where the entire status of the page can't be read. OK, so let's go ahead and just leave that in there just for now. And let's look at how we customize this. So we're going to go ahead and delete the two custom errors that we've got here because we're not going to need to do that.
02:42
And we're going to head over to our exception handler over in app and exceptions. Now, by default, this does not include a render method. I think in older versions of Laravel it did. So what we're going to do is we're going to pull back the render method that we get inside of here that comes from the base exception handler.
03:04
And we're basically overwriting this. So the first thing that we're going to do is go ahead and call the parent render method and pass the request in and pass the exception in. Just so it handles that in the standard way through Laravel. Now, there's a couple of approaches to take here.
03:21
You could create a bunch of if statements in here underneath each other. So you could have one here, one here, all handling the different status codes. Now, let's just take a look at how we access the status code, first of all. So I'm just going to do a die dump in here on response and status.
03:40
And let's go over and trigger this error. And there we go, we get a die dump on 403. So we can access that within here. And then we can basically use this to determine whether we want to render out individual inertia components, pages for each error,
03:56
or we want to kind of catch all error page for every single error that we have. We're going to do that. And that's the example that's in the inertia documentation. But you can switch this up to pretty much do whatever you like. So what we're going to do is use a simple native in array to grab the response status and check that it's within a predetermined list of responses.
04:20
So we're going to choose 500. In fact, let's just go with two here just to keep things really simple. So I'm going to go with 403 and 404, so a forbidden and a not found. Now, if that's the case, what we want to do is just do what we've been doing everywhere else in our app by rendering out a specific component. So we're going to go ahead and return using the inertia helper and render.
04:42
And we're going to render out an error component. Now, let's just leave it like this for now and just see what happens. So we're going to go back over to our JavaScript section here over in pages. And we're going to create error dot view out. And let's create our template out now and just say error just to see what happens. So if we come over here now and I type something, we know that we are manually triggering that error.
05:04
And you can see that an entirely new page now has been rendered, which is the kind of thing that we would normally expect when we're working with an app. So now that we've got this entirely new page rendered out, what we can do is start to pass the data down we want to see. So really simply, what we could do is pass down the status that we get,
05:27
and then we can use that template to determine what message to show. So let's go ahead and pass the status down to this error page. Let's open this error page up and I'm going to go ahead and bring in our script here. Now, I'm actually going to use the guest layout that comes with Laravel Breeze.
05:44
So let's import that from our layouts and guest layout. And then let's wrap this in that guest layout. And of course, you can design this page out however you want. We're going to go ahead and define out our props in here. Of course, we're going to get a status in here, which is going to be a number.
06:04
And let's go ahead and just dump the status within here. And let's look at the difference. OK, so I'm going to go ahead and post something. And there we go. We get 403. And of course, this is the guest layout that's used for things like logging and register. But you can just build up your own page and have this look how you want.
06:22
So now with this data, now that we're passing just the status down, we can actually go ahead and use this to within here, within a computed property, render out a specific message. So what we can do is in here, import computed from view. And down here, we can create out a title and a message.
06:45
So let's create out a title here using a computed property. This is going to go ahead and determine based on the status code. So let's say 404, what we want to return here. So we define them out inside of this object here. And then from this computed property, what we can do is go ahead and grab the status from that.
07:06
So this status is going to be something like 404. And that will pluck 404 out of here. And it will give us this string back. So you can do this in any way. And like I said, you could render individual pages as well if you want. So let's say 404 not found. And let's create one for our 403 forbidden.
07:24
And let's try this out for forbidden. OK, so why don't we go ahead and bind this title into head? So I'm going to go ahead and put in head from inertia here. And we can go ahead and define this out on the page. And we can set the title and bind that in to the title that we are grabbing from here.
07:47
So now if we post this, it doesn't look like it's working yet. So let's pull this out of here. So we're accessing it from this object. That makes more sense. And if we try this out, it's still not working, because you probably notice we haven't defined a props variable for our props.
08:05
That would help. And third time lucky. There we go. So we've now got 403 forbidden in the title plucked from that. Now what we can do is do pretty much the same thing here and go ahead and grab a description. So we could say not found or that page was not found.
08:24
And you can not access that just as an example. And now what we can do with this description is display this on the page. So now you see it's a bit easier for the 404 that works in exactly the same way. We've just got one page now that handles errors for any circumstance that we give it.
08:47
So that is one option of how to handle this. Now we've still got a little bit of work here to do, because if we look at this, let's just use the 404 as an example. And we head over to our network tab under all. If I give this page a refresh,
09:01
we would expect that the initial request to this here to be a 404. Now what we're actually getting back is a 200 status, because we're just rendering our component. We're not specifically setting any kind of headers or status code on this.
09:19
So what we're going to do is from this, we're going to set a status code. And we're going to grab the response status. So we can do that directly from the response from this inertia render. If we give this a refresh now, you can see that we actually get an error here.
09:38
That is just because we need to go ahead and cast this to a response or create a response from this and just pass the request in. And then we can go ahead and set the status code. So let's give that a refresh. We get the same thing.
09:50
But this time we actually get a 404 not found. So it's a lot more accurate than having that modal pop up, where if you were submitting something and you had an authorization error, you wouldn't actually get this status code for the actual page you're working with.
10:03
Okay, so this is one option. Another option is to go ahead and check the status code directly. So if the response status is 404, then you could render a page specifically for 404. So you could go ahead and render maybe an errors page 404 and then again do the same thing here. So you could do this and build that page out
10:32
and that would render just a specific 404 error for a 404 status. And you could just do this multiple times down the page. Not the cleanest way to do things and there could be a way to pop these into an array and find them, but it's entirely up to you how you structure this.
10:48
Now the other issue with adding this here is that we might not necessarily want to see this when we are working in a local environment. So we're probably while we are developing going to want to see the standard error messages that Inertia gives us. So there's a couple of things that we can do around this and we can first of all in here
11:09
and let's extract this out to a method. So we're going to say this should render custom error page and this status is in an array. So we've got some sort of condition as to whether we should be rendering these custom error pages.
11:25
Let's go down and just create this method out really quickly. This is typically what I do within an Inertia app. This is pretty much the code that I write here. So the first thing is going to be if the app environment is not local
11:45
or not testing, we're going to return true. So basically if it's in production, we do want to render these custom error pages and then otherwise we want to return false. So that's not going to have any effect on these errors.
11:59
So if we hop over to Nope here, we actually end up with an error here that is just because we're not returning the default response just down here. Let's give that a refresh. So we get the standard page because we are in local.
12:13
As soon as we go to production, that is now going to show our custom error pages. Now what I like to do, especially while I'm working locally, is be able to toggle this on and off because you might want to be able to see the error pages quickly. You don't want to come into your code and start to return false directly from here.
12:35
So what I like to do is over in my EMV file, just go ahead and create out whether custom error pages are enabled. So let's say custom error pages enabled. Let's set this to true.
12:49
Let's go ahead and add this to our app config. So config and app and we'll just do this right at the bottom here. So custom error pages enabled and we'll grab that value from our environment. Now what we can do is inside of here,
13:07
we can have another condition to say that the app custom error pages enabled. If that's true, then we want to return true. So now what we can do, if we just head over to EMV and set this to false real quick, we are within a local environment.
13:27
We should just see the standard 404, but to just toggle this to see the custom error pages, we're just going to set that value in our environment file to true. So again, completely optional, but I find this really helpful, particularly when I want to see and when you're developing or changing any of your error pages around.
13:46
So now that we have created out them custom error pages, anything that does trigger an error is just going to redirect the right user over to a custom error page with the correct status. And this is going to work more like a proper app rather than having that modal appear that Inertia gives us mainly for local development.

Episode summary

In this episode, we're diving into how to properly customize your error pages when building apps with Inertia.js and Laravel. Let's be honest, the default Laravel error pages are okay for quick development, but they start to feel clunky—especially once you're up and running in production. The big problem is those error modals that pop up when something's wrong; they're just not ideal for real users.

To start off, we look at the "old school" method: creating custom Blade views in the errors folder (like 404.blade.php), but with Inertia, these end up still showing up inside a modal, which isn’t what you want. Instead, the episode walks you through a much better approach:

  • We customize the app's exception handler to recognize certain error codes (like 403 and 404).
  • When these errors happen, we use Inertia to render a proper Vue page (like an Error.vue page) and pass along the status code, so you can show different messages depending on the error.
  • You'll see how to display the right status and custom content, and even customize the page's title using Inertia's Head component.

We also address an important detail: making sure the actual HTTP response status matches the error, not just the page content. This helps keep things correct for things like crawlers or API clients.

Lastly, we talk about environments. You probably want to keep Laravel's default errors while developing (since they include useful debug info), but switch to your branded error pages in production. We show you how to add an environment variable so you can toggle custom error pages on and off, making it super flexible for both development and production.

By the end of this episode, your users will see smooth, custom error pages that feel like part of your app, not those out-of-place Laravel modals. And you'll have a setup that’s easy to tweak or expand later! 👌

Episode discussion

No comments, yet. Be the first!