Alpha

This feature is in alpha. APIs and behavior may change without notice. Not recommended for production use.

Push Notifications

EdgeBase Push manages the complete push token lifecycle on the backend — the part every team rebuilds from scratch. Device tokens are mapped to user IDs with multi-device routing (up to 10 devices per user), automatic token refresh, deduplication, and cleanup of invalid tokens. Add topic-based subscriptions and broadcast messaging on top. Just call send() with a user ID and payload — EdgeBase resolves all devices and delivers through FCM.

Admin SDK Coverage

Server-side push sending, logs, topic operations, and broadcast are available across all Admin SDKs.

Control Surface

Access Rules: Push Access Rules gate which backend callers can send notifications.
Hooks: Push Hooks let you rewrite outbound sends or observe delivery results.
Triggers: Push is not a trigger-based surface.
Handlers: Inline push behavior lives under push.handlers.hooks in edgebase.config.ts.

Architecture

EdgeBase uses Firebase Cloud Messaging (FCM) as the single delivery provider for all platforms. Your client apps use the Firebase SDK to obtain FCM registration tokens, which are then stored and managed by EdgeBase.

Push Flow

┌─────────────┐     FCM Token     ┌──────────────┐    FCM HTTP v1    ┌─────┐
│  Client App  │ ──────────────→  │ EdgeBase      │ ──────────────→  │ FCM │ → Device
│ (Firebase SDK)│                  │ Server (KV)   │                  │     │
└─────────────┘                   └──────────────┘                   └─────┘

How it works:

Token Acquisition — Your client app uses the Firebase SDK to get an FCM registration token.
Token Registration — The client SDK sends this token to your EdgeBase server. When AUTH_DB is available, tokens are written to the _push_devices table in D1 as the primary source of truth, with KV acting as a mirrored cache for fast edge reads. If AUTH_DB is not configured, KV is the sole store.
Sending — Your backend calls admin.push.send(userId, payload). EdgeBase looks up all devices and sends through FCM.
Lifecycle — EdgeBase handles token refresh, deduplication, and automatic cleanup of invalid tokens.

Push vs Database Subscriptions and Room

Push is not a WebSocket channel. Database Subscriptions and Room target clients with an active live connection. Push targets registered devices through FCM and is meant for alerts that should arrive even when the app is backgrounded or not currently connected.

For the full comparison, see Choosing Live Features.

Key Features

📱

Multi-Device Management

Up to 10 devices per user. All devices receive notifications. Stale tokens are cleaned up when FCM returns 404/410/UNREGISTERED during a send attempt.

📌

Topic Messaging

Subscribe devices to topics (news, sports) and send to all subscribers at once.

📢

Broadcast

Send to every registered device. All tokens auto-subscribe to the 'all' topic.

🔒

Access Rules

Control which backend callers can send notifications through the server surface

🪝

Push Hooks

Rewrite outbound sends or observe delivery results before and after the provider call

📋

Push Logs

24-hour send logs with status (sent, failed, removed) and error details for debugging.

💾

Token Caching

Client SDKs cache tokens locally. Server requests only fire when the token actually changes.

🚪

Auto-Unregister

On sign out, the SDK automatically unregisters the device token before clearing the session.

What You Don't Have to Build

Push notification delivery (FCM/APNs) is well-documented. The hard part is everything around it — the backend infrastructure that maps users to tokens across devices, handles token churn, and cleans up stale registrations. This is what EdgeBase manages for you:

Without EdgeBase	With EdgeBase
Build a `user_tokens` table, handle schema migrations	`client.push.registerToken()` — stored in KV automatically
Write token refresh logic (FCM tokens expire/rotate)	Automatic — SDK detects changes and re-registers
Handle multi-device (user signs in on phone + tablet)	Built-in — up to 10 devices per user, all receive notifications
Detect and remove invalid tokens (uninstalled apps)	Automatic — invalid tokens are cleaned up on failed sends
Deduplicate tokens (same device, multiple sign-ins)	Automatic — `deviceId`-based deduplication
Build topic subscription management	`client.push.subscribeTopic('news')` — one line
Build send-to-user API (resolve userId → all device tokens)	`admin.push.send(userId, payload)` — resolves all devices
Set up logging for delivery debugging	Built-in 24h push logs with status and error details

This is typically 200–500 lines of backend code that every team writes from scratch. EdgeBase eliminates it entirely.

Token Storage

Push tokens use a dual-write strategy when AUTH_DB is available:

D1 (AUTH_DB._push_devices) — The primary source of truth. Token registrations, updates, and deletions are written here first.
Cloudflare KV — A mirrored cache for fast edge-cached reads at send time. KV is updated after every D1 write.

If AUTH_DB is not configured, KV acts as the sole store.

This dual-write design provides:

Durability — D1 is the authoritative store; KV can be rebuilt from it.
Edge-cached reads — Token lookups are fast at send time via KV.
No backup contamination — Invalid tokens in KV don't get restored during database backups.

KV key patterns: