Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 78 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,80 @@
# admin-dashboard

[Vercel's Admin Dashboard](https://github.com/vercel/nextjs-postgres-nextauth-tailwindcss-template) on
**Cloudflare Workers**, deployed by [Orun](https://github.com/sourceplane/orun) to stage
and prod on every merge, and then packaged as an Orun baseline.

This commit is the repository's frame: `intent.yaml` (with the placeholder
workspace `ws_CHANGE_ME`, so CI plans nothing until it is linked), the Orun
CI workflow, the shared TypeScript and ESLint configuration, and the spec
index. The work is tracked as an epic under [`specs/epics`](specs/epics/README.md).
Vercel's [Admin Dashboard](https://vercel.com/templates/next.js/admin-dashboard)
template ([vercel/nextjs-postgres-nextauth-tailwindcss-template](https://github.com/vercel/nextjs-postgres-nextauth-tailwindcss-template))
— a products table with search and paging read through Drizzle, a
customers page, and Auth.js with GitHub sign-in, in shadcn/ui and Tailwind —
running on **Cloudflare Workers + Static Assets** through
[`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), with the
database a **Supabase Postgres** project reached through **Cloudflare
Hyperdrive**, both provisioned by Terraform through
[Orun](https://github.com/sourceplane/orun) and the schema applied by Orun's
`db-migrate`, deployed by
[Orun](https://github.com/sourceplane/orun) to stage and prod on every merge.
Packaging it as an Orun baseline is the next milestone (AD2).

The template's code is the code. What the port changes is what the Workers
runtime and a fresh, unattended deployment force: the Postgres client is
built per request over the Hyperdrive binding (`lib/sql.ts`); the table, the
template's ten products and the key Auth.js signs sessions with are
migrations applied before the app serves, where upstream had its owner
create the table by hand, request a seed route and set `AUTH_SECRET`; and
GitHub sign-in is connected by the owner after the build, the dashboard
serving signed-out until then. Next.js moves from 15 to 16.3.8 so the
template's middleware, now the proxy, can read the session key from
Postgres. Every table in `public` has row-level security, so Supabase's Data
API serves none of it.
See [`specs/epics/admin-dashboard`](specs/epics/admin-dashboard/README.md)
for the design, the milestones and the as-built status, including every
departure.

## What is here (the product)

| Surface | Where |
|---|---|
| The product's name (the page title and the dashboard's home link) | `apps/web/lib/site.ts` |
| The dashboard: products, customers, search, the user menu; the login page | `apps/web/app/(dashboard)`, `apps/web/app/login` |
| Auth.js: its config, the session key, GitHub sign-in, the proxy | `apps/web/lib/auth.ts`, `apps/web/lib/auth-secret.ts`, `apps/web/lib/github.ts`, `apps/web/proxy.ts` |
| The client (Hyperdrive first, `POSTGRES_URL` fallback), the schema, the queries | `apps/web/lib/sql.ts`, `apps/web/lib/schema.ts`, `apps/web/lib/db.ts` |
| The database check the deploy smoke-tests | `apps/web/app/api/health/route.ts` |
| Workers build, bindings and deploy contract | `apps/web/next.config.mjs`, `open-next.config.ts`, `wrangler.template.jsonc` → `wrangler.jsonc` (committed), `component.yaml` |
| The schema, the seed and the session key as migrations, and Lumen's runner | `packages/db` (`@saas/db` — the name the db-migrate composition builds); `apps/web/lib/migrations` is the same SQL for drizzle-kit |
| The Supabase project, the Hyperdrive config, the migration step | `infra/terraform/supabase`, `infra/terraform/cloudflare-hyperdrive`, `infra/db-migrate` |
| Tests | `tests/web`, `tests/db` (vitest; `tests/db` runs the migrations in PGlite) |

## Getting started

```bash
pnpm install
pnpm run wire:fixture # re-render apps/web/wrangler.jsonc from its template (committed; this changes nothing)
pnpm typecheck
pnpm lint
pnpm test
pnpm build # next build + opennextjs-cloudflare build → apps/web/.open-next
```

The build needs no database. Running it locally — a Postgres on
`localhost:54322` (`supabase start`), `pnpm --filter @app/web db:migrate`,
then `next dev` or `wrangler dev` — is in the product's README
(`.baseline/product/README.md`), which is what a product built from here
carries.

## How it maps to Vercel

| Vercel | Here |
|---|---|
| Next.js 15 hosting | One Cloudflare Worker (`.open-next/worker.js`) + Static Assets, on Next.js 16.3.8 |
| Vercel Postgres (`POSTGRES_URL`), a module-level client | The Supabase project's Postgres through Hyperdrive: `getSql()` builds a `postgres` client per request from `env.HYPERDRIVE.connectionString`; `POSTGRES_URL` is for local work without wrangler |
| A table created by hand in the dashboard, then `/api/seed` | `infra/db-migrate` applies `packages/db/src/migrations` per environment — the table, row-level security, the template's ten products, the session key — after the project and the Hyperdrive config exist, before the Worker deploys; there is no seed route |
| `AUTH_SECRET`, set by the owner | Generated once per database into `app_private.secrets`; an `AUTH_SECRET` Worker secret overrides it |
| `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET` | Optional Orun secrets per environment, read at build; unset, no sign-in and a login page that says how to connect GitHub |
| `middleware.ts` (edge) | `proxy.ts` (Node.js), so it can read the session key from Postgres |
| A database created in the dashboard | `infra/terraform/supabase` (one project per environment) + `infra/terraform/cloudflare-hyperdrive` (one config per environment), ids and credentials as orun secrets |
| Vercel Analytics | Removed |
| "Deploy with Vercel" (clone the template) | `orun new --blueprint repo-blueprint.yaml` — a new repository, branded, provisioned, migrated, deployed |

## CI

| Workflow | What it runs | Ships to a product |
|---|---|---|
| `ci.yml` | the Orun pipeline, and the only workflow a product carries: `orun plan --changed`, then one job per lane. A pull request runs the verify lanes (the app built and dry-deployed per environment, both Terraform roots checked and planned, the migrations planned), except the bootstrap's own landings (`orun/BASE-*`), where `plan` alone runs and nothing waits for it — the landing was checked in the build box; a merge applies, migrates and deploys stage → prod. The lanes do not typecheck, lint or run the tests: `baseline.yml`'s e2e tier does, on the landing, before each tag. It plans nothing while `intent.yaml` names the placeholder workspace `ws_CHANGE_ME`, as this repository does. A manual run (Orunbase's Deploy button, or Run workflow on `main`) plans the environment and components it names under the push-to-main trigger, so they deploy as a merge deploys them | yes |
17 changes: 17 additions & 0 deletions apps/web/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Local development only — the Worker never reads this file; its database is
# the HYPERDRIVE binding (wrangler.jsonc's localConnectionString locally).
#
# A Postgres connection string for drizzle-kit (`pnpm db:migrate`, which
# defaults to the Supabase CLI's database below) and for `next dev` without
# wrangler.
POSTGRES_URL=postgres://postgres:postgres@localhost:54322/postgres

# Optional. The session key: unset, the one the migrations generated in the
# database (app_private.secrets) is used.
# AUTH_SECRET=

# Optional. GitHub sign-in — https://authjs.dev/getting-started/providers/github
# (callback URL http://localhost:3000/api/auth/callback/github). Unset, the
# dashboard runs without sign-in and /login says how to connect it.
# AUTH_GITHUB_ID=
# AUTH_GITHUB_SECRET=
21 changes: 21 additions & 0 deletions apps/web/LICENSE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
The MIT License (MIT)

Copyright (c) 2025 Vercel, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
36 changes: 36 additions & 0 deletions apps/web/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# @app/web — the admin dashboard on Cloudflare Workers

Vercel's [Admin Dashboard](https://vercel.com/templates/next.js/admin-dashboard)
template, https://github.com/vercel/nextjs-postgres-nextauth-tailwindcss-template ([demo](https://next-admin-dash.vercel.app/)):
a products table with search and paging read through
[Drizzle](https://github.com/drizzle-team/drizzle-orm), a customers page,
and [Auth.js](https://authjs.dev) with GitHub sign-in, in shadcn/ui and
Tailwind CSS. Here it is built by
[`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare) into one
Worker plus Static Assets, and its Postgres is reached through the Worker's
`HYPERDRIVE` binding.

| File | What it does |
|---|---|
| `lib/site.ts` | The product's name: the page `<title>` and the dashboard's home link |
| `lib/sql.ts` | `getSql()`: a `postgres` client per call — the `HYPERDRIVE` binding's connection string on the Worker, `POSTGRES_URL` without a Cloudflare context |
| `lib/schema.ts` | The `products` table and its `status` enum (with `.enableRLS()`), as upstream declared them |
| `lib/db.ts` | `getDb()` and upstream's queries: five products a page, the total, a search by name |
| `lib/auth.ts` | Upstream's Auth.js config (GitHub, JWT sessions), resolved per request |
| `lib/auth-secret.ts` | The session key: `AUTH_SECRET` when set, else the one the database generated (`app_private.secrets`) |
| `lib/github.ts` | GitHub sign-in, once its OAuth App's id and secret are both set (inlined at build) |
| `proxy.ts` | Upstream's middleware — Auth.js on every page — as Next.js 16's proxy |
| `app/(dashboard)`, `app/login` | Upstream's pages; `/login` says how to connect GitHub until it is |
| `app/api/health/route.ts` | 200 only when the database answers through the binding, the table exists with row-level security and the session key is there |
| `lib/migrations`, `drizzle.config.ts` | drizzle-kit, for a local database (`pnpm db:migrate`, `pnpm db:generate`); the deployed databases are migrated by db-migrate from `packages/db` — the same SQL |
| `wrangler.template.jsonc` → `wrangler.jsonc` | The Worker's config; the render is committed (`pnpm run wire:fixture`) |

The table, the template's ten products and the session key all come from
the migrations: upstream had its owner create the table by hand and request
a seed route, and set `AUTH_SECRET` themselves.

```bash
pnpm db:migrate # the schema, the products and the session key, into POSTGRES_URL (default: the Supabase CLI's localhost:54322)
pnpm dev # next dev, with the Worker's bindings through wrangler's platform proxy
pnpm build && pnpm preview # the built Worker under wrangler dev
```
10 changes: 10 additions & 0 deletions apps/web/app/(dashboard)/actions.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
'use server';

import { deleteProductById } from '@/lib/db';
import { revalidatePath } from 'next/cache';

export async function deleteProduct(formData: FormData) {
// let id = Number(formData.get('id'));
// await deleteProductById(id);
// revalidatePath('/');
}
19 changes: 19 additions & 0 deletions apps/web/app/(dashboard)/customers/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
import {
Card,
CardContent,
CardDescription,
CardHeader,
CardTitle
} from '@/components/ui/card';

export default function CustomersPage() {
return (
<Card>
<CardHeader>
<CardTitle>Customers</CardTitle>
<CardDescription>View all customers and their orders.</CardDescription>
</CardHeader>
<CardContent></CardContent>
</Card>
);
}
38 changes: 38 additions & 0 deletions apps/web/app/(dashboard)/error.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
'use client';

import { useEffect } from 'react';

export default function Error({
error,
reset
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
useEffect(() => {
// Log the error to an error reporting service
console.error(error);
}, [error]);

// Upstream's page asked for a table to be created by hand in the Vercel
// Postgres dashboard. Here the migrations create and seed it (packages/db,
// applied by db-migrate before every deploy), so a page that cannot read it
// means they have not run against this database yet.
return (
<main className="p-4 md:p-6">
<div className="mb-8 space-y-4">
<h1 className="font-semibold text-lg md:text-2xl">
Please complete setup
</h1>
<p>
The products table could not be read. Every deploy applies the
migrations before the site; locally, apply them to the database in
<code> POSTGRES_URL</code>:
</p>
<pre className="my-4 px-3 py-4 bg-black text-white rounded-lg max-w-2xl overflow-scroll flex text-wrap">
<code>pnpm --filter @app/web db:migrate</code>
</pre>
</div>
</main>
);
}
Loading
Loading