Convex example

Overview

A complete Convex backend that mounts the @shipdit/convex component and evaluates new-checkout and search-variant in an authenticated query. The component stores the snapshot in Convex, so evaluations are reactive and add no network call.

What’s in it

convex/convex.config.ts mounts one component instance named shipd for one shipd environment.
convex/lib/shipd.ts wraps the instance with typed defaults.
convex/storefront.ts authorizes the caller, then evaluates both flags for that user.
A signed webhook from shipd triggers a refresh when a snapshot is published. A one-minute poll is the fallback.

convex-example/
├── package.json
├── shipd.config.ts
└── convex/
    ├── convex.config.ts
    ├── http.ts
    ├── storefront.ts
    └── lib/
        └── shipd.ts

convex/_generated/ is created by npx convex dev.

Files

package.json

{
  "name": "convex-example",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "convex dev",
    "deploy": "convex deploy",
    "flags:diff": "shipd diff",
    "flags:push": "shipd push"
  },
  "dependencies": {
    "@shipdit/convex": "^0.2.0",
    "convex": "^1.44.0"
  },
  "devDependencies": {
    "@shipdit/cli": "^0.3.2",
    "shipdit": "^0.3.0",
    "typescript": "^5.9.0"
  }
}

shipdit is a dev dependency here because only shipd.config.ts imports it. Convex functions use @shipdit/convex.

shipd.config.ts

import { defineFlags } from "shipdit/config";

export default defineFlags({
  "new-checkout": {
    type: "boolean",
    default: false,
    description: "Redesigned checkout flow",
    tags: ["checkout"],
  },
  "search-variant": {
    type: "variant",
    variants: ["control", "semantic", "hybrid"] as const,
    default: "control",
    description: "Search ranking experiment",
    tags: ["search", "experiment"],
  },
});

convex/convex.config.ts

import shipd from "@shipdit/convex/convex.config.js";
import { defineApp } from "convex/server";
import { v } from "convex/values";

const app = defineApp({
  env: {
    SHIPD_SDK_KEY: v.string(),
    SHIPD_WEBHOOK_SECRET: v.string(),
  },
});

// The component serves its webhook at `${httpPrefix}/webhook`.
app.use(shipd, {
  name: "shipd",
  httpPrefix: "/shipd",
  env: {
    SHIPD_SDK_KEY: app.env.SHIPD_SDK_KEY,
    SHIPD_WEBHOOK_SECRET: app.env.SHIPD_WEBHOOK_SECRET,
  },
});

export default app;

convex/http.ts

import { httpRouter } from "convex/server";

// Your own HTTP routes go here. The shipd component registers its webhook route itself.
export default httpRouter();

The wrapper takes a flag map with variants as a readonly tuple. Keep it in sync with shipd.config.ts.

convex/lib/shipd.ts

import { Shipd } from "@shipdit/convex";

import { components } from "../_generated/api";

type Flags = {
  "new-checkout": { type: "boolean"; default: false };
  "search-variant": {
    type: "variant";
    default: "control";
    variants: readonly ["control", "semantic", "hybrid"];
  };
};

// Returned before the first snapshot syncs, and for missing or mistyped flags.
export const shipd = new Shipd<Flags>(components.shipd, {
  "new-checkout": false,
  "search-variant": "control",
});

convex/storefront.ts

import { v } from "convex/values";

import { query } from "./_generated/server";
import { shipd } from "./lib/shipd";

export const flags = query({
  args: {},
  returns: v.object({
    newCheckout: v.boolean(),
    search: v.union(v.literal("control"), v.literal("semantic"), v.literal("hybrid")),
  }),
  handler: async (ctx) => {
    // Component functions cannot see ctx.auth. Authorize here, before evaluating.
    const identity = await ctx.auth.getUserIdentity();
    if (identity === null) {
      throw new Error("Unauthenticated");
    }

    const context = { userId: identity.subject };

    return {
      newCheckout: await shipd.isEnabled(ctx, "new-checkout", context),
      search: await shipd.getVariant(ctx, "search-variant", context),
    };
  },
});

Run it

Push the flags

pnpm install
pnpm exec shipd login       # approve org → project → environment in the browser
pnpm exec shipd push

Start Convex

npx convex dev

This creates the deployment and generates components.shipd. Leave it running.

Set environment values

In a second terminal, use a server SDK key for the environment you pushed to. Set a placeholder secret for now.

npx convex env set SHIPD_SDK_KEY shipd_sdk_server_...
npx convex env set SHIPD_WEBHOOK_SECRET replace-after-dashboard-setup

Create the webhook destination

In the shipd dashboard, open the project’s Settings → Integrations. Under Convex, choose the environment and enter https://<your-deployment>.convex.site/shipd/webhook. Click Create destination, copy the signing secret, and replace the placeholder:

npx convex env set SHIPD_WEBHOOK_SECRET <signing-secret>

Click Test delivery.

Call the query

npx convex run storefront:flags --identity '{"subject":"usr_8f2k19"}'
# { newCheckout: false, search: "control" }

Add a rule to new-checkout in the dashboard and click Save environment. The webhook refreshes the component and subscribed clients re-render with the new value.

Adapt it

Mount one named instance per shipd environment (for example shipdDevelopment and shipdProduction), each with its own SDK key, httpPrefix, and webhook secret.
Add attributes to the context (plan, organizationId) from your own tables after authorization.
Use shipd.evaluate(ctx, key, context) to get the reason and snapshot version, and shipd.getStatus(ctx) to check sync health.
Call shipd.syncNow(ctx) from an authorized action to force a refresh.

Complete applications

Convex example

Overview

What’s in it

Files

Run it

Adapt it

Next

​Overview

​What’s in it

​Files

​Run it

​Adapt it

​Next

Overview

What’s in it

Files

Run it

Adapt it

Next