@sansavision/create-pulse

The official scaffolding tool for creating Pulse applications.

create-pulse generates a battle-tested, TypeScript-ready React application pre-configured to connect to a Pulse Relay. It eliminates the boilerplate of setting up WebSocket/WebTransport connections and provides robust React hooks.

Usage

You can create a new Pulse project interactively by running:

npm create pulse@latest
# or
npx @sansavision/create-pulse
# or
bunx @sansavision/create-pulse

You can optionally specify the project name directly:

npx @sansavision/create-pulse my-pulse-app

Available Templates

When you run create-pulse, you'll be prompted to select a template.

1. Next.js + Auth (Full Demo) ⭐

A full-featured demo application showcasing the full capabilities of Pulse.

• Better Auth with email/password, local SQLite + Drizzle ORM
• Webhook auth — Pulse relay verifies tokens via your Next.js API
• 5 comprehensive demos: Real-time Chat, Watch Together, Durable Queues (with offline simulation), Game State Sync, E2E Encrypted Chat
• Multi-user testing with separate browser tabs/incognito windows
• Built with Next.js 16, React 19, Tailwind CSS v4, TypeScript

2. Watch Together (React + TS)

A clean implementation of the "Watch Together" synchronized video player.

• Features a custom usePulse hook for lifecycle management.
• Handles syncing play, pause, and seek events across clients natively via the Pulse Relay.
• Built with React, Vite, Tailwind CSS, and TypeScript.

3. All Features (React + TS)

A kitchen-sink boilerplate that integrates multiple features.

• Perfect for exploring the SDK limits.
• Contains stubs and route setups for Chat, Metrics, and Video sync.
• Built with React, Vite, Tailwind CSS, and TypeScript.

4. Durable Queues (React + TS)

Demonstrates persistent message queues with publish/consume/ack workflows.

• Supports multiple storage backends (Memory, WAL, Postgres, Redis).
• Shows offline resilience and message recovery.
• Built with React, Vite, Tailwind CSS, and TypeScript.

5. Vanilla JS (Basic)

A minimal setup with zero frameworks.

• Raw WebSocket connection to the Pulse Relay.
• Good for understanding the protocol at a low level.

Running Your Scaffolded App

After your app is generated:

1. Navigate to the project directory:

   cd my-pulse-app

2. Install dependencies:

   npm install

3. Start the dev server:

   npm run dev

Note: The templates are configured by default to connect to a local Pulse Relay running at ws://localhost:4001. Start the server with pulse serve (or pulse dev for the full dev environment), or update your config to point to a production relay URL.

For the Next.js + Auth template, also start the relay with webhook auth:

npx @sansavision/pulse-cli serve --auth-mode webhook --auth-webhook http://localhost:3000/api/pulse/verify