@cyguin/notify

Server-triggered in-app notifications for Next.js apps.

Install

npm install @cyguin/notify

Setup

1. Create the API route

Create app/api/notify/[...cyguin]/route.ts in your Next.js app:

import { createNotifyHandler } from '@cyguin/notify/next';
import Database from 'better-sqlite3';
import { createSQLiteAdapter } from '@cyguin/notify/adapters/sqlite';

const db = new Database('notify.db');
db.pragma('journal_mode = WAL');
const adapter = createSQLiteAdapter(db);

const handler = createNotifyHandler({ adapter });

export { handler as GET, handler as POST, handler as PATCH };

2. Run migrations

CREATE TABLE notifications (
  id          TEXT PRIMARY KEY,
  user_id     TEXT NOT NULL,
  title       TEXT NOT NULL,
  body        TEXT NOT NULL,
  href        TEXT,
  read_at     INTEGER,
  created_at  INTEGER NOT NULL
);

3. Configure the adapter at startup

In your app startup (e.g., a setup file or server entry):

import { setNotificationAdapter } from '@cyguin/notify';
import { createSQLiteAdapter } from '@cyguin/notify/adapters/sqlite';

const adapter = createSQLiteAdapter(db);
setNotificationAdapter(adapter);

4. Trigger notifications from your server code

import { notify } from '@cyguin/notify';

// In a server action, API route, or background job:
await notify(userId, {
  title: 'Export ready',
  body: 'Your data export is ready to download.',
  href: '/exports/123',
});

5. Add the notification bell

import { NotificationBell } from '@cyguin/notify/react';

export default function Header({ user }: { user: { id: string } }) {
  return (
    <header>
      <nav>...</nav>
      <NotificationBell
        userId={user.id}
        pollInterval={30000}
        maxVisible={10}
        onToggle={(open) => console.log('Dropdown:', open)}
      />
    </header>
  );
}

API Routes

| Method | Route | Description | |--------|-------|-------------| | GET | /api/notify?userId=xxx&limit=N | List notifications for user | | POST | /api/notify | Create notification (internal) | | PATCH | /api/notify/:id/read?userId=xxx | Mark notification as read |

NotificationBell Props

| Prop | Default | Description | |------|---------|-------------| | userId | — | User ID to fetch notifications for. | | pollInterval | 30000 | Polling interval in ms. Pass 0 to disable. | | maxVisible | 10 | Max notifications to show in dropdown. | | className | '' | CSS class for the root element. | | onToggle | — | Callback when dropdown opens/closes. |

Theming

Use --cyguin-* CSS custom properties on .cyguin-notify-bell:

.cyguin-notify-bell {
  --cyguin-bg: #ffffff;
  --cyguin-fg: #0a0a0a;
  --cyguin-accent: #f5a800;
  --cyguin-border: #e5e5e5;
  --cyguin-radius: 6px;
  --cyguin-shadow: 0 1px 4px rgba(0,0,0,0.08);
}

Switch to dark theme with the theme prop on the inner button element via CSS:

.cyguin-notify-bell[data-theme="dark"] {
  --cyguin-bg: #0a0a0a;
  --cyguin-bg-subtle: #1a1a1a;
  --cyguin-border: #2a2a2a;
  --cyguin-fg: #f5f5f5;
  --cyguin-shadow: 0 1px 4px rgba(0,0,0,0.4);
}

Postgres Setup

import { createNotifyHandler } from '@cyguin/notify/next';
import postgres from 'postgres';
import { createPostgresAdapter } from '@cyguin/notify/adapters/postgres';

const sql = postgres(process.env.DATABASE_URL!);
const adapter = createPostgresAdapter(sql);

const handler = createNotifyHandler({ adapter });

export { handler as GET, handler as POST, handler as PATCH };

License

MIT