Havix — AI-powered Next.js Starter

Welcome to Havix — a modern, AI-first starter kit for Next.js. Havix brings together type-safe RPC (oRPC), shadcn UI primitives, Prisma database support, and built-in workflows so you can bootstrap dashboards and backend apps quickly.

Visit: https://havix.app or https://havix.dev

This is a Next.js project bootstrapped with create-next-app. Havix extends that starter kit with an opinionated set of integrations and examples.

Note: The landing page shows a modern build label in the lower-right that displays the Havix name, the package version and the short git commit. Example: Havix v0.1.0 • 5bf4069.

OpenGraph (dynamic):

Havix exposes a dynamic OpenGraph image at /api/og which returns an SVG showing current build info. Deployments and pull requests can use this endpoint to render a build-aware social preview. Example: https://havix.app/api/og.

Getting Started

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.

Sidebar menus (JSON-driven)

This repo supports generating the main sidebar from JSON in src/data/menus/.

• navGroups is the preferred schema for navigation sections — it allows multiple labeled groups.
• navMain is now deprecated. See src/data/menus/README.md for migration steps.

You can run a migration to convert navMain to navGroups for existing files:

pnpm run migrate:menus
pnpm run lint:menus
### Component usage

The `AppSidebar` component reads the `menus` prop to display the sidebar. Import your JSON from a server component (recommended) and pass it to `AppSidebar`:

```tsx
import menus from "@/data/menus/backend.json"
import { AppSidebar } from "@/components/sidebar/app-sidebar"

export default function Layout({ children }: { children: React.ReactNode }) {
	return (
		<AppSidebar menus={menus}>
			{children}
		</AppSidebar>
	)
}

## oRPC + BetterAuth integration

This project uses oRPC (type-safe RPC) and BetterAuth for authentication. To protect oRPC procedures with BetterAuth, the following pieces are used:

- `src/lib/orpc/context.ts` — defines a `base` context containing request `headers` and an `authMiddleware` that validates the session using `auth.api.getSession({ headers })`.
- `src/app/api/rpc/[[...rest]]/route.ts` — passes `request.headers` into the oRPC handler context so the auth middleware can read cookies and session info.
- `src/lib/orpc/orpc.router.ts` — you can use `authorized.handler` for procedures that require authentication.

Example usage in `orpc.router.ts`:

```ts
import { authorized } from '@/lib/orpc/context'

export const setMenu = authorized.handler(async (opts) => {
	// protected; `context.user` and `context.session` are available here
})
```

If a procedure throws an `ORPCError('UNAUTHORIZED')`, the client will receive an error; handle it accordingly in UI components.

### Protecting admin routes

Admin pages that perform server-side changes (e.g. the menu editor at `/backend/menu`) should require authentication. Example in `app/(admin)/backend/layout.tsx`:

```ts
import { auth } from '@/lib/auth/auth'
import { headers } from 'next/headers'
import { redirect } from 'next/navigation'

const session = await auth.api.getSession({ headers: await headers() })
if (!session) redirect('/sign-in')
```

This ensures a valid session before rendering admin UI and avoids unauthorized oRPC calls from public pages.

NavMain supports groups via the navGroups schema. Its old navMain array is deprecated — use navGroups instead.

Route-specific & dynamic menus

You can provide different menu JSON files for different routes. For example:

• src/data/menus/backend.json — used by the admin layout at /backend.
• src/data/menus/dashboard.json — example user menu used at /dashboard.

Two wiring options are supported for AppSidebar:

• Server-side import (pre-render): import menus in a server component & pass menus={menus} to AppSidebar for static pre-rendering.
• Client-side dynamic fetch (loading states): pass menuFile="dashboard.json" to AppSidebar. It will fetch the menu via oRPC (getMenu) and show SidebarMenuSkeleton while loading — useful for per-route menus with loading indicators.

- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.

You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!

## Deploy on Vercel or Havix.app

The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) or host at your own domain (for example, `havix.app`).

Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.