Get started with Birthday Wall

This guide takes you from zero to a live Birthday Wall in under 10 minutes. You’ll fork the repository, install dependencies, connect a Supabase database, customize the birthday config, and deploy to Vercel.

Steps 3–5 (Supabase setup and environment variables) are required only if you want the wish wall to save messages. The countdown timer, music radio, and games work without a database connection — you can skip to step 6 to run the app locally first.

Fork and clone the repository

Fork the Birthday Wall repository on GitHub, then clone your fork locally.

git clone https://github.com/your-username/birthday-web.git
cd birthday-web

Replace your-username with your GitHub username after forking from github.com/helloxiaozhen/birthday-web.

Install dependencies

Birthday Wall uses Next.js 14 and Supabase. Install all dependencies with npm.

npm install

Set up Supabase

Create a Supabase project and configure the required database tables for the wish wall and page configuration.Follow the full instructions in the Supabase setup guide, which covers:

Creating a new Supabase project
Running the migration SQL to create all required tables
Enabling Row Level Security policies
Locating your project URL and API keys

Set environment variables

In the project root, create a .env.local file and add the following variables. You’ll find the values in your Supabase project under Project Settings → API.

NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
NEXT_PUBLIC_SITE_URL=http://localhost:3000
ADMIN_PASSWORD=your-admin-password

Variable	Description
`NEXT_PUBLIC_SUPABASE_URL`	Your Supabase project URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Public anon key for client-side queries
`SUPABASE_SERVICE_ROLE_KEY`	Service role key for server-side admin operations — keep this secret
`NEXT_PUBLIC_SITE_URL`	The URL where the app is running (`http://localhost:3000` locally)
`ADMIN_PASSWORD`	Password to access the admin panel

Never expose SUPABASE_SERVICE_ROLE_KEY in client-side code or commit it to version control. It grants full database access.

Customize the birthday config

Open lib/birthday-config.ts and update the person object with the celebrant’s details.

export const birthdayConfig = {
  person: {
    name: "Your Person's Name",
    nickname: "Nickname",
    birthday: {
      month: 6,   // 1–12
      day: 19,    // 1–31
    },
    greeting: "A personal message for them",
  } as BirthdayPerson,

  countdown: {
    title: "Days until birthday",
    expiredTitle: "Today is your birthday",
  },
};

The fields you need to set:

Field	Description
`name`	Full name displayed on the countdown page
`birthday.month`	Birth month as a number (1–12)
`birthday.day`	Birth day as a number (1–31)
`greeting`	A short message shown beneath the countdown

Run locally

Start the development server and open the app in your browser.

npm run dev

Visit http://localhost:3000 to see the birthday countdown. Navigate to /radio, /write, /report, and /games to preview all five pages.

Deploy to Vercel

When you’re ready to share Birthday Wall, deploy it to Vercel.Follow the full instructions in the Vercel deployment guide, which covers:

Pushing your code to GitHub
Importing the repository in Vercel
Adding all environment variables in the Vercel dashboard
Configuring a custom domain (optional)

During the Vercel setup, remember to update NEXT_PUBLIC_SITE_URL to your production URL instead of http://localhost:3000.

Next steps

Once Birthday Wall is live, explore the guides below to customize it further.

Customize the birthday config

Change the celebrant’s name, date, greeting, and countdown text.

Add songs to the radio

Build a curated playlist with song titles, artists, lyrics, and artwork.

Wish wall

Learn how visitors submit wishes and how to manage them in the admin panel.

Environment variables reference

Full list of all required and optional environment variables.

Get Started

Features

Customization

Get started with Birthday Wall

Next steps

Customize the birthday config

Add songs to the radio

Wish wall

Environment variables reference

​Next steps

Customize the birthday config

Add songs to the radio

Wish wall

Environment variables reference

Next steps