averlo-next-template

Averlo Next Template

Choose a route profile, materialize a clean project, and build its design system on a focused Next.js App Router foundation.

Averlo provides marketing, authentication, dashboard, and local developer surfaces without turning the generated project into a demo-heavy product. Its frontend stays source-agnostic: server-side resolvers turn fallback or Payload documents into lightweight page, layout, and section props.

The canonical template also publishes /repository-footprint, a commit-history snapshot of its authored repository size. Generated projects do not include it.

Instant Setup

Template repository: github.com/olafBobryk/averlo-next-template

Create a clean project directly from a published profile initializer:

npx create-averlo my-project --profile thin-start --content static

The command installs dependencies by default and initializes a local main repository with one commit and no remote. Use --no-install to generate only the project and lockfile. Non-interactive callers must provide the project directory and --profile; interactive terminals prompt for missing choices.

Agent Bootstrap

Copy this prompt into Codex or another coding agent:

Create a project from https://github.com/olafBobryk/averlo-next-template. Read PRODUCT.md, AGENTS.md, and README.md; help me choose a route profile; materialize it into a new folder; and verify the result before project-specific work. Preserve the existing UI primitives, marketing layout contract, resolvers, and isolated agent dev workflow. Keep secrets, environment files, generated indexes, build output, and local service metadata out of Git.

Equivalent shell-first setup:

git clone https://github.com/olafBobryk/averlo-next-template.git averlo-template
cd averlo-template
npm install
npm run create:project -- --profile <profile> --content <content> --output ../my-project

Then work from the generated project:

cd ../my-project
npm run dev

Storybook

Storybook uses the same checkout and source environment as the isolated Next preview, but it remains a separate Vite process. Start the Next preview first, then let the managed command reuse or start the checkout's sole Storybook instance:

npm run storybook:preview

The command prints the Storybook URL and records it in ignored .codex/storybook-preview.json. Use npm run storybook:status to rediscover it; do not run raw storybook dev or assume a fixed port.

Choose a Profile

Profile selection is the main setup decision:

Profile	Included surfaces	Content choices	Default
full	Marketing, auth, dashboard, and developer tools.	static, payload-ready	payload-ready
app-only	Auth, dashboard, and developer tools; no marketing.	static	static
marketing-only	Marketing and developer tools; no auth or dashboard.	static, payload-ready	payload-ready
thin-start	Minimal marketing specialist surface.	static, payload-ready	payload-ready

Generated projects are one-way starting points rather than alternate states of this checkout. Positive assembly copies only selected, explicitly owned project code and omits template profiles, inventories, and creation machinery.

How It Works

• Route profiles decide which production surfaces belong in the generated project.
• Developer routes under /internal are local-development tools, not public product surfaces.
• Shared primitives provide reusable UI, overlay, motion, focus, and branding foundations.
• Marketing documents describe site layout, pages, and named sections.
• Server resolvers adapt fallback or Payload data into small render props.
• Section renderers own presentation without importing Payload document shapes.

The content source is replaceable; the layout contract and section renderers remain stable.

Content Modes

Marketing-capable profiles support three content states:

• Static: render committed TypeScript fallback content without Payload.
• Payload-ready: retain the guarded scaffold while admin and API routes stay inactive.
• Payload-powered: activate the real admin/API routes with Neon Postgres and Vercel Blob.

No generated profile is Payload-powered by default. Read docs/operations/payload-vercel-neon-blob.md before activation.

The marketing layout model and resolver boundary already exist. When using the optional $cms-backfill workflow, treat that model as an input to preserve and populate—not as a missing schema or permission to introduce a reorderable page builder.

Public Safety

This repository is designed to remain safe as a public template. Do not commit secrets, tokens, deploy hooks, database URLs, Payload secrets, environment files, generated agent indexes, local Vercel metadata, build output, dependency folders, raw client files, or throwaway worktrees.

Use ignored local files or platform environment stores for secrets. Keep source-specific CMS and deployment details behind server-side adapters so the frontend continues to render the same small contract.

Core Workflows

Development

Use npm run dev for the isolated, prewarmed preview workflow. It selects a random port and an isolated build directory, then warms the home route before reporting the preview ready. Use npm run dev:local only when a stable local server is actually needed:

npm run dev

Thin Start

thin-start can also be reviewed as an isolated workspace before committing to that profile. Create it with the normal project command, then run npm run review:thin-start-api -- --root <output> --strict from the template.

Scroll Performance

The repository includes real-page measurement and disposable autoresearch worktrees for scroll-sensitive changes. Use them only when a change is being measured or optimized against real page-scroll evidence; see docs/operations/scroll-performance.md.

Repository Map

.
|-- AGENTS.md               Agent and repository boundaries
|-- PRODUCT.md              Product purpose, audience, and boundaries
|-- docs/benchmarks/        Template-assessment systems and historical evidence
|-- docs/operations/        External-service and measurement runbooks
|-- scripts/                Creation, development, and verification tooling
|-- src/app/                Marketing, auth, dashboard, Payload, and API routes
|-- src/components/         Shared UI and product components
|-- src/lib/marketing-content/  Layout contract, fallback data, and resolvers
`-- src/payload/            Guarded Payload-ready infrastructure

Essential Scripts

Script	Purpose
npm run create:project	Materialize a route profile into a project workspace.
npm run dev	Start an isolated, prewarmed preview on a random port.
npm run dev:local	Start the former local server flow on port 3000–3010.
npm run storybook:preview	Start or reuse the current checkout's Storybook server.
npm run storybook:status	Show the paired preview and Storybook URLs.
npm run storybook:stop	Stop only a Storybook server launched by the coordinator.
npm run measure:storybook-performance	Capture a cold-cache developer-catalog baseline from the managed Storybook instance.
npm run verify:static	Run static policy, formatting, and type checks.
npm run verify:marketing	Verify composed marketing section, shell, and media contracts.
npm run verify:profiles	Materialize and verify every profile.
npm run verify:create-averlo	Pack and smoke-test the public initializer without publishing it.
npm run build	Create the production Next.js build.

Deployment

The template targets Vercel. Static and Payload-ready projects deploy without live Payload routes. Payload-powered projects use Neon for DATABASE_URL, Vercel Blob for BLOB_READ_WRITE_TOKEN, and a project-specific PAYLOAD_SECRET; follow the Payload deployment guide before enabling them.

Further Reading

• Payload on Vercel with Neon and Blob
• Scroll-performance workflow
• Published and legacy skill inventory
• Benchmarks