@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,
  secret: process.env.NOTIFY_SECRET,
});

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. Set the internal API secret

NOTIFY_SECRET=change-me

POST is an internal mutation route and requires Authorization: Bearer $NOTIFY_SECRET. GET and PATCH stay callable by the widget; pair the route with your app's own user/session boundary so users can only read and update their own notifications.

5. 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',
});

6. 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}
        theme="dark"
        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, requires Bearer token)
PATCH	/api/notify/:id/read?userId=xxx	Mark notification as read for the widget user

NotificationBell Props

Prop	Default	Description
userId	—	User ID to fetch notifications for.
theme	'dark'	Visual theme. Pass 'light' to opt into the light theme.
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

NotificationBell defaults to the cyguin dark theme. 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);
}

The dark theme applies these overrides automatically:

.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,
  secret: process.env.NOTIFY_SECRET,
});

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

License

MIT