Next.js dashboard for browsing, previewing, resending and cancelling VintaSend and VintaSend-TS notifications, with pluggable authentication (Clerk or Auth0) selected via environment variables.
The dashboard is a pure client of the
VintaSend API. It holds no
notification backend, no database credentials and no template rendering: it
reads and writes everything through the API's HTTP contract. Any implementation
of that contract can serve this UI — including one built on the Python
vintasend package.
Everything that is not user interface comes from
vintasend-dashboard-core:
the typed client generated from openapi.yaml, the TanStack Query hooks over
it, and the notification filters that live in the URL. This repository is
meant to be read as an example. If you want a dashboard with your own design
system, inside your own admin app, you install that package and replace the
components here — not the data layer.
browser this app's server elsewhere
┌──────────────┐ ┌────────────────────┐ ┌─────────────────┐
│ components │ │ /api/vintasend │ │ vintasend-api │
│ + │ ──────▶ │ proxy route │ ─────▶ │ + │
│ dashboard │ ◀────── │ │ ◀───── │ your backend │
│ -core │ JSON │ session checked │ JSON │ │
└──────────────┘ │ API key added │ └─────────────────┘
└────────────────────┘
the only place the key exists
The API authenticates with a bearer key that is a server-side secret, so the
browser never talks to the API directly. The client is pointed at
/api/vintasend, a route in this app that checks the visitor's session and then
re-signs the call with VINTASEND_API_KEY. The key never reaches a browser.
- Install dependencies:
npm install- Create your local environment file:
cp .env.example .env.local- Point the dashboard at a running VintaSend API:
VINTASEND_API_URL=http://localhost:3333
VINTASEND_API_KEY=the-same-key-the-api-was-started-withIf you do not have an API running yet, follow the setup in vintasend-ts-api or vintasend-api — that is where you configure which VintaSend backend, adapters and template renderer to use, along with the GitHub credentials used for template previews.
- Configure authentication (see below), then start the app:
npm run devOpen http://localhost:3000.
| Path | Responsibility |
|---|---|
app/providers.tsx |
The query cache and the VintaSend client, pointed at the proxy route. |
app/api/vintasend/[...path]/route.ts |
Session-checked proxy that adds the API key. The only server-side code that sees it. |
app/components/ |
The notifications page: table, filters, detail panel, dialogs. |
lib/auth/ |
Pluggable authentication. The core takes no position on this. |
proxy.ts |
Route protection, and the provider context the proxy route needs. |
There is no lib/api and no app/actions.ts. The contract types, the endpoint
calls, the URL filter state and the cache invalidation all come from
vintasend-dashboard-core:
const { notifications, filters, setFilters, page, setPage, setSort, hasNextPage } =
useFilteredNotifications({ router: useNextRouterAdapter() });Notifications arrive with a kind discriminator (user or one-off), so
components branch on that rather than sniffing for fields. Errors from the API
carry a machine-readable code; the preview dialog, for example, uses
getApiErrorCode(error) === 'PREVIEW_UNAVAILABLE' to tell "this notification
never recorded a commit" from a genuine failure.
The point of the split is that the interesting half is reusable. To start from scratch with a different design system:
npm install vintasend-dashboard-core @tanstack/react-query- Copy
app/providers.tsxandapp/api/vintasend/[...path]/route.ts. The proxy route is what keeps the API key server-side; keep that shape whatever else you change. - Build components against the hooks.
app/components/notifications-page-client.tsxis the worked example: it is UI and dialog state, and every piece of data in it arrives from a hook.
The package's own README documents the full hook surface, the capability negotiation and the router adapters.
The dashboard uses a strategy pattern: resolveAuthStrategy() reads
AUTH_PROVIDER and delegates auth operations to the chosen provider. The
proxy middleware (proxy.ts) protects routes and handles provider-specific
auth flows, while the app layout wraps the UI with the provider component.
- Clerk: Uses
clerkMiddleware()and renders Clerk components - Auth0 v4: Uses
auth0.middleware()which auto-mounts routes at/auth/*(no API route handlers needed)
- Create a Clerk application and copy the publishable/secret keys.
- Set
AUTH_PROVIDER=clerkin.env.local. - Add the Clerk keys listed below.
- Start the dev server and visit
/sign-in.
- Create an Auth0 Regular Web Application.
- Configure application URLs:
- Allowed Callback URLs:
http://localhost:3000/auth/callback - Allowed Logout URLs:
http://localhost:3000 - Allowed Web Origins:
http://localhost:3000
- Allowed Callback URLs:
- Set
AUTH_PROVIDER=auth0in.env.local. - Add the Auth0 values listed below.
- Start the dev server and visit
/auth/login.
Note: This dashboard uses Auth0 SDK v4, which no longer uses the /api prefix for auth routes. The routes are now mounted automatically by the middleware at /auth/*.
| Variable | Provider | Description |
|---|---|---|
| VINTASEND_API_URL | API | Base URL of the VintaSend API (e.g. http://localhost:3333). |
| VINTASEND_API_KEY | API | Shared secret sent as a bearer token. Server-side only. |
| AUTH_PROVIDER | Clerk, Auth0 | Selects which auth strategy to use (clerk or auth0). |
| NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Clerk | Clerk publishable key. |
| CLERK_SECRET_KEY | Clerk | Clerk secret key. |
| AUTH0_SECRET | Auth0 | Session cookie encryption secret. |
| APP_BASE_URL | Auth0 | Base URL of the app (e.g. http://localhost:3000). Note: In Auth0 v4, this was renamed from AUTH0_BASE_URL. |
| AUTH0_DOMAIN | Auth0 | Auth0 tenant domain without scheme (e.g. example.us.auth0.com). Note: In Auth0 v4, this was renamed from AUTH0_ISSUER_BASE_URL and no longer accepts https://. |
| AUTH0_CLIENT_ID | Auth0 | Auth0 application client ID. |
| AUTH0_CLIENT_SECRET | Auth0 | Auth0 application client secret. |
Backend credentials (database, mail provider, GitHub token for template previews) now belong to the API, not to this app.
npm run dev # dev server
npm test # vitest
npm run test:coverage # vitest with the coverage thresholds enforced
npm run typecheck # tsc --noEmit (TypeScript 7)
npm run lint # biome check (lint + formatting + import order)
npm run format # biome check --write
npm run build # production buildapp/page.tsx is only a Suspense boundary; the page itself is
app/components/notifications-page-client.tsx.
This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.
To learn more about Next.js, take a look at the following resources:
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.
The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.
Check out our Next.js deployment documentation for more details.