A Starter Kit for applications with Laravel as the API and NextJS for the Frontend
A Starter Kit for applications with Laravel as the API and NextJS for the Frontend
Find the official documentation at ln-starterkit.com
Laravel and Next.js are two awesome frameworks to build modern Web-Apps. However, creating a Laravel based API and hooking it up to a Next.js frontend (or any other SPA Frontend) can be a quite tedious task that involves a lot of boilerplate (e.g., authentication). This Starter Kit hooks up a Laravel 8 API to a Next.js 10 frontend and includes all the basic features you need, so you can focus on the important and unique parts of your app. The Kit includes:
This Starter Kit leans towards the creation of Server Side Rendered (SSR) dynamic Web-Apps that handle and display dynamic data on the fly. Thus, this Starter Kit is for you if you want users to be able to register and have them be able to create user specific data, dashboards etc. In other words, this repo is not suited for Server Side Generation (SSG) and use cases where the consumed data is known at build time. In fact, Server Side Generation is not supported with this Starter Kit, as the getInitProps() method is called in _app.tsx.
To get things working, we must configure both the backend (Laravel) and the frontend (Next.js) correctly.
Navigate to the root directory. Copy and paste the .env.example file and rename it to .env
cp .env.example .envNow open the .env file and fill in the values as needed. You might notice that the file is very similar to the default .env file that ships with Laravel, but it’s not 100% the same. Some values are already set or changed (e.g., SESSION_DRIVER) and some new ones are added. These configurations are necessary in order to hook the backend up to the frontend.
If you run your frontend on the default URL and Port (http://localhost:3000), you only need to replace the XXXXXXXXXXXXXXXX values. If you do not want to use the Next.js default URL and Port, you also need to adjust the SANCTUM_STATEFUL_DOMAINS variable. Please only provide ONE value here. This means NO comma separated URLs.
If you take advantage of the containerization you should be good to go without changing anything except the email settings (see below) as everything is prepopulated correctly in the .env.example file.
Notice: The repo uses some email functionality (registration, password reset). If you do not want these features, you must make some small tweaks. However, if you do want to take advantage of these features you MUST configure you email settings correctly. The app will break otherwise. Luckily, Laravel makes this extremely easy. More on that later on.
Once you're done you must install all the dependencies via composer:
composer installIf you worked with Laravel before you are probably familiar with artisan. In order to prepopulate our database with all the necessary tables, you must execute the following command:
php artisan migrate --seedThe --seed flag is optional but useful, since it creates some users and an admin for you (more on that below).
Once this is done, we can move to the frontend environment settings
We now take care of settings up our frontend. Therefore, navigate to the /client directory, where our Next.js app lives.
First things first, we need to run npm install to install all our dependencies.
Next, copy and paste the .env.local.example file and rename it to .env.local
cd client; cp .env.local.example .env.localNext.js can handle the .env.local file out of the box and even allows us to access the environment variables in the browser. For more information visit their environment variables documentation. In a nutshell, it tells us that all variables that start with NEXT_PUBLIC_ will be accessible in the browser, which is great news for us!
NEXT_PUBLIC_API_HOST_URL is the URL and host our Laravel API runs on. It defaults to http://localhost:8000. Customize it to your requirements.
NEXT_PUBLIC_USER_HOME_ROUTE is the home route for authenticated users, as the name indicates. It is the route a user will be redirected to after authentication, for example.
NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID is your Google Tag Manager Container ID. If you leave it empty, Google Tag Manager won’t be integrated. However, if you build production ready application, it is highly advised to do so (see more below.)
The app is written with TypeScript. If you instead want good old Javascript you must change all file extensions from .tsx to .jsx or .js. You then also have go through all the files and delete TypeScript specific syntax. My advise would be to leave it as it is and just use the .js extension in the files you create of top of the Starter Kit, if you don't want to use TypeScript.
You might have already noticed that there is a file named /client/config/config.tsx, which does not ship with Next.js by default. This file handles some default configurations for us.
We use axios to make api requests and make some default configurations that our Laravel backend requires.
Also, we export a variable named protectedRoutes. It is an array of routes/slugs that will not be accessible for unauthenticated users. The list also respects sub-routes, which means if we include „/dashboard“, „/dashboard/a“ or „/dashboard/a/b/c“ will be protected as well.
For example:
export const protectedRoutes = [
process.env.NEXT_PUBLIC_USER_HOME_ROUTE, // -> default
"/profile",
"/accout",
// ...
];Customize this file according to your needs.
Congrats! You are now ready to launch the application. In order to get backend and frontend running at the same time, you need two terminal windows. In one, navigate to the root directory of your project and execute
php artisan serveIn the second terminal, navigate to /client and execute
npm run devThe two commands ship directly with Laravel and Next.js, respectively.
Now navigate to the frontend URL. You now see the homepage. You may register a new user under /user/register or login at /user/login. For more info see below.
Multiple parts of this application require proper settings for email. This includes the verification of a newly created users email address as well as the password reset functionality. Configuring email is no absolute must but highly recommended, as some tweaks to the code have to be done otherwise. Plus, these features are quite useful.
To configure your email settings, open the .env file at the root of your project. Under the MAIL_ „section“ you can set any configurations you like. For development, I recommend MailTrap for a fake smtp testing server. You can set up an account for free and let MailTrap generate the .env variables for you that you can then paste into your .env file. All mails you then send from your app will be caught by MailTrap and accessible for you via their dashboard.
A new user can be registered under /user/register.
The following requirements must be pleased in order for the form to be submittable:
/client/services/UserValidator.tsx.If the registration was successful, the user will be redirected to the user home route (defined under /client/.env.local).
If the registration failed (for example because the email is already taken), a proper error message will be displayed. If configured, the user will also receive an email to verify her email address (see section „Email verification“).
If an already authenticated user tries to access /user/register she will be redirected to the user home route.
A user can login under /user/login. If the login was successful, the user will be redirected to the user home route (defined under client/.env.local). If the login fails, a proper error message will be displayed.
If an already authenticated user tries to access /user/register she will be redirected to the user home route.
Most Web-Apps these days require email verification for new users. As the Laravel Next.js Starter Kit leverages Laravel Sanctum on the backend, the API functionality for email verification comes right out of the box.
Important: If you want email verification in your project you MUST properly configure your email settings. Otherwise the application will break, as the Laravel API wants to send an email but does not find the right settings. Find out how to do that in the „Email testing“ section.
Once that’s done you can test things out on the frontend. Visit /user/register and create an account. Afterwards, check your email inbox (e.g. MailTrap) for new mails. You will se a new mail with a link to a URL. Click it. By opening the page, a request with information from the URL will be sent to the API. If the verification was successful, you will be redirected to your User Home Route (set in /client/.env.local). If the the verification fails an error message will be displayed and you will not be redirected.
If you don’t want email verification on your project, navigate to app/Models/User and delete the implements MustVerifyEmail part of the class definition statement. Then, delete the client/pages/user/email directory and delete the verifyEmail function in /client/store/auth/authActions.tsx. For security reasons you might also want to deny access to the backend route from the frontend to the API. To accomplish this, open /config/cors.php and delete "email/verify/*" from the paths array.
A user also has the possibility to reset his password. However, for this to work you must have your mail settings configured correctly. Find out how to do that in the „Email testing“ section.
To test things out visit /user/password/forgot and enter the email address of the account. After submission, you will receive an email with a link. The link includes a token that is valid for 60 minutes. By submitting the form you create a new password.
If you do not want the possibility for a user to reset her password, first delete the /client/pages/password directory. Afterwards, you can (but don’t have to) navigate to /client/store/auth/authActions.tsx and delete the functions forgotPassword and resetPassword. For security reasons you might also want to deny access to the backend route from the frontend to the API. To accomplish this, open /config/cors.php and delete "password/email" and "password/reset" from the paths array.
By default, Laravel does not assign user roles. However, there are many use cases for different user roles, for example if an admin should have access to a dashboard with sensible that another user should not be able to see. Therefore, the Laravel Next.js Starter Kit populates the user table in the database with an additional c
No open issues yet, or sync has not completed.