Skip to content
askdareDocumentation

    ADR-0006: Support matrix and versioning policy

    • Status: Accepted
    • Date: 2026-10-29

    Context

    A library runs inside its users' apps, so every supported combination of versions is a promise. A narrow, published matrix is the cheapest way to keep that promise.

    Decision

    Support matrix

    AreaSupportedNot supported
    Node.js22 and 24 (engines: >=22)20 or older (end of life)
    Next.js16.x, latest minor (peer ^16), App Router, Node.js runtimePages Router, Edge runtime, static export
    React19 in your app. 0.1 has no React peer: the chat is a prebuilt iframe app. The React subpath in 0.2 adds the peer ^19.18
    Zod^4.1 (peer, required)3
    BundlersTurbopack (default) and next build --webpack
    Consumer TypeScript5.9, 6.0 and 7.0 (published .d.ts tested against each)
    HostingVercel and Heroku, both documented and smoke-testedOthers are unsupported but expected to work if they run next start

    Versioning (0.x)

    • Minor releases may break; patch releases never do.

    • A removal is preceded by a deprecation warning one minor earlier.

    • Every change carries a changeset.

    • The SSE protocol has its own version (x-askdare-protocol).

    • The public surface is exactly:

      • defineBot, defineTool, createChatHandler (and defineTheme);
      • the script tag's data-* attributes and the askdare() JS API, identify included;
      • the identity token's claims, IDENTITY_SECRET and context.identity (ADR-0009);
      • --ask-* tokens, data-ask-part names and dictionary keys;
      • the shadow parts on the host page (launcher, panel, unavailable) and the host element's data-askdare attribute;
      • the protocol version;
      • ports implemented by official add-ons: RateLimitStore (and CounterHit);
      • the askdare commands and their options (init, doctor, kb sync), but not their printed output or the /doctor report behind doctor.

      Everything else is internal.

    • Guards (published for users in Support):

      • a .d.ts snapshot (packages/askdare/api/askdare.api.txt) fails the check when the published types change, until it is updated on purpose with a changeset; a consumer project type-checks the published .d.ts with TypeScript 5.9, 6.0 and 7.0;
      • size budgets fail the build: loader 5 KB, chat app 50 KB, its styles 8 KB, each preset's fonts 82 KB (gzipped);
      • a nightly canary runs the checks and browser tests against next@canary and openai@latest (with the mocked OpenAI API);
      • a daily live smoke test runs on a cheap model in a dedicated, spend-capped OpenAI project, so a retired model or a changed API fails there.

    Consequences

    • Issues from unsupported setups are closed with a link to this ADR.
    • Upgrading the Next.js or React major is a deliberate, planned change, not something that breaks unexpectedly.