Project setup

1. Copy the source/ directory into your project root, or merge source/src/ into your existing src/ tree. If merging, preserve the components/common/ subtree intact.

2. Merge tsconfig.json path aliases into your own tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. Copy tailwind.config.js and postcss.config.js, or merge the content globs and theme extensions into your existing Tailwind config.

4. Add the following environment variables to .env.local:

NEXT_PUBLIC_NHOST_SUBDOMAIN=your-project-subdomain
NEXT_PUBLIC_NHOST_REGION=eu-central-1
# Optional: for local CLI-linked development
NEXT_PUBLIC_NHOST_AUTH_URL=http://localhost:1337/v1/auth
NEXT_PUBLIC_NHOST_GRAPHQL_URL=http://localhost:1337/v1/graphql
NEXT_PUBLIC_NHOST_STORAGE_URL=http://localhost:1337/v1/storage
NEXT_PUBLIC_NHOST_FUNCTIONS_URL=http://localhost:1337/v1/functions

5. Wrap your _app.tsx (or layout.tsx) with the DialogProvider so all child components can open managed dialogs.

6. Import global styles in _app.tsx:

import '@/styles/globals.css';

7. Run codegen if you intend to use the GraphQL layer:

npx graphql-codegen --config graphql.config.yaml

Public API

DialogProvider

import { DialogProvider } from '@/components/common/DialogProvider';

function App({ children }: { children: React.ReactNode }) {
  return <DialogProvider>{children}</DialogProvider>;
}

Wraps your component tree and provides a React context that lets any descendant open, close, or update a shared modal dialog. Use it once at the application root.

useDialog

import { useDialog } from '@/components/common/DialogProvider';

const { openDialog, closeDialog } = useDialog();

Returns imperative controls for the dialog system registered by DialogProvider. Use openDialog to push a new dialog onto the stack from anywhere in the component tree without prop-drilling.

DateTimePicker

import { DateTimePicker } from '@/components/common/DateTimePicker';

<DateTimePicker
  value={date}
  onChange={(d) => setDate(d)}
/>

A controlled date-and-time input component. Use it wherever you need a combined date + time selection, such as scheduling jobs, setting expiry timestamps, or filtering log ranges.

DiscardChangesDialog

import { DiscardChangesDialog } from '@/components/common/DiscardChangesDialog';

<DiscardChangesDialog open={open} onClose={() => setOpen(false)} />

A confirmation dialog that warns the user they have unsaved changes. Use it in forms with dirty state before navigating away or resetting fields.

CookieConsent

import { CookieConsent } from '@/components/common/CookieConsent';

<CookieConsent />

A self-contained cookie consent banner. Mount it once in the layout; it persists user preference to local storage and suppresses itself after acceptance.

ApplyLocalSettingsDialog

import { ApplyLocalSettingsDialog } from '@/components/common/ApplyLocalSettingsDialog';

<ApplyLocalSettingsDialog />

A dialog that lets developers apply local CLI-overridden service URLs at runtime. Use it in development or staging builds where the Nhost CLI is running locally.

Working examples

Scenario - Wrapping your Next.js app with dialog infrastructure

Add DialogProvider to pages/_app.tsx so every page can trigger managed modals without prop drilling.

import type { AppProps } from 'next/app';
import { DialogProvider } from '@/components/common/DialogProvider';
import { CookieConsent } from '@/components/common/CookieConsent';
import '@/styles/globals.css';

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <DialogProvider>
      <Component {...pageProps} />
      <CookieConsent />
    </DialogProvider>
  );
}

Scenario - Opening a discard-changes confirmation from a form

Use useDialog to imperatively open DiscardChangesDialog when a user tries to navigate away from a dirty form.

import { useDialog } from '@/components/common/DialogProvider';
import { DiscardChangesDialog } from '@/components/common/DiscardChangesDialog';
import { useState } from 'react';

export function SettingsForm() {
  const { openDialog, closeDialog } = useDialog();
  const [dirty, setDirty] = useState(false);

  function handleCancel() {
    if (!dirty) return;
    openDialog({
      component: (
        <DiscardChangesDialog
          open
          onClose={closeDialog}
        />
      ),
    });
  }

  return (
    <form onChange={() => setDirty(true)}>
      <input name="displayName" placeholder="Display name" />
      <button type="button" onClick={handleCancel}>
        Cancel
      </button>
      <button type="submit">Save</button>
    </form>
  );
}

Scenario - Scheduling with DateTimePicker

Render a DateTimePicker inside a form to let the user choose an expiry date for an access token or scheduled task.

import { useState } from 'react';
import { DateTimePicker } from '@/components/common/DateTimePicker';

