# Datastar TypeScript SDK
[](https://github.com/starfederation/datastar-typescript/releases) [](https://www.npmjs.com/package/@starfederation/datastar-sdk)
[](https://nodejs.org/) [](https://deno.land/) [](https://bun.sh/)
A TypeScript SDK for building reactive web applications with [Datastar](https://github.com/starfederation/datastar).
Implements the [SDK spec](https://github.com/starfederation/datastar/blob/develop/sdk/README.md) and exposes an abstract ServerSentEventGenerator class that can be used to implement runtime specific classes. NodeJS and web standard runtimes are currently implemented.
Currently it only exposes an http1 server, if you want http2 I recommend you use a reverse proxy until http2 support is added.
## Features
- **Multi-runtime support**: Works with Node.js, Deno, and Bun
- **TypeScript support**: Full type safety and IntelliSense
## Quick Start
### Installation & Import
**Node.js:**
```bash
npm install @starfederation/datastar-sdk
```
```javascript
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";
```
**Deno:**
```typescript
// No installation needed, import directly from npm
import { ServerSentEventGenerator } from "npm:@starfederation/datastar-sdk/web";
```
**Bun:**
```bash
bun add @starfederation/datastar-sdk
```
```javascript
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/web";
```
### Basic Usage
Here's a simple example in Node showing how to read client signals and send back element patches:
```javascript
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";
// Read signals from the client request
const reader = await ServerSentEventGenerator.readSignals(req);
if (!reader.success) {
console.error('Error reading signals:', reader.error);
return;
}
// Stream updates back to the client
ServerSentEventGenerator.stream(req, res, (stream) => {
// Patch signals
stream.patchSignals(JSON.stringify({ foo: reader.signals.foo }));
// Patch DOM elements
stream.patchElements(`Hello ${reader.signals.foo}
`);
});
```
See examples for other runtimes below.
## Examples
### Runtime-Specific Examples
| Runtime | Example Location | How to Run | Try Online |
|---------|-----------------|------------|------------|
| **Node.js** | `examples/node/node.js` | [Instructions](examples/node/README.md) | [StackBlitz](https://stackblitz.com/edit/node-datastar) |
| **Deno** | `examples/deno/deno.ts` | [Instructions](examples/deno/README.md) | [Val.town](https://www.val.town/x/eduwass/datastar-deno/code/main.tsx) |
| **Bun** | `examples/bun/bun.ts` | [Instructions](examples/bun/README.md) | [Replit](https://replit.com/@eduwass/Bun-Datastar) |
Each example creates a simple web server demonstrating:
- Signal handling from client requests
- Element patching for DOM updates
- Real-time communication via Server-Sent Events
### Running Examples
1. Clone the repository
2. Navigate to the specific example directory (e.g., `examples/node/`)
3. Follow the instructions in the example's README file
4. Visit `http://localhost:3000` in your browser
> [!NOTE]
> The `npm run serve-*` and `deno task serve-*` commands in the root directory are for SDK development and testing, not for running the user examples.
## API Reference
### ServerSentEventGenerator
The main class for handling Datastar communication.
#### Static Methods
##### `readSignals(request)`
Reads signals from a client request.
**Parameters:**
- `request`: HTTP request object
**Returns:**
```typescript
{
success: boolean;
signals?: Record;
error?: string;
}
```
##### `stream(request, response, callback, options?)`
Creates a Server-Sent Event stream for real-time communication.
**Parameters:**
- `request`: HTTP request object
- `response`: HTTP response object
- `callback`: Function that receives a stream instance
- `options`: Optional configuration object
**Options:**
```typescript
{
onError?: (error: Error) => void;
onAbort?: () => void;
keepalive?: boolean;
}
```
> [!IMPORTANT]
> When `keepalive: true` is set, the stream will not be closed automatically after the callback finishes. You are responsible for calling `stream.close()` to end the stream.
#### Stream Instance Methods
##### `patchSignals(signals, options?)`
Patches signals into the client signal store.
**Parameters:**
- `signals`: JSON string containing signal data to patch
- `options`: Optional configuration object with `onlyIfMissing` boolean
**Example:**
```javascript
stream.patchSignals(JSON.stringify({ foo: "bar", count: 42 }));
```
##### `patchElements(elements, options?)`
Patches HTML elements into the client DOM.
**Parameters:**
- `elements`: HTML string containing elements to patch
- `options`: Optional configuration object with `mode` and `selector`
**Options:**
- `mode`: Patch mode - "outer", "inner", "replace", "prepend", "append", "before", "after", "remove"
- `selector`: CSS selector for targeting elements (required for some modes)
- `useViewTransition`: Whether to use View Transition API
**Example:**
```javascript
stream.patchElements('Updated content
');
```
##### `removeElements(selector?, elements?, options?)`
Removes elements from the client DOM by selector or by HTML string with IDs.
**Parameters:**
- `selector`: CSS selector for elements to remove (optional; mutually exclusive with elements)
- `elements`: HTML string of elements with IDs to remove (optional; required if selector is not provided)
- `options`: Optional configuration object with `eventId`, `retryDuration`
**Examples:**
```javascript
// Remove by selector
stream.removeElements('#feed, #otherid');
// Remove by HTML elements with IDs
stream.removeElements(undefined, '');
```
##### `removeSignals(signalKeys, options?)`
Removes one or more signals from the client signal store.
**Parameters:**
- `signalKeys`: The signal key or array of keys to remove
- `options`: Optional configuration object with `onlyIfMissing`, `eventId`, `retryDuration`
**Examples:**
```javascript
// Remove a single signal
stream.removeSignals('foo');
// Remove multiple signals
stream.removeSignals(['foo', 'bar']);
```
##### `executeScript(script, options?)`
Executes a script on the client by sending a