Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.cartble.com/llms.txt

Use this file to discover all available pages before exploring further.

Before you deploy a custom plugin or submit it for review, work through the items below. This checklist covers every requirement outlined in the Cartble plugin development guide — from registration and data scoping to UI consistency and directory hygiene. A plugin that passes all items here is ready for production.

​
Registration and navigation

  • Plugin registered in the main plugin registry — your plugin’s loader is included in src/core/plugin-registry.ts under PLUGIN_LOADERS and resolves correctly via getAllPluginsAsync() / getInstalledPluginsAsync().
  • adminApps defined with icons and labels — every page your plugin exposes has an entry in the adminApps array with a unique id, a human-readable label, and a valid Lucide icon component. These entries drive the admin sidebar navigation.

​
Bridge and context isolation

  • All exported pages wrapped with withBridge — every component referenced in adminApps and slots is wrapped with your plugin’s Bridge HOC (e.g., withYourPluginBridge). This HOC provides an isolated QueryClient and any plugin-local context, preventing pollution of the main application’s React tree.

​
Pricing and currency display

  • All price displays use formatPrice — every monetary value rendered in your plugin’s UI is formatted through formatPrice from useTranslation. No raw .toFixed() calls, no custom currency symbols, and no hardcoded locale assumptions.

​
Firestore data access

  • Direct updates to core resources collection follow the platform schema — if your plugin reads or writes to platforms/{platformId}/resources/, every document field conforms to Cartble’s existing resource schema. No conflicting or shadow fields are introduced.
  • All Firestore data stored under platforms/{platformId}/ — every collection your plugin reads from or writes to sits under the platform-scoped Firestore path. No data is written at the root level or to a path outside the current platform’s namespace.

​
State management and cache scoping

  • React Query keys include platformId — every useQuery and useMutation call in your plugin uses a query key with platformId as the first element (e.g., [platformId, 'your-plugin', 'resource-type']). This prevents cache entries from leaking between platforms when a user switches accounts.

​
Hardcoding and global constants

  • No hardcoded platform IDs, collection names, or global constants — your plugin contains no string literals that represent a specific platformId, no hardcoded Firestore collection paths (e.g., platforms/abc123/...), and no global variables that would break in a multi-platform deployment. All paths are constructed dynamically using usePlatform().

​
UI components and design system

  • UI components sourced from src/components/ui/ — your plugin does not define custom button, input, or confirmation dialog components. All interactive controls use Button.tsx, Input.tsx, and ConfirmModal.tsx from the shared UI library.
  • Tailwind classes match the admin design system — your plugin’s styling uses the same Tailwind color palette, spacing scale, border radius, and typography conventions as the rest of the admin. No custom CSS, no arbitrary color values, and no overrides to global styles.

​
Directory hygiene

  • Plugin directory is self-contained under src/plugins/[plugin-name]/ — all plugin code lives inside your plugin’s dedicated subdirectory. Your plugin does not import from another plugin’s directory, does not place files outside its scope, and does not modify any file in src/plugins/core/ or src/core/.
Use the smart-price plugin at src/plugins/smart-price as your gold-standard reference when verifying each item on this checklist. It demonstrates every pattern correctly — from the Bridge HOC and scoped React Query keys to the adminApps structure and Firestore data conventions.

​
Next steps

Plugin Development

Step-by-step guide to building a custom Cartble plugin from directory structure to registration.

Architecture Reference

Deep dive into modularity, Firestore data conventions, React Query patterns, and the UI design system.