> ## Documentation Index
> Fetch the complete documentation index at: https://developer.leaderos.net/llms.txt
> Use this file to discover all available pages before exploring further.

# create-leaderos-theme

> Create a ready Next.js theme connected to your LeaderOS site with a single command.

`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](https://developer.leaderos.net/headless/en/quickstart.md))

## Installation

> [tab] Interactive
>
> ```bash theme={null}
> npm create leaderos-theme@latest my-theme
> ```
>
> Answer the prompts:
>
> 1. **Project folder**
> 2. **Your LeaderOS website URL**: `https://your-site.com`
> 3. **Public key**: `pk_live_...`

> [tab] Non-interactive
>
> ```bash theme={null}
> npx create-leaderos-theme my-theme \
>   --url https://your-site.com \
>   --key pk_live_XXXXXXXX \
>   --yes
> ```

The tool will:

1. Test the connection with `GET /headless/v1/site/config` (`✔ Connected to ... (LeaderOS 6.x)`). If it fails it warns but continues.
2. Copy the template into the folder (the folder **must be empty**).
3. Create `.env.local`:

```bash theme={null}
LEADEROS_URL=https://your-site.com
LEADEROS_PUBLIC_KEY=pk_live_XXXXXXXX
```

## First run

```bash theme={null}
cd my-theme
npm install
npm run dev
```

Open `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

```
my-theme/
├── app/
│   ├── (site)/            # pages with header + footer
│   ├── (auth)/            # login/registration layout
│   ├── headless/v1/[...path]/route.ts   # API proxy
│   ├── layout.tsx
│   ├── sitemap.ts, robots.ts
├── components/            # header, footer, product card, pagination…
├── lib/
│   ├── leaderos.ts        # server client, getConfig(), getUser()
│   ├── guards.ts          # requireAuth(), requireGuest()
│   └── module-page.ts     # requireModule(), apiCall()
├── public/                # CSS, images
├── AGENTS.md  CLAUDE.md  .mcp.json
└── .env.local
```

## Commands

| Command | Purpose |
| - | - |
| `npm run dev` | Development server |
| `npm run build` | Production build |
| `npm start` | Starts the built app |
| `npm run typecheck` | TypeScript check |

## Key patterns

* **Page guards**: at the top of pages that need a login call `await requireModule('slug')` then `const user = await requireAuth()`. Do not hand-write `redirect('/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 `dangerouslySetInnerHTML` inside `.prose-content`.

## Adding a new page

```tsx theme={null}
// app/(site)/posts/page.tsx
import { requireModule, apiCall } from '@/lib/module-page';
import { leaderos } from '@/lib/leaderos';

export default async function Page() {
  await requireModule('blog');               // 404 if the module is off
  const api = await leaderos();
  const { data } = await apiCall(() => api.blog.posts.list());
  return <ul>{data.map((p) => <li key={p.id}>{p.title}</li>)}</ul>;
}
```

> [!WARNING]
>
> When you change the footer or layouts, make sure `<PoweredBy />` stays visible. This is a license requirement.

## Next steps

> [card] [Develop with AI](https://developer.leaderos.net/headless/en/ai-development.md)
>
> Customize the theme with Claude Code, Cursor and similar tools.

> [card] [Deploy](https://developer.leaderos.net/headless/en/deployment.md)
>
> Run the theme on your own VDS.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.