@fayz-ai/core

The headless kernel that turns plugin manifests into a running app.

Status: beta — published to npm and used across Fayz dogfood apps. Pre-1.0: minor APIs may change before 1.0.

A salon, a restaurant, and a clinic are the same engine with different plugins enabled. @fayz-ai/core is that engine — headless and UI-free. It defines the plugin contract, the entity/CRUD model, the data-provider abstraction, and the manifest format that describes an entire app as data. Plugins declare what they are; core resolves them into navigation, routes, widgets, and tools at runtime.

The bet: a SaaS app should be composable and portable, not hand-wired. Swap Supabase for the Fayz API or a mock with one provider call. Describe an app as a manifest and render it. Register an entity once and get list/form/detail behavior everywhere. Core is the substrate that makes plugins "snap in."

What's inside

• Plugin runtime — definePlugin, resolvePluginRuntime, getWidgetsForZone, getDashboardWidgets, PluginRuntimeProvider, PLUGIN_API_VERSION
• Data providers — createSupabaseProvider, createFayzApiProvider, createMockProvider, createArchetypeProvider, withCache, resolveDataProvider over one DataProvider interface
• Entity + registry — registerEntity, getEntityByKey, and the uniform Registry for components, blocks, pages, metrics, scaffolds, and plugin factories
• App manifest — defineApp, renderApp, migrateManifest, validateManifest, JSON schema, and a versioned migration runner
• Blocks — BlockRenderer / renderBlocks, the universal page primitive
• i18n + router — I18nProvider, useTranslation, hashRouterAdapter, windowRouterAdapter
• Event bus + utils — eventBus, useOnEvent, formatCurrency, exportCSV, tenant context (setActiveTenantId)

Install

npm install @fayz-ai/core

Peer deps: react, react-dom (^18 or ^19).

Usage

import { definePlugin, createSupabaseProvider } from '@fayz-ai/core'

const provider = createSupabaseProvider({ url, anonKey })

export const crmPlugin = definePlugin({
  id: 'crm',
  navigation: [{ label: 'Clients', path: '/clients' }],
  entities: [/* declarative data models */],
})

Part of the Fayz SDK

The headless core. @fayz-ai/auth, @fayz-ai/ui, and @fayz-ai/admin build the running app on top of it.

Roadmap & contributing

Built and evolving in the open. See the Fayz SDK roadmap for current gaps, missing features, and good first issues.