Documentation

Saync is one npm package that ships an SDK, a Playwright-driven agent, a SQLite store, and a dashboard — all running locally inside your project. Everything below assumes Node 18+ and any package manager (npm / pnpm / yarn / bun).

Building with an AI assistant?

Download the full Saync context as a single Markdown file. Paste it into Claude / ChatGPT / Cursor / Copilot Chat — the model will know every component, flow step, contract shape, CLI command, and HTTP endpoint.

Download saync-llm.md View in browser

1. Install

bash

npm install --save-dev saync-web

Add a script to your package.json:

json

{
  "scripts": {
    "saync": "saync start"
  }
}

Boot it with npm run saync and open localhost:3777.

2. Declare contracts

Wrap interactive elements with the SDK and say what they should do:

tsx

import { SayncButton } from 'saync-web/react';

export function AddToCartButton({ onClick }) {
  return (
    <SayncButton
      onClick={onClick}
      expect={{
        onClick: {
          apiCall: {
            method: 'POST',
            url: '/api/cart',
            expectedStatus: 200,
            maxDuration: 500,
          },
        },
      }}
    >
      Add to cart
    </SayncButton>
  );
}

3. Multi-step flows (optional)

For journeys — login, checkout, share — drop a saync.flows.ts at your repo root:

import { defineFlow } from 'saync-web';

export const flows = [
  defineFlow({
    name: 'add-to-cart',
    description: 'Add a product to cart and verify the badge updates.',
    steps: [
      { interact: 'add-to-cart' },
      { interact: 'open-cart' },
      { expect: { text: 'Your cart' } },
    ],
  }),
];

4. Modes

The SAYNC_MODE env var (or the mode field in saync.config.ts) decides behavior:

local — the watcher re-runs the agent on every file save.
dev — one-shot agent run at build time, plus the production reporter for real-user traffic.
prod — production reporter only; slower polling, retention tuned for live traffic.

5. Configuration

// saync.config.ts at your repo root
export default {
  appUrl: 'http://localhost:3000',  // your dev server
  port: 3777,                       // dashboard port
  watch: ['src/**/*.{ts,tsx}'],     // local-mode watch globs
  mode: 'local',
};

Equivalent env vars: SAYNC_MODE, SAYNC_PORT, SAYNC_APP_URL, SAYNC_DB_PATH. Env wins over config file wins over defaults.

6. AI reports (bring your own LLM)

Saync never ships an LLM key. Set one of these in your project's .env and the dashboard's "Generate report" buttons start working:

env

WATSONX_API_KEY=...
WATSONX_PROJECT_ID=...
# or
OPENAI_API_KEY=...
# or
ANTHROPIC_API_KEY=...

7. CLI

saync start — boot the dashboard, the app probe, and (in local mode) the file watcher.
saync run — one-shot agent invocation. Used by CI / build hooks.
saync clear — wipe all locally-stored data (confirms first).

8. Your data

Everything lives in .saync/saync.db inside your repo. Add it to .gitignore. Nothing leaves your machine unless you explicitly configure an LLM (in which case only the prompt context goes to the provider you chose).