A batteries-included starter framework for bootstrapping full-stack web applications with Payload CMS, deployed on Vercel with Neon PostgreSQL. Fork this repo, configure your environment, choose a theme, and ship.

• Framework: Next.js 16 (React 19)
• CMS/Backend: Payload CMS 3
• Database: PostgreSQL 17 (Neon recommended)
• Auth: Auth.js (next-auth v5) with Google and GitHub OAuth
• Styling: Tailwind CSS 4, shadcn/ui, VS Code theme import system
• Storage: Vercel Blob
• Language: TypeScript

• Node.js 22.x or 24.x
• pnpm 9.x or 10.x
• A PostgreSQL 17 database (Neon, Supabase, or local)
• A Vercel Blob store

# Clone and install
git clone <your-fork-url>
cd hackerlab
pnpm install

# Copy the example env file
cp .env.example .env

Fill in the required values in .env (see Environment Variables below), then:

# Start the dev server
pnpm dev

Open http://localhost:3000 for the frontend and http://localhost:3000/admin for the admin panel.

The first user to sign in is automatically promoted to admin.

Create a .env file from .env.example and fill in the required values:

Generate secrets:

# Payload secret
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Auth secret
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

OAuth providers are optional and conditional — only providers with both their CLIENT_ID and CLIENT_SECRET configured will appear on the login page. You can run with just one provider, both, or none (email/password only via the admin panel).

Hackerlab supports Google (GCP) and GitHub OAuth out of the box. Configure one or both depending on your needs.

1. Go to the Google Cloud Console
2. Create a new project (or select an existing one)
3. Navigate to APIs & Services > Credentials
4. Click Create Credentials > OAuth client ID
5. Select Web application as the application type
6. Add authorized redirect URIs:
   • Local dev: http://localhost:3000/api/auth/callback/google
   • Production: https://your-domain.com/api/auth/callback/google
7. Copy the Client ID and Client Secret
8. Add them to your .env:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Note: You may also need to configure the OAuth consent screen under APIs & Services > OAuth consent screen. For development, set it to "External" with test users. For production, submit for verification.

1. Go to GitHub Developer Settings
2. Click New OAuth App (or Register a new application)
3. Fill in:
   • Application name: Your app name
   • Homepage URL: http://localhost:3000 (or your production URL)
   • Authorization callback URL: http://localhost:3000/api/auth/callback/github
4. Click Register application
5. Copy the Client ID
6. Click Generate a new client secret and copy it
7. Add them to your .env:

GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

For production: Create a second OAuth App with your production URL as both the homepage and callback URL, or update the existing one. GitHub OAuth Apps only support one callback URL per app.

• Email is the canonical identity — the same email from different OAuth providers links to one user account
• The first user to sign in is automatically promoted to admin
• Non-admin users redirect to / after login; admins go to /admin
• Both login pages (frontend and admin) dynamically show only the providers you've configured

Hackerlab includes a VS Code theme import system that lets you restyle the entire app using any VS Code color theme. Themes map VS Code color tokens to shadcn/ui CSS variables at build time.

# List bundled themes
pnpm import-theme --list

# Apply a bundled theme to both light and dark modes
pnpm import-theme --file src/themes/dracula.json --both

# Preview the mapping without writing
pnpm import-theme --file src/themes/tokyo-night.json --both --dry-run

# Restore the original palette
pnpm import-theme --restore

# Search and download interactively
pnpm import-theme --vscode "Catppuccin"

# Import from a raw JSON URL
pnpm import-theme --url https://raw.githubusercontent.com/.../theme.json --both

VS Code themes are single-mode. To have different light and dark themes:

pnpm import-theme --file src/themes/solarized-light.json --mode light
pnpm import-theme --file src/themes/dracula.json --mode dark

Visit /admin/theme in the admin panel to browse all available themes with visual previews. Click any theme to see its color palette, then use the CLI commands shown on the page to apply it.

1. Find a VS Code theme JSON file (from a GitHub repo, VSIX, or the marketplace)
2. Save it to src/themes/<name>.json
3. Apply it with pnpm import-theme --file src/themes/<name>.json --both

Theme JSON files follow the VS Code theme format:

{
  "name": "My Theme",
  "type": "dark",
  "colors": {
    "editor.background": "#282c34",
    "editor.foreground": "#abb2bf",
    "button.background": "#4d78cc",
    ...
  }
}

src/
├── app/
│   ├── (frontend)/          # Frontend routes
│   ├── (payload)/           # Payload admin routes
│   └── api/                 # Standalone API routes
├── collections/             # Payload collection configs
├── components/
│   ├── admin/               # Custom admin panel components
│   ├── icons/               # Icon components
│   └── ui/                  # shadcn/ui components
├── lib/
│   ├── auth/                # Auth.js + Payload auth bridge
│   └── theme/               # Theme import system
├── themes/                  # Bundled VS Code theme JSONs
├── migrations/              # Database migrations
└── payload.config.ts        # Main Payload config

Hackerlab is designed for Vercel deployment with Neon PostgreSQL:

1. Push your repo to GitHub
2. Import into Vercel
3. Set all environment variables in the Vercel dashboard
4. Deploy

For the database, create a Neon project at neon.tech and use the connection string as DATABASE_URL.