How to Add Supabase to a Next.js App (App Router)

Supabase is one of my favorite backend services.

It gives you a PostgreSQL database, authentication, storage, Edge Functions, and much more. It works great with Next.js.

In this guide, I'll show you how to connect Supabase to a Next.js App Router project.

Let's get started.

Prerequisites

Before you begin, make sure you have:

• Node.js installed
• A Next.js App Router project
• A free Supabase account

Step 1. Create a Next.js Project

If you don't already have a project, create one.

npx create-next-app@latest

Move into the project folder.

cd my-app

Install the dependencies.

npm install

Step 2. Install Supabase

Install the official Supabase client.

npm install @supabase/supabase-js

This package lets your application talk to your Supabase project.

Step 3. Create a Supabase Project

Open the Supabase dashboard.

Create a new project.

Choose:

• Organization
• Project name
• Database password
• Region

Click Create Project.

Wait a minute or two while your database is created.

Step 4. Copy Your API Keys

Open your project.

Go to Settings → API.

Copy these values:

• Project URL
• Anon Public Key

We'll use them in the next step.

Step 5. Add Environment Variables

Create a file called .env.local in the root of your project.

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Save the file.

Step 6. Create the Supabase Client

Create a new file.

lib/supabase.ts

Add the following code.

import { createClient } from "@supabase/supabase-js";

export const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

Now you have a reusable Supabase client.

You can import it anywhere in your application.

Step 7. Test the Connection

Import the client into a page or server component.

Then run your first query.

import { supabase } from "@/lib/supabase";

export default async function Home() {
  const { data, error } = await supabase
    .from("todos")
    .select("*");

  console.log(data);

  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

If everything is configured correctly, you'll see data from your todos table.

If you don't have a table yet, create one in the Supabase dashboard and try the query again.

Project Structure

After the setup, your project might look like this.

app/
lib/
  supabase.ts
.env.local
package.json

What's Next?

Now that your app is connected, you can build almost anything.

Some popular features include:

• User authentication
• PostgreSQL database
• File storage
• Real-time subscriptions
• Edge Functions
• Row Level Security
• Database migrations

Supabase handles much of the backend work, so you can focus on building your application.

Final Thoughts

Connecting Supabase to Next.js is quick and simple.

Once you have the client set up, you can use it throughout your app.

This is the setup I use in many of my own projects because it is easy to maintain and works really well.

If you enjoyed this guide, check out more tutorials on parish.cv. I regularly share practical tips about Next.js, React, TypeScript, and building modern web applications.