The two paths
There are two ways to build with the Fayz SDK, and picking the right one up front saves rework. Either you use the Fayz App — a complete admin shell assembled from your config — or you go Fayz Headless, consuming the core and the plugin bundles directly in your own project. Both use the same plugins and the same backend; what changes is who owns the shell around the plugins.
Rule of thumb: if the product is the management app (a multi-tenant SaaS, an admin), go with the Fayz App. If you already have your own site — a landing page, a store with a strong brand — and you just want to plug a few capabilities into it, go Headless.
Fayz App
You declare the app config — in app.manifest.json or in code with defineSaas — turn on a set of plugins, and get a finished app: admin shell, navigation generated from the plugins, tenant switching, permissions and CRUD screens. It's the fastest path to a complete multi-tenant product, and it's what fayz create admin generates for you.
import { defineSaas } from '@fayz-ai/saas'
import { createAgendaPlugin } from '@fayz-ai/plugin-agenda'
import { createCrmPlugin } from '@fayz-ai/plugin-crm'
export default defineSaas({
name: 'My Clinic',
plugins: [createAgendaPlugin(), createCrmPlugin()],
})
// → complete admin shell: navigation, tenants, permissions, CRUD
You get in through the Quickstart, which generates exactly this kind of app and boots it in mock mode. When consuming the packages in code, mock providers start out empty — Mock and sample data shows how to seed them.
Fayz Headless Beta
You import @fayz-ai/core and assemble the surfaces yourself, injecting the plugin bundles ({ manifest, Provider }) and serving their subpaths under /public. It's the path for a bespoke site — marketing, store, portal — that only wants a few Fayz capabilities without adopting the whole shell. The theme inherits from your own tokens, so the plugin looks like your site, not like the default admin.
The Headless path is real and in use, but it has less documentation than the Fayz App today. Expect to lean more on reading the types and the examples, and less on step-by-step guides, while it matures.
Comparison
| Fayz App | Fayz Headless | |
|---|---|---|
| Who builds the shell | the SDK (ready to go) | you, in your project |
| Navigation / routes | generated from the manifest | you wire up your own |
| Multi-tenancy + permissions | included | you integrate what you need |
| Theme | Fayz shell and tokens | inherits from your own tokens |
| Starting point | fayz create admin | a site you already have |
| Best for | SaaS / management admin | branded site + a few capabilities |
| Cost of entry | minimal — running in minutes | higher — you own the integration |
| Documentation today | complete | maturing |
What you gain with the Fayz App — shell, navigation, tenancy — is exactly what you give up control over. Headless inverts that: you control everything, and you pay for it by building the integration. Neither is "better"; it depends on whether the product is the management app or a site that consumes capabilities.