Steps to run the site locally for development or curiosity
Follow these steps to create a fork of this repository and clone it to your local machine.
If you have just run git clone ... , the next step would be to move into the cloned repo:
cd hacktoberfestThis repo requires node, pnpm, and the Netlify CLI to get started.
The best way to install node is to download the installer from their site. This repo requires node version 24 or newer (see .nvmrc), which is the current LTS version.
If you already have a different version of node installed, but don't want to update globally, you can install a package called nvm, which will allow you to easily switch node versions. Once you have nvm installed (or if you already have it installed), you can run nvm use in the main directory and it will install the proper version of node.
pnpm is a package manager that is used to install the rest of our dependencies.
Read more about pnpm on their docs site.
The best way to install pnpm for this project is by using Corepack, a new feature bundled with Node.
Install pnpm via corepack with the following commands:
corepack enable
corepack prepareUse the following command to create a local .env.local file. Then open the new file (.env.local) and fill in the values -- every variable is documented inline in the example file.
cp .env.local.example .env.localThe only value you need of your own is a secret: generate one with openssl rand -base64 32 and put it in BETTER_AUTH_SECRET. You sign in with the Auth DevTools panel -- see Authentication.
Leave VC_GITHUB_ORG unset if you are not a Virtual Coffee org member -- the admin-role lookup is then skipped entirely and everything else works normally.
Once you have node, pnpm, and the Netlify CLI installed, you're ready to install the local dependencies! Run the following command:
pnpm installThen link your checkout to the Netlify project, which is what lets the CLI start a local database for you:
netlify login
netlify linkAt this point you're ready to roll! Run the following command to get rolling!
pnpm devRead more about what pnpm dev does in the following section.
The following commands are available for your use. Most of the time you'll only ever need pnpm dev.
pnpm devThis is the only command you need to do normal local development.
It runs netlify dev, which starts Next and the local Postgres database, then serves both at http://localhost:8888. Any changes you make should re-build the site and re-load your browser.
Use ctrl-c to quit the server when you're done.
Use
pnpm dev, notnextdirectly. The local database only starts alongside the Netlify dev server, sopnpm dev:nextwill boot the site and then fail on the first query. If you see an error saying no database connection is available, this is why.
Before your first run, apply the migrations:
netlify database migrations applyThe schema lives in db/schema/. auth.ts is generated by the Better Auth CLI and must not be hand-edited; app.ts holds the application tables.
Netlify owns migration state and applies netlify/database/migrations on deploy, so drizzle-kit is only ever used to author SQL -- never run drizzle-kit migrate or push against this project.
# 1. edit db/schema/app.ts, then generate the SQL
pnpm db:generate
# 2. create the migration Netlify will apply
netlify database migrations new -d "what changed"
# 3. copy the SQL from db/.drizzle into that migration file, then apply it
netlify database migrations applyIf you change the Better Auth config in lib/auth.ts in a way that affects its tables, run pnpm auth:generate first to regenerate db/schema/auth.ts.
Sign-in is GitHub OAuth through Better Auth, configured in lib/auth.ts. There is exactly one GitHub OAuth app, and it is registered with production's callback only: https://osweave.virtualcoffee.io/api/auth/callback/github. The old hacktoberfest.virtualcoffee.io alias redirects there (netlify.toml), so sessions only ever live on one domain.
- Without GitHub credentials (most contributors). Run
pnpm devand use the Auth DevTools panel in the bottom-right corner to create throwaway Member or Admin users and switch between them. The "Sign in with GitHub" button is replaced by a pointer to that panel; that is expected. - With real GitHub sign-in (maintainers). Ask a maintainer for production's
GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRETandOAUTH_PROXY_SECRET, and put them in.env.local. Signing in athttp://localhost:8888sends you to GitHub, back to production's callback, and then back to localhost with your session.
Previews sign in the same way: Better Auth's oAuthProxy plugin sends GitHub to production's callback, production exchanges the code and encrypts the profile with OAUTH_PROXY_SECRET, and the preview creates the user and session in its own database branch. Production skips the hop. A preview's database is a fork of production's, so a preview has production's data behind production's sign-in. The devtools panel is off on every Netlify deploy.
Set these in the Netlify UI with the Functions scope, so they reach the function runtime:
| Variable | Production | Deploy previews / branch deploys | Local |
|---|---|---|---|
BETTER_AUTH_SECRET |
value A | a different value | your own |
OAUTH_PROXY_SECRET |
value B | the same value B | value B, or unset |
GITHUB_CLIENT_ID |
set | the same value | the same value, or unset |
GITHUB_CLIENT_SECRET |
set | the same value | the same value, or unset |
- A distinct
BETTER_AUTH_SECRETper context means a session from one deploy is worthless on another. OAUTH_PROXY_SECRETmust match everywhere: production encrypts what the other side decrypts. A mismatch shows up as an error after the GitHub round-trip.BETTER_AUTH_URLis not used. Do not set it anywhere; the base URL is derived from the request against an allowlist inlib/auth.ts.
Because previews get these secrets and a fork of production's data, the Netlify site's Sensitive variable policy requires approval before building pull requests from unrecognized authors. Approve a fork's deploy only after reading its changes.
- NextJS
- TypeScript
- Better Auth for authentication
- Netlify DB with Drizzle
- Tailwind UI
- Hosted on Netlify