datastar Documentation

Technical Documentation: starfederation/datastar

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Datastar

The hypermedia framework. Copy Section

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.

<script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/[email protected]/bundles/datastar.js"></script>

Then start adding frontend reactivity using declarative data-* attributes.

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

Visit the Datastar Website »

Watch the Videos »

Join the Discord Server »

Getting Started Copy Chapter

Read the Getting Started Guide »

Contributing Copy Chapter

Read the Contribution Guidelines »

Overview (`sdk/README.md`) Copy Section

Datastar SDK Directory

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

Structure Copy Chapter

• 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 Copy Chapter

Configuration Copy Section

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 Copy Section

1. Read the Architecture Decision Record for SDK specifications
2. Use datastar-sdk-config.json as your source of constants
3. Implement the required ServerSentEventGenerator interface
4. Validate your implementation using the test suite

Official SDKs Copy Chapter

Official SDKs can be found at the Datastar website.

Support Copy Chapter

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.

Overview (`sdk/clojure/README.md`) Copy Section

Datastar Clojure SDK

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

Overview (`sdk/dotnet/README.md`) Copy Section

Datastar C# (.NET) SDK

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

Overview (`sdk/go/README.md`) Copy Section

Datastar Go SDK

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

Overview (`sdk/haskell/README.md`) Copy Section

Datastar Haskell SDK

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

Overview (`sdk/java/README.md`) Copy Section

Datastar Java SDK

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

Overview (`sdk/php/README.md`) Copy Section

Datastar PHP SDK

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

Overview (`sdk/python/README.md`) Copy Section

Datastar Python SDK

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

Overview (`sdk/ruby/README.md`) Copy Section

Datastar Ruby SDK

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

Overview (`sdk/rust/README.md`) Copy Section

Datastar Rust SDK

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

Overview (`sdk/test/README.md`) Copy Section

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 Copy Chapter

$ ./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 Copy Chapter

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 Copy Section

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`) Copy Section

Datastar SDK Test Suite

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

Installation Copy Chapter

As a Go Library Copy Section

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

Usage Copy Chapter

Running Tests Copy Section

# 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 Copy Section

# 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 Copy Chapter

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 Copy Chapter

• 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 Copy Chapter

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 Copy Chapter

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 Copy Section

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

Output Format Copy Section

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 Copy Chapter

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 Copy Section

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 Copy Chapter

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`) Copy Section

Datastar TypeScript SDK

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

Overview (`sdk/zig/README.md`) Copy Section

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