@schematichq/schematic-vue

schematic-vue

schematic-vue is a client-side Vue library for Schematic which provides composables to track events, check flags, and more. schematic-vue provides the same capabilities as schematic-js, for Vue apps.

Install

npm install @schematichq/schematic-vue
# or
yarn add @schematichq/schematic-vue
# or
pnpm add @schematichq/schematic-vue

Usage

SchematicPlugin

You can use the SchematicPlugin to make Schematic available throughout your Vue application:

import { createApp } from "vue";
import { SchematicPlugin } from "@schematichq/schematic-vue";
import App from "./App.vue";

const app = createApp(App);
app.use(SchematicPlugin, { publishableKey: "your-publishable-key" });
app.mount("#app");

Setting context

To set the user context for events and flag checks, you can use the identify function provided by the useSchematicEvents composable:

<script setup lang="ts">
import { onMounted } from "vue";
import { useSchematicEvents } from "@schematichq/schematic-vue";

const { identify } = useSchematicEvents();

onMounted(() => {
  identify({
    keys: { id: "my-user-id" },
    company: {
      keys: { id: "my-company-id" },
      traits: { location: "Atlanta, GA" },
    },
  });
});
</script>

To learn more about identifying companies with the keys map, see key management in Schematic public docs.

Tracking usage

Once you've set the context with identify, you can track events:

<script setup lang="ts">
import { useSchematicEvents } from "@schematichq/schematic-vue";

const { track } = useSchematicEvents();

function handleQuery() {
  track({ event: "query" });
}
</script>

<template>
  <button @click="handleQuery">Run Query</button>
</template>

If you want to record large numbers of the same event at once, or perhaps measure usage in terms of a unit like tokens or memory, you can optionally specify a quantity for your event:

track({ event: "query", quantity: 10 });

Checking flags

To check a flag, you can use the useSchematicFlag composable:

<script setup lang="ts">
import { useSchematicFlag } from "@schematichq/schematic-vue";

const isFeatureEnabled = useSchematicFlag("my-flag-key");
</script>

<template>
  <div v-if="isFeatureEnabled">
    <Feature />
  </div>
  <div v-else>
    <Fallback />
  </div>
</template>

Checking entitlements

You can check entitlements (i.e., company access to a feature) using a flag check as well, and using the useSchematicEntitlement composable you can get additional data to render various feature states:

<script setup lang="ts">
import {
  useSchematicEntitlement,
  useSchematicIsPending,
} from "@schematichq/schematic-vue";

const schematicIsPending = useSchematicIsPending();
const {
  featureAllocation,
  featureUsage,
  featureUsageExceeded,
  value: isFeatureEnabled,
} = useSchematicEntitlement("my-flag-key");
</script>

<template>
  <!-- Loading state -->
  <Loader v-if="schematicIsPending" />

  <!-- Usage exceeded state -->
  <div v-else-if="featureUsageExceeded">
    You have used all of your usage ({{ featureUsage }} / {{ featureAllocation }})
  </div>

  <!-- Either feature state or "no access" state -->
  <Feature v-else-if="isFeatureEnabled" />
  <NoAccess v-else />
</template>

Note: useSchematicIsPending is checking if entitlement data has been loaded, typically via identify. It should, therefore, be used to wrap flag and entitlement checks, but never the initial call to identify.

For features metered by credit burndown, the same composable exposes the company's credit position:

All four unwrap to undefined when the feature is not credit-based.

<script setup lang="ts">
import { useSchematicEntitlement } from "@schematichq/schematic-vue";

const { creditSettled, value: isFeatureEnabled } =
  useSchematicEntitlement("my-flag-key");
</script>

<template>
  <OutOfCredits v-if="!isFeatureEnabled" />
  <Feature v-else :credits-remaining="creditSettled" />
</template>

These values refresh with each flag check. For a balance that also updates on the credit partials arriving between checks, pass creditId to useSchematicCreditBalance instead.

Usage warnings

If a usage warning is configured on the entitlement, the composable exposes it as warningTiers, so you can warn a customer before they hit the limit rather than after:

The dashboard writes a single tier under the key default.

<script setup lang="ts">
import { computed } from "vue";
import { useSchematicEntitlement } from "@schematichq/schematic-vue";

const { featureUsage, warningTiers } = useSchematicEntitlement("my-flag-key");