export function ScheduleJobForm() {
  const [runAt, setRunAt] = useState<Date | null>(null);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!runAt) return;
    await fetch('/api/jobs', {
      method: 'POST',
      body: JSON.stringify({ runAt: runAt.toISOString() }),
      headers: { 'Content-Type': 'application/json' },
    });
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="runAt">Run at</label>
      <DateTimePicker value={runAt} onChange={setRunAt} />
      <button type="submit" disabled={!runAt}>
        Schedule
      </button>
    </form>
  );
}

Scenario - Local development settings override

Render ApplyLocalSettingsDialog in a dev-only layout so engineers running nhost dev can point the dashboard at their local stack.

import { ApplyLocalSettingsDialog } from '@/components/common/ApplyLocalSettingsDialog';

export function DevToolbar() {
  if (process.env.NODE_ENV !== 'development') return null;
  return (
    <div style={{ position: 'fixed', bottom: 16, right: 16 }}>
      <ApplyLocalSettingsDialog />
    </div>
  );
}

File walkthrough

• src/ - Root of all application code: pages (Next.js routing), components, hooks, utilities, GraphQL operations, and type definitions.
• src/components/common/ - Shared UI primitives reused across the entire dashboard (dialogs, pickers, consent, providers).
• src/components/common/DialogProvider/ - Context + provider + hook for the imperative dialog system.
• src/components/common/DateTimePicker/ - Controlled date-time input component.
• src/components/common/DiscardChangesDialog/ - Confirmation modal for unsaved-changes guard.
• src/components/common/CookieConsent/ - Cookie consent banner with local-storage persistence.
• src/components/common/ApplyLocalSettingsDialog/ - Dev-mode dialog for applying local Nhost CLI service URLs.
• public/ - All static files served at /: icons, logos, brand assets, framework images, and the MSW service worker.
• next.config.js - Next.js compiler options, image domains, and environment variable exposure.
• tailwind.config.js - Design tokens, custom colors, and the content glob for purging unused CSS.
• tsconfig.json - Compiler settings and @/* path alias pointing to src/.
• biome.json - Linting and formatting rules (replaces ESLint + Prettier).
• graphql.config.yaml - Schema pointers and codegen output paths.
• playwright.config.ts - Browser test runner config (base URL, retries, projects).
• vitest.global-setup.ts - Global before-all setup for unit tests (MSW, environment seeds).

Common pitfalls and fixes

• @/* imports resolve to undefined at runtime - Ensure baseUrl is . (project root) and paths maps @/* to ./src/* in both tsconfig.json and next.config.js (use experimental.externalDir if the source lives outside the Next.js root).
• Tailwind classes not applied - Add ./src/**/*.{ts,tsx} to the content array in tailwind.config.js; missing globs cause PurgeCSS to strip all classes in production.
• GraphQL codegen fails with schema fetch errors - The codegen config expects the Hasura endpoint to be live; set HASURA_GRAPHQL_ENDPOINT and HASURA_GRAPHQL_ADMIN_SECRET in .env.local before running codegen, or point the config at a local schema file.
• DialogProvider context is undefined - useDialog throws if called outside DialogProvider. Ensure DialogProvider wraps the component at the _app / root layout level, not inside a single page.
• MSW service worker not found in tests - The mockServiceWorker.js must be served from public/; if you restructure the public directory, update the MSW serviceWorker.register path accordingly.
• DateTimePicker produces invalid dates across locales - The component uses date-fns locale defaults; pass an explicit locale prop matching the user's locale to avoid dd/mm vs mm/dd ambiguity.

Vibe-coding prompt template

I have dropped the Nhost Dashboard source block into `source/` in my project.
The integration guide is in `source/USAGE.md`.
The upstream package is `user@example.com` (repo: nhost/nhost, dashboard workspace).

Please help me integrate this into my existing Next.js + TypeScript project step by step:

1. Read `source/USAGE.md` fully before making any changes.
2. Merge the TypeScript path aliases from `source/tsconfig.json` into my `tsconfig.json`.
3. Copy `source/src/components/common/` into `src/components/common/`.
4. Wrap my `pages/_app.tsx` (or `app/layout.tsx`) with `DialogProvider` from
   `@/components/common/DialogProvider` and mount `CookieConsent` from
   `@/components/common/CookieConsent`.
5. Add a `DateTimePicker` to my existing scheduler form, importing from
   `@/components/common/DateTimePicker`.
6. Add a discard-changes guard to my settings form using `useDialog` and
   `DiscardChangesDialog` from `@/components/common/DialogProvider` and
   `@/components/common/DiscardChangesDialog`.
7. Only use exports that are actually listed in `source/USAGE.md` - do not
   invent component names or props.
8. Show me the full diff for each changed file.

License and credit

The Nhost Dashboard source is part of the nhost/nhost monorepo, published under the MIT License (see source/LICENSE if present, or the repository root LICENSE file). Upstream package: user@example.com. Refer to the Nhost documentation for platform usage terms.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.