# Technical Documentation: starfederation/datastar

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/starfederation/datastar)

### Overview (`README.md`)

[](https://github.com/starfederation/datastar/releases)
[](https://github.com/starfederation/datastar/blob/main/LICENSE.md)
[](https://github.com/starfederation/datastar/stargazers)

<p align="center"><img width="150" height="150" src="https://data-star.dev/static/images/rocket-512x512.png"></p>

# Datastar

### The hypermedia framework.

Datastar is a lightweight framework for building everything from simple sites to real-time collaborative web applications.

Getting started is as easy as adding a single 11.89 KiB script tag to your HTML.

```html
<script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.4/bundles/datastar.js"></script>
```

Then start adding frontend reactivity using declarative <code>data-*</code> attributes.

```html
<input data-bind:title />
<div data-text="$title.toUpperCase()"></div>
<button data-on:click="@post('/endpoint')">Save</button>
```

Visit the [Datastar Website »](https://data-star.dev/)

Watch the [Videos »](https://data-star.dev/videos)

Join the [Discord Server »](https://discord.gg/bnRNgZjgPh)

## Getting Started

Read the [Getting Started Guide »](https://data-star.dev/guide/getting_started)

## Contributing

Read the [Contribution Guidelines »](https://github.com/starfederation/datastar/blob/develop/CONTRIBUTING.md)

[](https://www.star-history.com/#starfederation/datastar&Date)

---

### Overview (`sdk/README.md`)

# Datastar SDK Directory

This directory contains the SDK test suite and related tools for Datastar SDK development.

## Structure

- `tests/` - Comprehensive test suite for validating SDK implementations
- `datastar-sdk-config.json` - SDK configuration with constants and defaults
- `datastar-sdk-config.schema.json-v1.json` - JSON schema for configuration validation
- `ADR.md` - Architecture Decision Record for SDK specifications

## SDK Development

### Configuration

The SDK configuration system provides:

- **Constants**: Event types, element patch modes, and other enums
- **Defaults**: Default values for booleans and durations
- **Literals**: List of known dataline literals
- **JSON Schema**: Validation for the configuration format

### Creating a New SDK

1. Read the [Architecture Decision Record](./ADR.md) for SDK specifications
2. Use [`datastar-sdk-config.json`](./datastar-sdk-config.json) as your source of constants
3. Implement the required `ServerSentEventGenerator` interface
4. Validate your implementation using the [test suite](./tests/README.md)

## Official SDKs

Official SDKs can be found at the [Datastar website](https://data-star.dev/reference/sdks).

## Support

For SDK-specific issues, please open an issue in the respective SDK repository. For general Datastar questions or cross-SDK concerns, use the main [Datastar repository](https://github.com/starfederation/datastar).

---

### Overview (`sdk/clojure/README.md`)

# Datastar Clojure SDK

The Datastar Clojure SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-clojure](https://github.com/starfederation/datastar-clojure).

---

### Overview (`sdk/dotnet/README.md`)

# Datastar C# (.NET) SDK

The Datastar C# (.NET) SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-dotnet](https://github.com/starfederation/datastar-dotnet).

---

### Overview (`sdk/go/README.md`)

# Datastar Go SDK

The Datastar Go SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-go](https://github.com/starfederation/datastar-go).

---

### Overview (`sdk/haskell/README.md`)

# Datastar Haskell SDK

The Datastar Haskell SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-haskell](https://github.com/starfederation/datastar-haskell).

---

### Overview (`sdk/java/README.md`)

# Datastar Java SDK

The Datastar Java SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-java](https://github.com/starfederation/datastar-java).

---

### Overview (`sdk/php/README.md`)

# Datastar PHP SDK

The Datastar PHP SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-php](https://github.com/starfederation/datastar-php).

---

### Overview (`sdk/python/README.md`)

# Datastar Python SDK

The Datastar Python SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-python](https://github.com/starfederation/datastar-python).

---

### Overview (`sdk/ruby/README.md`)

# Datastar Ruby SDK

The Datastar Ruby SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-ruby](https://github.com/starfederation/datastar-ruby).

---

### Overview (`sdk/rust/README.md`)

# Datastar Rust SDK

The Datastar Rust SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-rust](https://github.com/starfederation/datastar-rust).

---

### Overview (`sdk/test/README.md`)

# Datastar SDK testing suite

This test suite uses curl(1), cat(1), sh(1), and awk(1) to test that a server respects the SDK spec found in `../README.md`.

It expects a server to expose a `/test` endpoint that accepts all HTTP methods. The server should then use ReadSignals
to extract the `events` array. It must then loop through the array of events and use `event.type` to decide which server sent event to use. If the output of the server differs from the expected output, then an error will be printed to the terminal.

## Usage

```
$ ./test-all.sh $server_address
Running tests with argument: $server_address
Processing GET cases...
Processing POST cases...
```

If nothing else is output then all tests passed!

Results of the test can be found in `./get_cases/$case_name/testOutput.txt` (or `post_cases` depending on the test).

## Adding new cases

To add a new test case, simply add a folder named after the test in either `./get-cases` or `./post-cases`.

That folder must contain an `input.json` file and an `output.txt` file.

The `input.json` file must contain valid json of the following shape:

```
{"events":
  [
    { "type": "executeScript",
      "script": "console.log('hello');",
      "eventId": 1,
      "retryDuration": 2000,
      "attributes": {
        "type": "text/javascript",
        "blocking": false
      },
      "autoRemove": false
     }
   ]
}
```

The `output.txt` file must contain valid a `text/eventstream` like such:

```
event: datastar-patch-elements
id: 1
retry: 2000
elements: <script type="text/javascript" blocking="false">console.log('hello')</script>;
```

### Special case for multiline signals

For the event type `patchSignals` the `input.json` contains the `signals` as JSON-object which should be converted to a single signals line in the `output.txt`. 

If you want to output multi-line signals, then the input must contain `signals-raw` as String with `\n` in them instead. This is due to the fact that Json parsers would otherwise interpret the input file without the line breaks.

So the implementation of the server has to interpret `signals-raw` as String first, and if not present `signals` as JSON-object.

---

### Overview (`sdk/tests/README.md`)

# Datastar SDK Test Suite

A comprehensive test suite for validating Datastar SDK implementations across different languages.

## Installation

### As a Go Library

```bash
go get github.com/starfederation/datastar/sdk/tests
```

## Usage

### Running Tests

```bash
# Run all tests against default server (localhost:7331)
go run github.com/starfederation/datastar/sdk/tests/cmd/datastar-sdk-tests@latest

# Run with custom server
go run github.com/starfederation/datastar/sdk/tests/cmd/datastar-sdk-tests@latest -server http://localhost:8080

# Run only GET tests
go run github.com/starfederation/datastar/sdk/tests/cmd/datastar-sdk-tests@latest -type get

# Run only POST tests  
go run github.com/starfederation/datastar/sdk/tests/cmd/datastar-sdk-tests@latest -type post

# Verbose output
go run github.com/starfederation/datastar/sdk/tests/cmd/datastar-sdk-tests@latest -v
```

### Using go test directly

```bash
# Clone the repository and navigate to tests directory
cd sdk/tests

# Run all tests
go test -v

# Run with custom server
TEST_SERVER_URL=http://localhost:8080 go test -v
```

## Test Structure

The test suite includes:

- **GET Tests** (`golden/get/`): Test cases for GET endpoints
- **POST Tests** (`golden/post/`): Test cases for POST endpoints

Each test case contains:
- `input.json`: The request payload
- `output.txt`: The expected SSE response

## Features

- **HTML Normalization**: Automatically handles HTML attribute ordering differences
- **Embedded Test Data**: All test cases are embedded in the binary for portability
- **Flexible Runner**: Can be used as a CLI tool or Go library
- **Detailed Output**: Clear error messages and debug information

## For SDK Implementers

To validate your SDK implementation:

1. Start your test server on port 7331 (or specify a different port)
2. Implement the `/test` endpoint that:
   - For GET: reads the `datastar` query parameter
   - For POST: reads the JSON body
   - Returns appropriate SSE responses
3. Run `go run github.com/starfederation/datastar/sdk/tests/cmd/datastar-sdk-tests@latest` to validate your implementation

## Test Endpoint Requirements

The `/test` endpoint should:

1. Use ReadSignals to extract the `events` array from the request
2. Loop through the array of events 
3. Use `event.type` to decide which server sent event to generate
4. Return the appropriate SSE response

### Input Format

```json
{
  "events": [
    {
      "type": "executeScript",
      "script": "console.log('hello');",
      "eventId": "event1",
      "retryDuration": 2000,
      "attributes": {
        "type": "text/javascript",
        "blocking": "false"
      },
      "autoRemove": false
    }
  ]
}
```

### Output Format

```
event: datastar-patch-elements
id: event1
retry: 2000
data: mode append
data: selector body
data: elements <script type="text/javascript" blocking="false">console.log('hello');</script>

```

## Adding New Test Cases

To add a new test case:

1. Create a folder in `golden/get/` or `golden/post/` named after your test
2. Add an `input.json` file with the request payload
3. Add an `output.txt` file with the expected SSE response

### Special Cases

#### Multiline Signals

For `patchSignals` events, if you need multiline output:
- Use `signals-raw` as a string with `\n` characters instead of `signals` as a JSON object
- The server should check for `signals-raw` first, then fall back to `signals`

## Test Cases

The test suite covers:

- Element patching (single and multiline)
- Signal patching  
- Script execution
- Element/signal removal
- Various SSE formatting scenarios
- Edge cases and error conditions

---

### Overview (`sdk/typescript/README.md`)

# Datastar TypeScript SDK

The Datastar TypeScript SDK has moved to a dedicated repo at [https://github.com/starfederation/datastar-typescript](https://github.com/starfederation/datastar-typescript).

---

### Overview (`sdk/zig/README.md`)

# Datastar Zig SDK

The Datastar Zig SDK has been deprecated.

---

--- METRICS ---
- Files Extracted: 15
- Estimated Token Budget: ~2776 tokens
- Canonical Reference: https://codewiki.google/github.com/starfederation/datastar