@fastyoke/sdk-vue

Vue 3 bindings for FastYoke — 7 components + 4 composables wrapping @fastyoke/sdk-core.

Preview — API may change before 1.0.

This package is published on the preview dist-tag. Install with the explicit tag (npm install @fastyoke/sdk-vue@preview) — latest will not resolve until the v1.0 contract is locked.

Install

npm install @fastyoke/sdk-vue@preview @fastyoke/sdk-core
# peer dep — bring your own Vue
npm install vue

vue and @fastyoke/sdk-core are declared as peer dependencies. The SDK is built ESM-first with a CJS fallback and ships its own .d.ts types.

Quick start

Build the shared FastYokeClient once via createFastYokeClient from sdk-core, then install FastYokePlugin with that client. Every composable reads the client via Vue's inject contract.

// main.ts
import { createApp } from 'vue';
import { createFastYokeClient } from '@fastyoke/sdk-core';
import { FastYokePlugin } from '@fastyoke/sdk-vue';
import App from './App.vue';

const client = createFastYokeClient({
  tenantId: 'tenant_xyz',
  baseUrl: 'https://app.fastyoke.io',
  fetcher: fetch.bind(globalThis),
});

createApp(App)
  .use(FastYokePlugin, { client })
  .mount('#app');

<!-- App.vue -->
<script setup lang="ts">
import { useEntity, useFsmJob } from '@fastyoke/sdk-vue';

const { data: customer, isLoading, error } = useEntity('customer', 'cust_42');
const { data: shipment, transition } = useFsmJob('job_99');

async function markShipped() {
  await transition('mark_shipped');
}
</script>

<template>
  <div v-if="isLoading">Loading…</div>
  <div v-else-if="error">{{ error.message }}</div>
  <div v-else>
    {{ customer?.data_payload?.name }}
    <button @click="markShipped">Ship</button>
  </div>
</template>

Public surface (v0.1)

Composables (4 public + 2 internal):

• useFastYokeClient() — raw FastYokeClient handle from sdk-core.
• useEntity(entityName, id, { live? }) — { data, error, isLoading, refresh }.
• useFsmJob(jobId, { live? }) — { data, error, isLoading, transition, cancel, refresh }.
• useEvents(filter?) — { events, close }, always live.
• useEntityEventLog, useEntityJobs — internal, back <WorkflowSection />. Not exported from the barrel.

Components (7):

• <SmartField />, <EntitySelect />, <ToggleSwitch />
• <FsmViewer />, <WorkflowSection />
• <LeftNavShell />, <TopNavShell />

SSR safety

Every composable opens realtime subscriptions only inside onMounted, guarded by isBrowser() + the injected ssrSafeRealtime flag (default true). Components never reference window during render. Use in plain Vue 3 SPAs, Vite SSR, or Nuxt SSR without configuration. Set { ssrSafeRealtime: false } on app.use() to skip realtime setup entirely (Phase G's @fastyoke/sdk-nuxt module sets this automatically on the server side).

Documented v0.1 gaps

• Mutation composables (useCreateEntity, useUpdateEntity, useDeleteEntity, useSpawnJob) — call useFastYokeClient().entities.create(...) etc. directly. Ships in v0.2.
• useFsmJob().transition() payload arg is dropped in v0.1 — the sdk-core TransitionInput exposes only eventType and contextRecordId. v0.2 widens the wire layer + composable together.
• <FsmViewer /> reactflow canvas — only the compact timeline mode ships in v0.1. Full canvas mode in v0.2.
• <FilePayloadView />, <ThemeStyle />, full theming primitives. Use the CSS variable hook described below.
• Extension authoring (ExtensionRegistry, ExtensionErrorBoundary). Separate roadmap.

Theming

All components accept :class passthrough on their root element so you can layer Tailwind / CSS Modules / vanilla classes without forking. Component-internal styling reads CSS custom properties under the --fy-* prefix (e.g. --fy-accent, --fy-bg, --fy-border) so you can override the look at any ancestor scope without touching component code. Mirroring react/shells/ThemeStyle.tsx (a fetch-and-inject helper for tenant-defined CSS) arrives in v0.2.

License

MIT.