https://github.com/draphy/pushforge
A modern, cross-platform Web Push Notification library with full VAPID support. Handles payload encryption, authentication, and delivery across Node.js, Browsers, Deno, Bun, and Cloudflare Workers. Zero dependencies, TypeScript-first, and built for modern web applications.
https://github.com/draphy/pushforge
browser bun cloudflare cross-platform deno ecdh hkdf nodejs typescript vapid web webpush webpush-notifications
Last synced: 3 days ago
JSON representation
A modern, cross-platform Web Push Notification library with full VAPID support. Handles payload encryption, authentication, and delivery across Node.js, Browsers, Deno, Bun, and Cloudflare Workers. Zero dependencies, TypeScript-first, and built for modern web applications.
- Host: GitHub
- URL: https://github.com/draphy/pushforge
- Owner: draphy
- License: mit
- Created: 2025-04-17T10:58:02.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2025-04-29T00:05:13.000Z (12 months ago)
- Last Synced: 2025-04-29T01:25:16.200Z (12 months ago)
- Topics: browser, bun, cloudflare, cross-platform, deno, ecdh, hkdf, nodejs, typescript, vapid, web, webpush, webpush-notifications
- Language: TypeScript
- Homepage: https://www.npmjs.com/org/pushforge
- Size: 1.07 MB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PushForge
**Web Push Notifications for the Modern Stack**
[](https://www.npmjs.com/package/@pushforge/builder)
[](https://www.npmjs.com/package/@pushforge/builder)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
Zero dependencies · Works everywhere · TypeScript-first
[Documentation](packages/builder) · [npm](https://www.npmjs.com/package/@pushforge/builder) · [Report Bug](https://github.com/draphy/pushforge/issues)
**[Try the Live Demo →](https://pushforge.draphy.org)**
---
## Live Demo
See PushForge in action at **[pushforge.draphy.org](https://pushforge.draphy.org)** — a fully working test site powered by PushForge on Cloudflare Workers.
- **Enable push notifications** on your device with a single toggle
- **Send a test notification** to all active devices — anyone visiting the page can send and receive
- **See it working across browsers** — Chrome, Firefox, Edge, Safari 16+, and more
- Subscriptions auto-expire after 5 minutes — no permanent data stored
The entire backend is a single Cloudflare Worker using `buildPushHTTPRequest()` from `@pushforge/builder` with zero additional dependencies.
## The Problem
Traditional web push libraries like `web-push` rely on Node.js-specific APIs that don't work in modern edge runtimes:
```
❌ Cloudflare Workers - "crypto.createECDH is not a function"
❌ Vercel Edge - "https.request is not available"
```
## The Solution
PushForge uses standard Web APIs that work everywhere:
```typescript
import { buildPushHTTPRequest } from "@pushforge/builder";
const { endpoint, headers, body } = await buildPushHTTPRequest({
privateJWK: VAPID_PRIVATE_KEY,
subscription: userSubscription,
message: {
payload: { title: "Hello!", body: "This works everywhere." },
adminContact: "mailto:admin@example.com"
}
});
await fetch(endpoint, { method: "POST", headers, body });
```
## Why PushForge?
| | PushForge | web-push |
|---|:---:|:---:|
| Dependencies | **0** | 5+ |
| Cloudflare Workers | ✅ | [❌](https://github.com/web-push-libs/web-push/issues/718) |
| Vercel Edge | ✅ | ❌ |
| Convex | ✅* | ❌ |
| Deno / Bun | ✅ | Limited |
| TypeScript | Native | @types |
\* Requires `"use node";` directive — [see example](packages/builder#convex)
## Quick Start
```bash
# Install
npm install @pushforge/builder
# Generate VAPID keys
npx @pushforge/builder vapid
```
**Frontend** - Subscribe users:
```javascript
const subscription = await registration.pushManager.subscribe({
userVisibleOnly: true,
applicationServerKey: VAPID_PUBLIC_KEY
});
// Send subscription.toJSON() to your server
```
**Backend** - Send notifications:
```typescript
import { buildPushHTTPRequest } from "@pushforge/builder";
const { endpoint, headers, body } = await buildPushHTTPRequest({
privateJWK: process.env.VAPID_PRIVATE_KEY,
subscription,
message: {
payload: { title: "New Message", body: "You have a notification!" },
adminContact: "mailto:admin@example.com"
}
});
await fetch(endpoint, { method: "POST", headers, body });
```
See the [full documentation](packages/builder) for platform-specific examples (Cloudflare Workers, Vercel Edge, Convex, Deno, Bun).
## Packages
| Package | Description |
|---------|-------------|
| [@pushforge/builder](packages/builder) | Core library for building push notification requests |
## Requirements
- **Node.js 20+** or any runtime with Web Crypto API
- Supported: Cloudflare Workers, Vercel Edge, Convex, Deno, Bun, modern browsers
## Development
```bash
git clone https://github.com/draphy/pushforge.git
cd pushforge
pnpm install
pnpm build
```
## Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
MIT © [David Raphi](https://github.com/draphy)