Next.js and PlanetScale Netlify Template Tutorial
Build and deploy a Next.js admin dashboard with NextAuth.js, PlanetScale, Prisma, and Netlify.
This guide will show you how to get up and running with the Netlify, Next.js, and PlanetScale starter template. The template includes the following features:
- Simple user admin dashboard
- PlanetScale serverless database
- Prisma ORM integration
- Next.js authentication
- One-click deploy to Netlify
- Tailwind CSS styling
You can see a live demo of the starter application here.
Example of the dashboard application
If you're starting fresh and haven't deployed yet (or don't want to deploy), you can start from the beginning of this tutorial.
To follow along with this guide, you'll need the following:
One-click deploy to Netlify
The one-click deploy button allows you to connect Netlify to your GitHub account to clone the
nextjs-planetscale-starter repository and automatically deploy it. Be sure to sign up for a Netlify account before clicking the deploy button.
Once you click the button, you'll be taken to Netlify’s direct deploy page with the pre-built project’s repository passed as a parameter in the URL. Click the "Connect to GitHub" button to authorize access.
Next, you'll be asked to configure your site variables. For the
Secret value, navigate to
https://generate-secret.now.sh/32 to generate a secret and then paste that in. You can leave the
Database URL and
NextAuth URL values blank for now. Click "Save & Deploy".
Your site will take about a minute to build and then you'll be taken to a settings page. A unique Netlify URL will be generated for the project. You can click that now to see your live site! The next section will show you how to set the project up locally and create your PlanetScale database to connect to your live site.
Set up the project locally
If you already went through the Netlify deployment, find the repository that was created for you in your GitHub account and clone it.
If you didn't deploy and just want to run the template locally, you can clone the
Enter into the folder and install the dependencies:
Run the application with:
Navigate to http://localhost:3000/ in your browser to view the PlanetScale Next.js Starter app.
Next.js PlanetScale Starter application homepage
Create your database
To begin, create a new database. You can either do this in the dashboard or using the PlanetScale CLI.
In the dashboard, click on the "Create a database" button. Name your database "
netlify-starter", or whatever name you wish. Select the region closest to you, and click "Create database".
Next, go to the "Settings" page for your database and check the "Automatically copy migration data" box, select "Prisma" from the "Migration framework" dropdown, and click "Save".
Alternatively, sign in and create a database with the CLI by running the following:
Copiedpscale database create <database-name> -regionSlug
The list of region slugs can be found in our Regions documentation. You'll still need to go into the dashboard to enable automatically copying the migration data.
Set up Prisma shadow branch
Next, you need to set up the Prisma shadow branch. This is a temporary database used for Prisma development.
To create the Prisma shadow branch:
- Click on your
netlify-starterdatabase in your PlanetScale dashboard.
- Click on the "New branch" button.
- Name the branch
- Leave the base branch as
- Select the region closest to you or your application.
- Click "Create branch".
Connect to your database branches locally
To connect locally, make sure you've authenticated in the CLI. If not, follow the directions in the sign-in section of our quick start guide.
Next, connect to your
shadow branches locally by running the following in your terminal in two separate tabs:
Copiedpscale connect <database-name> main --port <port>
Copiedpscale connect <database-name> shadow --port <port>
Choose any unused port. This tutorial uses
3310. You'll see the response "Secure connection to database
netlify-starter and branch
main is established!" along with the local address that your application is on. Take note of that address for the next step.
Set up local environment variables
For the last part of setup, you need to fill in your environment variables.
Make a copy of the
.env.example file at the root of your project and rename it
Copiedcp .env.example .env
SHADOW_DATABASE_URL values come from your PlanetScale database and will be in the following form:
user— the database user
address— the local address returned in the previous step
port— the port you specified in the previous step
database— the name of your database
Below is an example of the
.env file based on this tutorial:
CopiedDATABASE_URL="mysql://firstname.lastname@example.org:3309/netlify-starter"SHADOW_DATABASE_URL="mysql://email@example.com:3310/netlify-starter"NEXTAUTH_URL=http://localhost:3000# Navigate to https://generate-secret.now.sh/32 to generate a secret for the variable belowNEXTAUTH_SECRET=
Remember, these are the values for your local environment. The values needed for the Netlify environment variables will be covered shortly.
Migrate the database
Now that your PlanetScale database is connected to your application, it's time to run migrations and seed the database with some sample users.
In your terminal, run:
Name your migration
initial-migration. This will create a new migration file under
You can view the schema in your PlanetScale dashboard by clicking the
netlify-starter database > "Branches" >
main > "Schema" > "Refresh schema".
You'll now see the following tables:
You can also verify it worked using the PlanetScale CLI. Run the following to start a MySQL shell (where
netlify-starter is your database):
Copiedpscale shell netlify-starter main
Once in the shell, view the tables with:
exit to exit the MySQL shell.
The database schema,
db/schema.prisma, has been loaded and your PlanetScale database is now ready for data.
Seed the database
To seed the database, run the following:
This will add three mock users to the
User database, as described in
db/seed.ts. To verify that they were added, click on the "Console" tab in your PlanetScale dashboard on the
main branch of your
Run the following:
CopiedSELECT * from User;
You can also run this command from the CLI using the same
pscale shell command mentioned above.
Netlify environment variables
Now that you have your site running locally, let's shift back to the live Netlify site.
The final step in the site deployment is configuring your production environment variables. In the Netlify dashboard under your site's settings page, click on "Build & deploy" > "Environment" in the left nav.
Click on the "Edit variables" button and enter in the following key/value pairs:
DATABASE_URL— To find this value, go back to your PlanetScale dashboard, click on the
netlify-starterdatabase, and select the
mainbranch under "Branches". Click on the "Connect" dropdown and then click the "Generate new password" button. Next, click on the "General"" dropdown in that modal and select "Prisma". Copy the value for
urland paste that back in the Netlify dashboard as the value for
DATABASE_URL. Be sure to save your PlanetScale password somewhere as you won't be able to access it again after closing the modal.
NEXTAUTH_SECRET— You may have already filled this out, but if not generate a new secret at https://generate-secret.now.sh/32 and paste in the value that's returned.
NEXTAUTH_URL— Paste in the Netlify site name that was generated for you. For example,
Click "Save". Now, redeploy the site with these new variables by going to "Deploys" in the top nav and clicking the "Trigger deploy" > "Deploy site" button.
Set up your admin account
Now that your site is live and connected to your PlanetScale database, you need to set up your admin account for your application. Go to
/admin/setup on your live Netlify site (or locally if you didn't deploy), and fill in the form to set up your account. This will be automatically saved to your PlanetScale database.
Creating an admin account gives you access to the
/admin route in your application, which is the dashboard to manage your users.
Once you're signed in as an admin, navigate to
/admin to see a list of your users.
Customize and extend
And that's it! If you followed this tutorial completely, you now have a local and production version of your Next.js + PlanetScale + Prisma admin dashboard. So what's next?
Now, it's time to extend it! Next.js Authentication is baked into this starter, so you can explore the Next.js docs to manage authentication in your application.
You also have a fully functional PlanetScale MySQL database built for scale using the power of Vitess. You might have noticed that this tutorial uses the same database locally as it is in production. This was just for simplicity, but with PlanetScale, you can take advantage of our powerful branching feature to create development branches of your database specifically for testing locally. All you have to do is create a new branch and swap out the
DATABASE_URL environment variable in your local
Finally, you have Prisma ORM already configured in your application. If you want to add any more fields to your
User table or create any new tables, Prisma makes it easy with the
schema.prisma file. If you want to make any schema changes, it's a perfect time to try out the PlanetScale branching feature. If you mess up, those changes won't touch production. And once you're satisfied with the changes, you can deploy to production without causing downtime thanks to PlanetScale's non-blocking schema changes.
Hopefully this tutorial has been helpful. We'd love to hear how you're extending your starter application. Tweet us @PlanetScaleData and share what you built!