create-leaderos-theme is a command-line tool that generates a Next.js (App Router, TypeScript) project wired to your LeaderOS site.
What is in the template?
- An exact clone of the main site’s flat theme (same Tabler/Bootstrap CSS, same pages, same URL structure).
- Login/registration, 2FA, e-mail verification, account, store, cart, payment results, credits, chest, gift codes, forum, suggestions, support, help center, applications, forms, blog, downloads, members, leaderboards, punishments, changelog, voting, Gaming Night, Fortune Wheel, Bazaar, custom pages, sitemap/robots, 403/404/maintenance screens.
- The API proxy route (
app/headless/v1/[...path]), server client (lib/leaderos.ts) and page guards (lib/guards.ts). - AI files:
AGENTS.md,CLAUDE.md,.mcp.json.
Requirements
- Node.js 18.18 or newer (current LTS recommended) and npm
- A LeaderOS site with the Headless API enabled and its public key (Quickstart)
Installation
- Interactive
- Non-interactive
- Project folder
- Your LeaderOS website URL:
https://your-site.com - Public key:
pk_live_...
- Test the connection with
GET /headless/v1/site/config(✔ Connected to ... (LeaderOS 6.x)). If it fails it warns but continues. - Copy the template into the folder (the folder must be empty).
- Create
.env.local:
First run
http://localhost:3000 in your browser.
1
Set the Frontend URL
In Settings → Headless API → Frontend URL & Pages enter
http://localhost:3000. Otherwise e-mail links and payment returns go to the LeaderOS site.2
Add an origin (optional)
Not needed because the template uses a proxy; but if you call the API directly from the browser, add
http://localhost:3000 to the allowed origins.3
Browse the site
Log in and try the store and cart. Pages of disabled modules return 404 automatically.
Project structure
Commands
Key patterns
- Page guards: at the top of pages that need a login call
await requireModule('slug')thenconst user = await requireAuth(). Do not hand-writeredirect('/login'). - Data fetching:
const api = await leaderos()in Server Components,useLeaderOS()in interactive components. - Translation:
t('English text')(await getT()on the server,useT()on the client). - Theme options: colors, dark mode and logo come from the flat theme settings in the panel (
config.theme). - HTML fields (content, description) are written by staff; render them with
dangerouslySetInnerHTMLinside.prose-content.
Adding a new page
Next steps
Develop with AI
Customize the theme with Claude Code, Cursor and similar tools.
Deploy
Run the theme on your own VDS.
