@cyguin/announce

DB-backed, per-user dismissible announcement banners for Next.js. Create announcements from an admin API, users see them once and dismiss them.

Install

npm install @cyguin/announce

Setup

1. Create the API route

app/api/announce/[...cyguin]/route.ts:

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

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

const handler = createAnnounceHandler({
  adapter,
  options: {
    secret: process.env.ANNOUNCE_SECRET,
  },
});

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

2. Run migrations

CREATE TABLE IF NOT EXISTS announcements (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  body TEXT NOT NULL,
  active_from INTEGER,
  active_until INTEGER,
  created_at INTEGER NOT NULL
);

CREATE TABLE IF NOT EXISTS announcement_dismissals (
  user_id TEXT NOT NULL,
  announcement_id TEXT NOT NULL,
  dismissed_at INTEGER NOT NULL,
  PRIMARY KEY (user_id, announcement_id)
);

3. Set the admin API secret

ANNOUNCE_SECRET=change-me

Creating and deleting announcements needs Authorization: Bearer $ANNOUNCE_SECRET. Listing and dismissing is public — the widget handles that.

4. Add the banner

import { AnnouncementBanner } from '@cyguin/announce/react';

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <AnnouncementBanner
        apiBase="/api/announce"
        userId={currentUser.id}
        theme="dark"
      />
      {children}
    </>
  );
}

Postgres Setup

import { createAnnounceHandler } from '@cyguin/announce/next';
import postgres from 'postgres';
import { createPostgresAdapter } from '@cyguin/announce/adapters/postgres';

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

const handler = createAnnounceHandler({
  adapter,
  options: {
    secret: process.env.ANNOUNCE_SECRET,
  },
});

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

API Routes

| Method | Route | Description | |--------|-------|-------------| | GET | /api/announce/cyguin?userId=xxx | List active announcements for user | | POST | /api/announce/cyguin | Create announcement (Bearer token required) | | DELETE | /api/announce/cyguin/:id | Delete announcement (Bearer token required) | | POST | /api/announce/cyguin/:id/dismiss?userId=xxx | Dismiss for user |

Theming

The banner is dark by default. Pass theme="light" to switch. Customize --cyguin-* variables on .cyguin-announce-banner:

.cyguin-announce-banner {
  --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);
}

Dark mode auto-applies these:

--cyguin-bg: #0a0a0a;
--cyguin-bg-subtle: #1a1a1a;
--cyguin-border: #2a2a2a;
--cyguin-fg: #f5f5f5;
--cyguin-shadow: 0 1px 4px rgba(0,0,0,0.4);

Configuration

createAnnounceHandler({
  adapter,
  options: {
    defaultActiveDays: 7,  // auto-expire after N days
    maxActive: 3,          // max simultaneous active announcements
    secret: process.env.ANNOUNCE_SECRET,
  },
})

License

MIT