starter-next-demo — Next.js Starter Template

SHA-256: 3384daa8883286fb13e43a7377e465130e0378b0ea7b1b13745d29859570d6c0

2026-10-14T22:35:33.353Z

# Lyra DS Next.js template

A minimal [Next.js](https://nextjs.org) template for
[Lyra Design System](https://lyra-ds.dev). It ships the public Lyra styles
and React packages, local fonts, theme selection (light / dark / system),
live white-label branding, and ready-to-go lint, test, and CI setup.

**[See the live demo →](https://lyra-ds.github.io/starter-next-demo/)**

## Create your project

Click **Use this template** on GitHub, or:

```sh
npx create-next-app@latest my-app -e https://github.com/lyra-ds/starter-next
```

Plain cloning works too. Then:

```sh
pnpm install
pnpm dev
```

`npm` and `yarn` work as well.

## After cloning

- [ ] Rename `name` in `package.json`.
- [ ] Edit the `metadata` export in `app/layout.tsx` (title, description).
- [ ] Replace the example brands in `app/brand.css` with your own.
- [ ] Swap `app/icon.svg` for your favicon.
- [ ] When you start building, delete `components/starter-home.tsx` (and its
      test) and replace `app/page.tsx`.

## White-label branding

Lyra rebrands with only four CSS variables — everything else derives from
them:

```css
[data-brand='acme'] {
  --brand: #176b87;
  --brand-contrast: #ffffff;
  --brand-radius: 0.75rem;
  --brand-font: 'Plus Jakarta Sans', sans-serif;
}
```

See `app/brand.css` for the two example brands the demo switches between.
The demo's "Lyra" option is the baseline look: it removes `data-brand`
entirely — never set the attribute without defining `--brand`, or the
derived accent group resolves to nothing.

## Scripts

| Script              | What it does                |
| ------------------- | --------------------------- |
| `pnpm dev`          | Start the dev server        |
| `pnpm build`        | Production build            |
| `pnpm test`         | Run tests (Vitest + jsdom)  |
| `pnpm lint`         | ESLint (next presets)       |
| `pnpm format`       | Prettier write              |
| `pnpm format:check` | Prettier check (used in CI) |

CI runs lint, format check, tests, and build on every push and PR.

## Deploy

This demo is deployed to GitHub Pages by
[`.github/workflows/deploy.yml`](./.github/workflows/deploy.yml) on every
push to `main`. Pages serves static files only, so the workflow builds
with `GITHUB_PAGES=true`, which turns on `output: 'export'` and the
`basePath` in `next.config.ts` and publishes `out/`.

The flag keeps those settings out of local dev, which still serves from
the root. To deploy your own fork: set the `basePath` to your repository
name (or drop it for a custom domain), then enable _Settings → Pages →
Source: GitHub Actions_.

## AI agents

The template ships an [`AGENTS.md`](./AGENTS.md) that points AI coding
agents at the Lyra DS docs, the machine-readable component contracts
([llms.txt](https://lyra-ds.dev/llms.txt)), and this project's commands and
conventions. Keep it updated as your project evolves.

## Links

- [Lyra DS](https://lyra-ds.dev)
- [Lyra repository](https://github.com/lyra-ds/lyra)
- [@lyra-ds/styles on npm](https://www.npmjs.com/package/@lyra-ds/styles)
- [@lyra-ds/react on npm](https://www.npmjs.com/package/@lyra-ds/react)