const warning = computed(() =>
  warningTiers.value?.find((tier) => tier.key === "default"),
);
const approachingLimit = computed(
  () =>
    typeof featureUsage.value === "number" &&
    typeof warning.value?.value === "number" &&
    featureUsage.value >= warning.value.value,
);
</script>

<template>
  <ApproachingLimit v-if="approachingLimit" :limit="warning!.value" />
  <Feature />
</template>

Company plan information

To access the current company's plan and trial status, you can use the useSchematicPlan composable:

<script setup lang="ts">
import { useSchematicPlan } from "@schematichq/schematic-vue";

const plan = useSchematicPlan();
</script>

<template>
  <div v-if="!plan">No plan assigned</div>
  <div v-else>
    <p>Current plan: {{ plan.name }}</p>

    <p v-if="plan.trialStatus === 'active'">
      Trial ends: {{ plan.trialEndDate?.toLocaleDateString() }}
    </p>

    <p v-if="plan.trialStatus === 'expired'">
      Your trial has ended. <a href="https://github.com/SchematicHQ/schematic-js/blob/HEAD/upgrade">Upgrade now</a>
    </p>
  </div>
</template>

The composable returns an object with the following properties:

Credit balances

To display a company's credit balance, use the useSchematicCreditBalance composable. It is keyed by credit ID and updates reactively as the balance changes over the DataStream:

<script setup lang="ts">
import { useSchematicCreditBalance } from "@schematichq/schematic-vue";

const { balance, isLoading } = useSchematicCreditBalance("credit-id");
</script>

<template>
  <div v-if="isLoading">Loading…</div>
  <div v-else>{{ balance }} credits remaining</div>
</template>

The composable returns an object with the following reactive properties:

The credit ID is available on a feature's entitlement, and the composable accepts a ref or a getter as well as a plain string, so you can feed one straight through:

<script setup lang="ts">
import {
  useSchematicCreditBalance,
  useSchematicEntitlement,
} from "@schematichq/schematic-vue";

const { creditId } = useSchematicEntitlement("my-flag-key");
const { balance, isLoading } = useSchematicCreditBalance(creditId);
</script>

<template>
  <div v-if="isLoading">Loading…</div>
  <div v-else>{{ balance }} credits remaining</div>
</template>

The composable re-keys to the new credit whenever the source resolves to a different ID. While it resolves to undefined, it reports the client's loading state and a balance of 0.

Credit spend policies

To show the spend limits that bind the current company and user, use the useSchematicCreditSpendPolicies composable. It updates over the DataStream, so a policy edited or deleted in the dashboard reaches the component without a refetch:

<script setup lang="ts">
import { useSchematicCreditSpendPolicies } from "@schematichq/schematic-vue";

const { policies, isLoading } = useSchematicCreditSpendPolicies();
</script>

<template>
  <div v-if="isLoading">Loading…</div>
  <ul v-else>
    <li v-for="policy in policies" :key="policy.id">
      <template v-if="policy.kind === 'window' && policy.window">
        {{ policy.scope }} limit: {{ policy.consumed }} of {{ policy.limit }} credits used this {{ policy.window.unit }}
      </template>
      <template v-else>
        {{ policy.scope }} limit: {{ policy.limit }} credits per request
      </template>
    </li>
  </ul>
</template>

The composable returns an object with the following reactive properties:

A per_draw policy caps a single draw. A window policy caps what can be spent in one period: consumed is what the current period has spent, resetsAt is when the period ends, and window names the period. Each new spend sends an updated consumed. Once resetsAt has passed, read consumed as 0 until the next update arrives.

Fallback Behavior

The SDK includes built-in fallback behavior you can use to ensure your application continues to function even when unable to reach Schematic (e.g., during service disruptions or network issues).

Flag Check Fallbacks

When flag checks cannot reach Schematic, they use fallback values in the following priority order:

1. Callsite fallback - fallback values can be provided directly in the composable options
2. Initialization defaults - fallback values configured via flagCheckDefaults or flagValueDefaults options when initializing the plugin
3. Default value - Returns false if no fallback is configured

<script setup lang="ts">
// Provide a fallback value at the callsite
import { useSchematicFlag } from "@schematichq/schematic-vue";

const isFeatureEnabled = useSchematicFlag("feature-flag", {
    fallback: true,  // Used if API request fails
});
</script>

