Getting started

This guide takes you from an empty GitHub repository to a running site with an admin account. Plan on about five minutes once you have a Supabase project ready.

What you need#

1. Create your repository#

Start each client site from a fresh copy of the starter. Clone it into a new folder and move into it:

git clone https://github.com/jahzlariosa/jed.git my-site
cd my-site

You can name the folder anything you like. my-site is just an example.

2. Install dependencies#

npm ci

Using Windows PowerShell 5.1? Run each command on its own line. It doesn't support chaining commands with &&.

3. Configure the environment#

npm run setup

Setup creates .env.local from .env.example and asks for the Supabase URL, publishable key, and the other required settings. It checks that Supabase accepts the publishable key, and it does not print secret values. For a hosted project, copy the URL and keys from Project Settings > API. For local Supabase, start the stack first (next step), run npx supabase status, then run npm run setup again.

See Environment variables for what each value does.

4. Apply the database schema#

The schema lives in supabase/migrations/. Apply it with the Supabase CLI if you can.

Local, with Docker:

npx supabase start
npx supabase db reset

Hosted project:

npx supabase login
npx supabase link --project-ref <your-project-ref>
npx supabase db push

If you can't use the CLI, open the Supabase SQL Editor and run each file from supabase/migrations/ in filename order, one at a time. Don't skip any. Once you have an admin account, the SQL templates screen lists the same files with a copy button and shows which ones are applied. supabase/seed.sql is optional and mostly useful for local sample data.

5. Create the first admin#

New accounts get the member role. The first admin has to be granted in SQL.

1. Make sure email signups are on in Supabase under Authentication > Providers > Email.
2. Sign up at http://localhost:3000/signup, or invite yourself from the Supabase dashboard.
3. In the Supabase SQL Editor, run this once with your email:

insert into public.user_roles (user_id, role_code)
select user_id, 'admin'
from public.profiles
where lower(email) = lower('you@example.com')
on conflict do nothing;

1. Sign in and open /admin.

After this, you can give other people the admin role from Admin > Users.

6. Run the dev server#

npm run dev

Open http://localhost:3000. When setup is still incomplete, the dev server opens /setup instead. That page is only available while you are running the app locally. When you run Supabase locally, confirmation and password reset emails land in Inbucket at http://127.0.0.1:54324.

7. Check the setup#

npm run doctor

Doctor checks the environment, Supabase connectivity, the latest migration when the key can read it, and the Node.js version. It exits with an error if a check fails.

8. Brand the site#

Go to Admin > Settings and set:

• Site name, used in the header, page titles, and sign-in screens.
• Accent color, used for buttons, links, and focus rings across the site and admin.
• Logo URL, used wherever the site shows public branding.
• Contact email, which turns on the contact form.

Scripts#

Pulling in starter updates#

Client sites cloned from the starter don't sync on their own. To bring improvements from the starter into a client site:

git remote add starter https://github.com/jahzlariosa/jed.git
git fetch starter
git log HEAD..starter/main --oneline
git diff HEAD starter/main

Merge or cherry-pick what you need. Expect conflicts in branding, AGENTS.md, and client routes. If new migrations came in, apply them to each environment with npx supabase db push, then run npm ci, npm run check, npm test, and npm run build before you deploy.

Common problems#