Documentation Index
Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
Use this file to discover all available pages before exploring further.
This page distills the most important internal knowledge for developers working on the Tagada platform. It covers deprecated APIs you should stop using, architecture patterns you must understand, and migrations currently in progress.
Deprecated APIs
These APIs have replacements and should not be used in new code. Existing usages should be migrated when touching the relevant files.
Plugin SDK (@tagadapay/plugin-sdk)
The README references @tagadapay/plugin-sdk/v3 but that export path does not exist in package.json. Use @tagadapay/plugin-sdk/v2 or the root import (which re-exports v2).
| Deprecated | Use Instead | Notes |
|---|
useFunnelLegacy() / useSimpleFunnel() | TagadaProvider + useFunnel() | Legacy hooks maintain duplicate session logic |
onSuccess / onFailure (payment callbacks) | onPaymentSuccess / onPaymentFailed | Removal planned for next SDK major version |
staticResources (on step config, funnel config, hooks) | resources | Applies to RuntimeStepConfig, LocalFunnelConfig, UseStepConfigResult |
getAssignedStaticResources() | getAssignedResources() | Same rename as above |
getPreviewParams() | getSDKParams() | In previewMode.ts |
transformToCheckout() | transformToCheckoutSession() | In offers.ts |
@tagadapay/plugin-sdk/react subpath | @tagadapay/plugin-sdk/v2 or root | ./react is the Legacy V1 surface (SWR-based). V2 uses TanStack Query. |
/config/resources.static.json | /config/funnel.local.json | Old static resource config path for local dev |
Node SDK (@tagadapay/node-sdk)
| Deprecated | Use Instead | Why |
|---|
checkout.init() | checkout.createSession() | init() follows HTTP 302 redirects and can parse HTML as JSON. createSession() returns a clean checkoutToken. |
plugins.deploymentDetails() | plugins.retrieveDeployment() | Simplified signature (no storeId required) |
CRM App
| Deprecated | Use Instead | Location |
|---|
FlowStep type | FunnelNode | storefront/types.ts |
StepConfig.paymentFlowId (top-level) | stepConfig.payment.paymentFlowId | Nested under payment object |
useAnalyticsV4 | Per-metric hooks (useRebillRevenueData, etc.) | lib/api/analytics.ts — v4 is a monolithic hook being split |
payment-guard.tsx | payment-method-valid-guard.tsx | Guard component rename |
Studio App
| Deprecated | Use Instead | Notes |
|---|
setActionHandler() on DataStore | registerAction(type, handler) | Per-action-type registry. setActionHandler is a single catch-all fallback. |
Bundle mode 'esbuild' | 'standalone' | Name was misleading (no tree-shaking involved) |
Bundle modes 'interactive' / 'esbuild-bundle' | 'runtime' / 'islands' / 'treeshake' / 'standalone' | Legacy bundle modes with limited SDK support |
Must-Know Architecture Patterns
These are non-obvious patterns that every developer touching the codebase must understand.
CRM App
The CRM is a Vite SPA with React Router — not Next.js. Server-side API and tRPC routers live on the main Tagada app at /api/crm/trpc, not inside crm-app.
- Clerk provides auth. JWT is passed as
Authorization: Bearer to tRPC.
- Org context is synced via
OrgRouteWrapper — when the user switches org, useResetQueries() invalidates all queries to avoid stale data from the previous org.
Funnel dual model:
- Funnels have both
nodes/edges (V2 graph model) and legacy steps (flat list), kept in sync via useFunnelData.
- Always deep-copy nodes/edges before mutating — they come from React Query cache.
- Never copy
url when cloning steps — the backend recomputes URLs from mount points.
- Split-test variants each have their own
stepConfig.
Plugin lifecycle:
instantiate creates a plugin instance but does NOT mount it to a funnel step.- The user must explicitly configure and publish. Code should not assume instantiation = live.
Studio App
Two operating modes:
- Embedded (inside CRM iframe): communicates via Builder Protocol (
postMessage), skips localStorage hydration to avoid stale data.
- Standalone (direct URL): authenticated via Clerk, full localStorage persistence for work-in-progress recovery.
DataStore (commerce layer):
- Vanilla Zustand store (works outside React for island hydration).
- MockResolver provides static fixtures for design mode. TagadaResolver makes real API calls in live mode.
- Use
registerAction(type, handler) to register action handlers. The old setActionHandler catch-all is deprecated.
Current bundle modes:
| Mode | Output | Best For |
|---|
runtime | Monolithic JS (~3.5 MB) | Development, testing |
islands | Static HTML + hydrated commerce (~620 KB JS) | Production (fastest first paint) |
treeshake | Per-component JS loading | Templates using few components |
standalone | Single self-contained HTML | Plugin deployment, previews |
interactive, esbuild-bundle, and esbuild are legacy and should not be used.
Template parsing:
parseTemplateFile() accepts 3 formats for backward compatibility: StudioTemplateFile wrapper, legacy { version, template }, and raw FunnelTemplate.- Legacy page types
upsell / downsell auto-normalize to offer.
Active Migration Paths
These transitions are in progress. New code should target the “After” column.
| Area | Before (Legacy) | After (Current) | Bridge |
|---|
| Funnel model | steps (flat list) | nodes + edges (graph) | useFunnelData syncs both representations |
| Step config: payment | StepConfig.paymentFlowId | stepConfig.payment.paymentFlowId | Both read in CRM; write to nested form |
| Step config: resources | staticResources | resources | SDK reads both with fallback |
| Analytics hooks | useAnalyticsV4 (monolithic) | Per-metric hooks (useRebillRevenueData, etc.) | v4 still works; new dashboards use per-metric |
| Conditions | LegacyCondition (flat) | JSONLogic structured conditions | ConditionBuilder + isLegacyCondition() |
| Plugin SDK surface | V1 (./react, SWR) | V2 (./v2 or root, TanStack Query) | V1 still published; new plugins use V2 |
| Funnel hooks | useFunnelLegacy / useSimpleFunnel | TagadaProvider + useFunnel | Legacy hooks re-exported for backward compat |
| Payment callbacks | onSuccess / onFailure | onPaymentSuccess / onPaymentFailed | Both work today; old names removed in next major |