<template>
    <Feature v-if="isFeatureEnabled" />
    <Fallback v-else />
</template>

// Or configure defaults at initialization
import { createApp } from "vue";
import { SchematicPlugin } from "@schematichq/schematic-vue";

const app = createApp(App);
app.use(SchematicPlugin, {
    publishableKey: "your-publishable-key",
    flagValueDefaults: {
        "feature-flag": true,  // Used if API request fails and no callsite fallback
    },
    flagCheckDefaults: {
        "another-flag": {
            flag: "another-flag",
            value: true,
            reason: "Default value",
        },
    },
});

Event Queueing and Retry

When events (track, identify) cannot be sent due to network issues, they are automatically queued and retried:

• Events are queued in memory (up to 100 events by default, configurable via maxEventQueueSize)
• Failed events are retried with exponential backoff (up to 5 attempts by default, configurable via maxEventRetries)
• Events are automatically flushed when the network connection is restored
• Events queued when the page is hidden are sent when the page becomes visible

WebSocket Fallback

In WebSocket mode, if the WebSocket connection fails, the SDK will provide the last known value or the configured fallback values as outlined above. The WebSocket will also automatically attempt to re-establish its connection with Schematic using an exponential backoff.

Options API Support

While the primary API uses the Composition API, you can still use these composables in the Options API:

<script>
import { useSchematicFlag, useSchematicEvents } from "@schematichq/schematic-vue";

export default {
  setup() {
    const isFeatureEnabled = useSchematicFlag("my-flag-key");
    const { track } = useSchematicEvents();

    return {
      isFeatureEnabled,
      track,
    };
  },
  methods: {
    handleAction() {
      this.track({ event: "action" });
    },
  },
};
</script>

Troubleshooting

For debugging and development, Schematic supports two special modes:

Debug Mode

Enables console logging of all Schematic operations:

// Enable at initialization
import { createApp } from "vue";
import { SchematicPlugin } from "@schematichq/schematic-vue";

const app = createApp(App);
app.use(SchematicPlugin, {
  publishableKey: "your-publishable-key",
  debug: true,
});

// Or via URL parameter
// https://yoursite.com/?schematic_debug=true

Offline Mode

Prevents network requests and returns fallback values for all flag checks:

// Enable at initialization
import { createApp } from "vue";
import { SchematicPlugin } from "@schematichq/schematic-vue";

const app = createApp(App);
app.use(SchematicPlugin, {
  publishableKey: "your-publishable-key",
  offline: true,
});

// Or via URL parameter
// https://yoursite.com/?schematic_offline=true

Offline mode automatically enables debug mode to help with troubleshooting.

Advanced Usage

Using a Pre-configured Client

If you need more control over the Schematic client initialization, you can create a client instance and pass it to the plugin:

import { createApp } from "vue";
import { Schematic } from "@schematichq/schematic-js";
import { SchematicPlugin } from "@schematichq/schematic-vue";
import App from "./App.vue";

const client = new Schematic("your-publishable-key", {
  useWebSocket: true,
  debug: true,
});

const app = createApp(App);
app.use(SchematicPlugin, { client });
app.mount("#app");

Per-Component Client Override

You can override the client for a specific component by passing a client option to any composable:

import { useSchematicFlag } from "@schematichq/schematic-vue";
import { Schematic } from "@schematichq/schematic-js";

const customClient = new Schematic("different-api-key");
const isFeatureEnabled = useSchematicFlag("my-flag-key", {
  client: customClient,
});

Server-Side Rendering (SSR)

All composables are SSR-compatible and work seamlessly with Nuxt and other Vue SSR frameworks:

• Initial flag/entitlement values are retrieved synchronously for server-side rendering
• Real-time subscriptions are deferred to client-side hydration
• No special configuration needed - it just works!

// plugins/schematic.ts
import { SchematicPlugin } from '@schematichq/schematic-vue'

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()
  nuxtApp.vueApp.use(SchematicPlugin, { publishableKey: config.public.schematicPublishableKey })
})

<!-- Works in Nuxt/SSR -->
<script setup lang="ts">
import { useSchematicFlag } from "@schematichq/schematic-vue";

// Initial value available on server, updates subscribed on client
const isFeatureEnabled = useSchematicFlag("my-feature");
</script>

License

MIT

Support

Need help? Please open a GitHub issue or reach out to support@schematichq.com and we'll be happy to assist.