# ai-agent-rules: AI Agent Rules URL: /docs/ai-agent-rules Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/ai-agent-rules.mdx Canonical cross-agent execution contract for implementing features with docs + kit + examples. *** title: AI Agent Rules description: Canonical cross-agent execution contract for implementing features with docs + kit + examples. ----------------------------------------------------------------------------------------------------------- ## What It Does This page defines how coding agents should implement features in Creatorem using a single canonical rules contract and generated agent-specific adapters. ## When To Use * You want consistent behavior across Codex, Claude, Cursor, Windsurf, and other agents. * You want feature work to be capability-driven instead of guess-driven. * You want reusable implementation decisions (`kit/*`) with real integration patterns (`examples/*`). ## Prerequisites * Access to the repository root. * Access to docs capability endpoints (`/mcp-index.json`, `/llms.mdx/*`) when using MCP retrieval. Agents should use **capability-first retrieval**, then implement against **`kit/*` as source of truth**, and use **`examples/*` for composition patterns**. ## How To Use Use canonical contract as source of truth. Canonical contract path: ```text docs/agent-rules/creatorem-agent-rules.contract.v1.json ``` Consume an adapter for your coding agent. | Agent | Adapter file | | ------------ | -------------------------------------------------- | | Codex | `AGENTS.md` | | Claude | `CLAUDE.md` | | Cursor | `.cursor/rules/creatorem-agent-rules.mdc` | | Windsurf | `.windsurfrules` | | Other agents | `docs/agent-rules/adapters/generic-agent-rules.md` | Use MCP discovery before coding. 1. Read capability metadata from `/mcp-index.json`. 2. Resolve the target docs page(s). 3. Pull LLM-ready content from `/llms.mdx/*` only for selected pages. Map docs capabilities to implementation layers. | Capability family | Main implementation truth | Integration references | | -------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Filters architecture | `kit/utils/src/filters/*` + `kit/*/src/**/filters/*` | `apps/dashboard/hooks/use-filters.ts`, `apps/dashboard/lib/init-*-filters.ts`, `apps/mobile/hooks/use-filters.ts` | | Settings | `kit/settings/*` | `examples/pco-dashboard/*settings*`, `examples/pco-mobile/*settings*` | | Translations/i18n | `kit/i18n/*`, cross-env filters | `examples/pco-dashboard/config/i18n.config.ts`, `examples/pco-dashboard/lib/init-cross-env-filters.ts` | | Database workflow | root `package.json` db scripts + `supabase/*` | `docs/database`, `docs/scripts`, `.creatorem` schemas in examples | Maintain and validate adapters from canonical contract. ```bash pnpm --filter creatorem docs:agents:generate pnpm --filter creatorem docs:agents:check ``` ## Source Precedence If sources disagree, resolve in this order: 1. `kit/*` code and exports 2. docs contract pages (`MCP Context`, `Agent Recipe`) 3. `examples/*` integration implementations ## Filter-First Modularity Use filter composition as the default integration strategy before app-local implementation: 1. Define and verify filter signatures in `FilterList`. 2. Register filter callbacks in package filter modules. 3. Initialize filters in app entrypoints (`use-filters.ts`, `init-server-filters.ts`, `init-cross-env-filters.ts`). 4. Consume filters through `useApplyFilter` / `applyServerFilter` / `applyCrossEnv*`. When a feature already exposes filter integration points, do not hardcode equivalent behavior directly in app routes/components. See [Filter API](/docs/filters-api) for the full architecture and end-to-end wiring pattern. ## MCP Context ```yaml capability: agent_rules_contract entrypoints: - docs/agent-rules/creatorem-agent-rules.contract.v1.json - AGENTS.md - CLAUDE.md - .cursor/rules/creatorem-agent-rules.mdc - .windsurfrules - docs/agent-rules/adapters/generic-agent-rules.md - apps/creatorem/scripts/generate-agent-rules.mts - apps/creatorem/scripts/check-agent-rules.mts - apps/creatorem/app/mcp-index.json/route.ts - apps/creatorem/app/llms.mdx/[...slug]/route.ts inputs: - coding_task - capability_selection outputs: - deterministic_agent_execution_rules - synchronized_agent_adapter_files constraints: - canonical contract is the only editable source for adapter content - capability IDs referenced by rules must exist in mcp-index - path references in contract must resolve in repository side_effects: - adapter files are regenerated from canonical contract ``` ## Agent Recipe 1. Select capability IDs from `/mcp-index.json`. 2. Read target docs pages and extract implementation entrypoints. 3. Implement in `kit/*` first when behavior is reusable. 4. Wire app-level integration using existing example patterns. 5. Run validation commands and report exact execution status. ## Troubleshooting * If adapters are outdated, run `pnpm --filter creatorem docs:agents:generate`. * If contract checks fail on capability IDs, regenerate docs index and verify capability names. * If path references fail, update contract refs to real paths before regeneration. ## Related * [MCP Server](/docs/mcp-server) * [MCP Capabilities](/docs/web/mcp-capabilities) * [Documentation](/docs/web/features/documentation) # benefits: Benefits URL: /docs/benefits Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/benefits.mdx Why this codebase exists and what it optimizes for. *** title: Benefits description: Why this codebase exists and what it optimizes for. ---------------------------------------------------------------- ## What It Does Creatorem SaaS Kit gives you a production-ready monorepo baseline for web and mobile products with a unified data model, shared feature modules (`kit/*`), and repeatable setup workflows. If modern tools like Next.js, shadcn/ui, and Expo are the bricks, Creatorem is the cement that glues them together. ## When To Use * You want to ship a SaaS product quickly without rebuilding auth, settings, billing, i18n, and org primitives. * You want a monorepo where product teams and AI coding agents can work from stable conventions. * You want feature toggling through the CLI instead of manually pruning code. ## Prerequisites * Node.js `>=20` * `pnpm` workspace workflow * Docker Desktop (for local Supabase) ## For which environments ? Monorepo tools, paired with the React Native ecosystem, let you build web and native apps from one codebase. For that reason, Creatorem SaaS Kit is designed for: * **Web applications** powered by [Next.js](https://nextjs.org/) and [React](https://react.dev/). * **Native applications** powered by [Expo](https://expo.dev/) and [React Native](https://reactnative.dev/). Native applications implies **iOS** and **Android** mobile apps. Cross environment development ## Why should I use a toolkit if AI can code for me ? AI is a powerful tool and we are using it to improve our productivity. But we have to keep in mind that it useful only if a few use cases. ### Long answer An AI coding agent is trained on large datasets of code. During the training, the model will learn to generate code which will be the average of the code that have been used to train the model. So you won't get something perfect, but something close to the average. **Important:** Artificial intelligence is a statistical tool. Which means that when you enter a prompt, you will have a certain probability to get the right answer. But the 100% doesn't exist in the statistical world. **Make sure to check its work to make sure it is correct.** *It is a tool to help you, not to replace you.* With that in mind, it is easy to understand that AI should be used for simple and repetitive tasks only. If you need to build complex logic or design system, human is still the best. ### Short answer AI is nice to build simple MVPs, but it is impossible to build such easy to maintain, powerful and scalable applications with AI. People who say the opposite are **fools**. Even if a such AI exists, it would either take a lot of time to build or to be very expensive. ## Our mission The goal is to deploy applications as fast as possible. This includes : * you new projects * existing applications For that reason, all packages and the documentation are designed to easily implement features into new applications. To improve readability, some packages use a [config file](/docs/web/configuration) to configure the behavior of the package features. ## How To Use Start from CLI scaffolding or from this repository, then keep your product-specific logic in apps while reusing `kit/*` as the shared capability layer. ```bash npx @creatorem/cli create my-saas ``` ## MCP Context ```yaml capability: product_overview entrypoints: - README.md - cli/src/cli.tsx - kit/ inputs: - selected_apps - selected_features outputs: - monorepo_with_feature_set constraints: - architecture centered on kit/* reusable modules - apps consume kit APIs rather than reimplementing core logic side_effects: - creates or reshapes workspace structure ``` ## Agent Recipe 1. Read `README.md` and `cli/src/cli.tsx` to identify supported app and feature combinations. 2. Inspect `apps/dashboard/config/*` for real integration patterns. 3. Implement product changes by extending config and filters first, then pages/components. ## Troubleshooting * If features seem “missing”, verify what was selected through CLI manifests in `.creatorem/`. * If behavior differs across apps, compare each app’s `lib/init-*-filters.ts` wiring. ## Related * [Structure](/docs/structure) * [CLI](/docs/cli) * [Quickstart](/docs/web) # Fumadocs CLI (the CLI tool for automating Fumadocs apps): CLI URL: /docs/cli Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/cli.mdx Commands to bootstrap and reshape projects with feature-level control. *** title: CLI description: Commands to bootstrap and reshape projects with feature-level control. ----------------------------------------------------------------------------------- ## What It Does `@creatorem/cli` scaffolds and refactors monorepos using app + feature selection. It can also generate SQL artifacts from `.creatorem/setup.json` inputs. ## When To Use * Starting a new customer project. * Removing unused features from an existing repo. * Generating SQL schemas/migrations after setup changes. ## Prerequisites * `git` available in PATH. * `pnpm` workspace environment. * Run from monorepo root for `generate-sql` commands. This page describes the standard kit integration path; adapt app-specific paths and config names when your project differs. ## How To Use ### Core commands ```bash npx @creatorem/cli create creatorem create-dashboard my-dashboard --features ai,keybindings creatorem create-mobile my-mobile --features organization,onboarding creatorem generate-sql creatorem generate-schemas creatorem generate-migration ``` ### Important options * `--features`: comma-separated feature keys to keep. * `--edit`: mutate current app in place. * `--repo-scope`: also remove repo-level assets/dependencies for deselected features. * `--oss`: force OSS template source. ### Selectable apps | App | Description | | --------- | -------------------------------------------------------------------------------------------- | | Dashboard | Main SaaS dashboard (Next.js) | | Marketing | Landing / marketing website (Next.js) | | Mobile | React Native app (Expo) | | API | Standalone API server | | Examples | Optional real-case example apps from `examples/*` to bootstrap from concrete implementations | ### Selectable features Features are selected per app. Each one toggles UI components, database schemas, and kit packages. **Dashboard** | Key | What it adds | | ----------------- | ------------------------------------------------------------------------- | | `analytics` | Google Analytics and Umami support | | `monitoring` | Sentry integration | | `ai` | AI chat UI, tools, AI wallet and usage tracking | | `organization` | Teams, roles, member management, `` | | `notification` | Notification UI and database logic | | `billing` | Stripe and Lemon Squeezy, subscriptions, one-time payments, credit wallet | | `content-type` | Premade data-display components, search helpers, edit forms | | `keybindings` | Keyboard shortcut settings UI and React hooks | | `onboarding` | Post-signup information collection | | `email-templates` | React Email templates for auth and transactional emails | | `emailer` | Email sending via Nodemailer, Postmark, Resend, or Sendgrid | **Mobile** | Key | What it adds | | -------------- | ------------------------------------------------- | | `organization` | Teams, roles, member management (React Native) | | `notification` | Notification UI and database logic (React Native) | | `onboarding` | Post-signup information collection | ### Selectable examples If the source repository contains an `examples/` directory, the wizard can include one or more examples in the generated project. ### SQL generation behavior * `generate-schemas`: creates `supabase/app-schemas/*.sql`. * `generate-migration`: merges `supabase/schemas` + `supabase/app-schemas` into `supabase/migrations/_generated_from_schemas.sql`. * `generate-sql` defaults to migration mode. ## MCP Context ```yaml capability: project_generation_and_refactor entrypoints: - cli/src/cli.tsx - cli/src/commands/create*.tsx - cli/src/commands/generate-*.mjs inputs: - app_selection - feature_selection - setup_reference outputs: - generated_or_trimmed_monorepo - generated_sql_artifacts constraints: - feature keys must match command-specific feature registries - SQL generation expects supabase directory structure side_effects: - creates/deletes files - updates workspace deps and manifests ``` ## Agent Recipe 1. For new projects, run `create` and choose apps/features interactively. 2. For existing repos, use `create-dashboard --edit` or `create-mobile --edit` with explicit `--features`. 3. After schema/setup edits, run `creatorem generate-sql` from root. ## Troubleshooting * If `generate-sql` cannot find setup input, pass explicit path: `creatorem generate-schemas apps//.creatorem/setup.json`. * If repo cleanup is incomplete, rerun with `--repo-scope`. ## Related * [Database](/docs/database) * [Scripts](/docs/scripts) * [Quickstart](/docs/web) # database: Database URL: /docs/database Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/database.mdx Supabase + SQL workflow used by the kit. *** title: Database description: Supabase + SQL workflow used by the kit. links: Supabase: [https://supabase.com/](https://supabase.com/) -------------------------------------------------------- ## What It Does The kit uses Supabase/PostgreSQL with SQL-first schemas, generated app schemas, and generated migration bundles. ## When To Use * Adding or modifying tables/policies/functions. * Regenerating migrations after setup changes. * Running local database workflows. ## Prerequisites * Docker Desktop running locally. * Supabase CLI installed. Validate credentials, secrets, and runtime environment values before promoting changes to production. ## How To Use ### Core directories | Path | Purpose | | ---------------------- | -------------------------------------------------------------- | | `supabase/schemas` | Hand-written core kit SQL sources | | `supabase/app-schemas` | Hand-written core app SQL sources | | `supabase/migrations` | Generated merged migration file using `creatorem generate-sql` | | `supabase/tests` | SQL tests | ### Standard flow ```bash pnpm run supabase:start creatorem generate-sql pnpm run db:reset pnpm run db:types ``` ### Command details * `creatorem generate-sql`: reads app setup (`.creatorem/setup.json`), generates `supabase/app-schemas/*`, then assembles the merged migration file in `supabase/migrations/*`. * `pnpm run db:reset`: resets the local Supabase database, applies the generated SQL migration state, and rebuilds the local database from that SQL source. * `pnpm run db:types`: run this after `db:reset` with the Supabase Docker instance running; it generates TypeScript DB types from the current database state and refreshes Drizzle schema artifacts. ### Reset local database ```bash pnpm run db:reset ``` ## MCP Context ```yaml capability: database_workflow entrypoints: - supabase/schemas/ - supabase/app-schemas/ - supabase/migrations/ - creatorem generate-sql - package.json scripts (db:reset, db:types) inputs: - sql_sources - setup_json outputs: - generated_migration_sql - updated_local_database - refreshed_types constraints: - generated migration file should not be edited manually - ordering in supabase/schemas affects merge output side_effects: - writes SQL files - mutates local db state ``` ## Agent Recipe 1. Edit SQL sources or setup definitions. 2. Start local Supabase (`pnpm run supabase:start`) and keep it running. 3. Run `creatorem generate-sql`. 4. Run `pnpm run db:reset`. 5. Run `pnpm run db:types`. ## Troubleshooting * If migration output is empty, verify SQL files exist in `supabase/schemas` and/or generated app schemas. * If runtime queries fail after schema updates, regenerate types with `pnpm run db:types`. ## Related * [CLI](/docs/cli) * [Deployment](/docs/web/deployment) # filters-api: Filter API URL: /docs/filters-api Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/filters-api.mdx Typed filter architecture used to compose kit features into apps with high modularity. *** title: Filter API description: Typed filter architecture used to compose kit features into apps with high modularity. --------------------------------------------------------------------------------------------------- ## What It Does The Filter API is the composition layer between reusable packages (`kit/*`) and app runtime wiring (`apps/*`). Instead of hardcoding integrations inside each app, packages enqueue typed filter callbacks and apps initialize them at stable entrypoints. ## Why It Matters * Keeps package logic modular and reusable. * Lets apps add/remove behavior by initialization wiring, not by forking package code. * Gives AI and humans a deterministic integration contract (`FilterList` + init files). All filter names, parameters, and return types are declared in `kit/utils/src/filters/list.ts`. ## Core Model | Concept | Purpose | Source | | --------------- | -------------------------------------------------------------- | ---------------------------------------- | | `FilterList` | Typed contract for all filter slugs, params, and return values | `kit/utils/src/filters/list.ts` | | `FilterEngine` | Runtime add/remove/apply + priority ordering | `kit/utils/src/filters/filter-engine.ts` | | Filter callback | `(value, options) => nextValue` | `FilterCallback` / `AsyncFilterCallback` | | Priority | Lower values run earlier | `priority` on enqueue object | ## Environments and APIs | Environment | API | Typical usage | | ------------------- | ------------------------------ | ------------------------------------------------------------------------------- | | Client (web/mobile) | `@kit/utils/filters` | UI composition, provider wrappers, page-level runtime behavior | | Server | `@kit/utils/filters/server` | settings schema/provider registration, redirect logic, server query constraints | | Cross-env | `@kit/utils/filters/cross-env` | package translation namespaces and translation dictionary resolution | ## Initialization Entry Points ## How To Add a New Filter Declare the typed filter contract. Add your slug in `FilterList` with explicit params and return type. ```ts title="kit/utils/src/filters/list.ts" your_new_filter: { myParam: string; return: string[]; }; ``` Register/enqueue from a package filter module. ```ts useEnqueueFilter('your_new_filter', { name: 'myFilterRegistration', fn: (value, { myParam }) => [...value, myParam], }); ``` For server or cross-env filters, use `enqueueServerFilter` or `enqueueCrossEnvFilter`. Initialize in app entrypoints. * Client hooks in `hooks/use-filters.ts` * Server wiring in `lib/init-server-filters.ts` * Cross-env wiring in `lib/init-cross-env-filters.ts` * i18n resolver usage in `config/i18n.config.ts` (`applyCrossEnv*`) Consume the filter. * Client: `useApplyFilter`, `applyFilter`, `applyAsyncFilter` * Server: `applyServerFilter`, `applyServerAsyncFilter` * Cross-env: `applyCrossEnvFilter`, `applyCrossEnvAsyncFilter` ## Notification Push Filters | Filter | Parameters | Return | Consumer | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------- | | `server_notification_push_should_send` | `{ notificationId, notificationUserId, notificationType, notificationTitle, notificationBody, notificationData, deviceId, deviceUserId, devicePlatform, deviceProvider }` | `boolean` | `@kit/notification/shared/server/push-worker` | | `server_notification_push_map_payload` | `{ notificationId, notificationUserId, notificationType, notificationTitle, notificationBody, notificationData, iosSubtitle, iosBadgeCount, iosSoundName, androidChannelId, deviceId, devicePlatform, deviceProvider }` | `{ title?, body?, subtitle?, badge?, sound?, data?, channelId? }` | `@kit/notification/shared/server/push-worker` | Use these hooks to narrow delivery rules per app and to customize OS payloads without forking `@kit/notification`. ## MCP Context ```yaml capability: filter_api_architecture entrypoints: - kit/utils/src/filters/list.ts - kit/utils/src/filters/filter-engine.ts - kit/utils/src/filters/client/use-filters.tsx - kit/utils/src/filters/server.ts - kit/utils/src/filters/cross-env.ts - apps/dashboard/hooks/use-filters.ts - apps/dashboard/lib/init-server-filters.ts - apps/dashboard/lib/init-cross-env-filters.ts - apps/dashboard/config/i18n.config.ts - apps/mobile/hooks/use-filters.ts - apps/mobile/config/i18n.config.ts inputs: - target_feature_behavior - filter_namespace outputs: - typed_filter_registration_and_app_wiring constraints: - filter slug/params/return must match FilterList - app init entrypoints must enqueue required package filters side_effects: - runtime behavior is composed from package filters at app boot time ``` ## Agent Recipe 1. Identify filter namespace (`client`, `server`, `cross-env`) before editing code. 2. Confirm typed signature in `FilterList`. 3. Register filter in package module and initialize it in app entrypoints. 4. Verify consumption path (`useApplyFilter` / `applyServerFilter` / `applyCrossEnv*`). 5. Update feature docs with filter parameters when the integration changes. ## Troubleshooting * Behavior missing in one app usually means missing filter initialization in that app’s init files. * Wrong execution order means priorities are conflicting. * Filter not called often means slug mismatch between enqueue and apply calls. ## Related * [Configuration](/docs/web/configuration) * [Settings API Interest](/docs/settings-package-interest) * [AI Agent Rules](/docs/ai-agent-rules) # mcp-server: MCP Server URL: /docs/mcp-server Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/mcp-server.mdx Installable bridge that lets coding agents query Creatorem docs capabilities and page content. *** title: MCP Server description: Installable bridge that lets coding agents query Creatorem docs capabilities and page content. ----------------------------------------------------------------------------------------------------------- ## What It Does `@creatorem/mcp-server` exposes stable MCP tools over stdio so coding agents can: * list documentation capabilities from `/mcp-index.json` * resolve capability details and related pages * fetch LLM-ready page content from `/llms.mdx/*` * search capabilities by ID, title, tags, aliases, and description This server gives agents structured retrieval first, then full page content only when needed. ## When To Use * You want Claude/Cursor/VS Code agents to understand the Creatorem API surface quickly. * You want consistent, tool-based retrieval instead of prompt-only guessing. * You want to keep docs consumption aligned with the generated MCP capability index. ## Prerequisites * Node.js `>=20` * Access to your hosted docs endpoints (`/mcp-index.json`, `/llms.mdx/*`) ## Install And Configure Install or run directly with `npx`: ```bash npx @creatorem/mcp-server ``` Optional environment variables: ```bash CREATOREM_MCP_BASE_URL=https://creatorem.com CREATOREM_MCP_TIMEOUT_MS=10000 CREATOREM_MCP_CACHE_TTL_MS=60000 ``` Add it to your MCP client config. ```json title=".mcp.json" { "mcpServers": { "creatorem": { "command": "npx", "args": ["-y", "@creatorem/mcp-server"], "env": { "CREATOREM_MCP_BASE_URL": "https://creatorem.com" } } } } ``` Ask the agent to call MCP tools first, then retrieve full page content only for selected pages. ## Available Tools | Tool | Purpose | | ------------------------------- | ---------------------------------------- | | `creatorem.list_capabilities` | List/filter capability catalog | | `creatorem.get_capability` | Return one capability with related pages | | `creatorem.get_page_content` | Fetch LLM-ready text for a docs page | | `creatorem.search_capabilities` | Ranked search over capability metadata | ## Troubleshooting If tools return `UPSTREAM_UNAVAILABLE`, verify `CREATOREM_MCP_BASE_URL` and confirm `/mcp-index.json` is reachable. * If tool calls return `INVALID_INPUT`, check required keys (`capabilityId`, `pageUrl`, `query`). * If results are stale, lower `CREATOREM_MCP_CACHE_TTL_MS` during debugging. ## MCP Context ```yaml capability: mcp_server_integration entrypoints: - packages/mcp-server/src/cli.ts - packages/mcp-server/src/tools.ts - apps/creatorem/content/.generated/mcp-index.json - apps/creatorem/app/mcp-index.json/route.ts - apps/creatorem/app/llms.mdx/[...slug]/route.ts inputs: - mcp_client_configuration - docs_base_url outputs: - structured_docs_capability_retrieval - llm_ready_page_content_for_agents constraints: - requires Node.js 20+ - docs endpoints must be reachable from MCP client runtime side_effects: - outbound HTTP calls to docs endpoints ``` ## Related * [MCP Capabilities](/docs/web/mcp-capabilities) * [Documentation](/docs/web/features/documentation) # scripts: Scripts URL: /docs/scripts Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/scripts.mdx Root-level commands you will run every day. *** title: Scripts description: Root-level commands you will run every day. -------------------------------------------------------- ## What It Does The root `package.json` scripts coordinate build/dev/lint/typecheck/test and database workflows across the monorepo. ## When To Use * Starting local development. * Running CI-equivalent checks locally. * Generating DB artifacts. ## Prerequisites * Run from monorepo root. * Install dependencies first. This page describes the standard kit integration path; adapt app-specific paths and config names when your project differs. ## How To Use ### Core development ```bash pnpm dev pnpm build pnpm test pnpm typecheck ``` ### Code quality (Biome) ```bash pnpm lint pnpm lint:fix pnpm format pnpm format:fix pnpm check ``` ### Database and Supabase ```bash creatorem generate-sql pnpm run supabase:start pnpm run supabase:stop pnpm run db:reset pnpm run db:types ``` `db:reset` regenerates the SQL migration file from the app selection and setup, then resets the local Supabase database with that generated SQL. Run `db:types` when the local Supabase Docker instance is started. It generates TypeScript database types and refreshes Drizzle schemas from the currently generated and applied SQL migration state. ## MCP Context ```yaml capability: repo_task_execution entrypoints: - package.json scripts inputs: - task_type outputs: - workspace_build_or_validation_result constraints: - commands assume workspace tooling installed - db tasks assume supabase cli + docker availability side_effects: - may generate artifacts and cache files ``` ## Agent Recipe 1. Use `pnpm check && pnpm typecheck` before proposing commits. 2. For database changes, run `creatorem generate-sql` then validation commands. 3. Use `pnpm dev` for multi-app local development. ## Troubleshooting * If `supabase:start` fails, start Docker and retry. * If type errors reference stale DB types, run `pnpm run db:types`. ## Related * [Database](/docs/database) * [CLI](/docs/cli) * [Quickstart](/docs/web) # settings-package-interest: Settings API Interest URL: /docs/settings-package-interest Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/settings-package-interest.mdx Why the settings architecture matters and how it removes duplicate logic. *** title: Settings API Interest description: Why the settings architecture matters and how it removes duplicate logic. -------------------------------------------------------------------------------------- ## What It Does `@kit/settings` centralizes settings schema, storage mapping, form rendering, and retrieval for both server and client usage. Manual settings pages are typically **painful**, **error-prone**, and **hard to maintain**. The package removes most of that duplication. ## When To Use * You need user/organization settings pages. * You need typed settings reads in server routes/actions. * You need typed settings reads in client components/hooks. ## Prerequisites * A schema defined with `parseSchemaSettingConfig`. * App server filters enqueueing schema into `server_get_settings_schema`. ## Architecture Snapshot To solve this, we chose an architecture close to a MVC (Model-View-Controller) architecture. Settings architecture schema That way, you just have to define your settings in a type-safe object and you are good to go. The settings UI, storage management and settings fetching is handled by the package. The settings configuration is made of 3 objects from : * a UI config object that control the ui (found in `settings.ui.config.ts` file) * a schema config object that define zod schemas used for type checking (found in `settings.schema.config.ts` file) * a server config object that contains the database controllers (found in `kit/shared/src/config/settings.server.config.ts` file) ## How To Use Define schema. ```ts import { parseSchemaSettingConfig } from '@kit/settings/schema-config'; import { z } from 'zod'; export const settingsSchemas = parseSchemaSettingConfig({ schema: { user_name: { schema: z.string().default(''), storage: 'user_attributes' }, theme: { schema: z.enum(['light', 'dark', 'system']), storage: 'user_settings' }, }, }); ``` Enqueue schema server-side. ```ts import { enqueueServerFilter } from '@kit/utils/filters/server'; enqueueServerFilter('server_get_settings_schema', { name: 'appSettingsSchema', priority: 1, fn: (input) => ({ schema: { ...input.schema, ...settingsSchemas.schema } }), }); ``` Read settings server-side. ```ts import { getServerSettings } from '@kit/settings/shared/server/get-server-settings'; type AppSettingsSchema = typeof settingsSchemas.schema; const settings = await getServerSettings({ settingKeys: ['theme', 'user_name'], }); ``` Read settings client-side. ```ts import { getClientSettings, useClientSettings } from '@kit/settings/shared'; type AppSettingsSchema = typeof settingsSchemas.schema; const initial = await getClientSettings({ clientTrpc, settingKeys: ['theme'], }); const query = useClientSettings({ clientTrpc, settingKeys: ['theme'], }); ``` ## MCP Context ```yaml capability: settings_architecture entrypoints: - kit/settings/src/shared/server/get-server-settings.ts - kit/settings/src/shared/client/get-client-settings.ts - kit/settings/src/shared/client/use-client-settings.ts - app/lib/init-server-filters.ts inputs: - setting_keys - schema_filter_registration outputs: - typed_settings_values constraints: - schema keys must be registered via server filter before reads - reads with empty key arrays return empty object side_effects: - none for reads ``` ## Agent Recipe 1. Check that requested keys exist in the effective schema filter output. 2. Use `getServerSettings` for server reads and `getClientSettings`/`useClientSettings` for client reads. 3. Keep writes inside settings forms/router actions to preserve validation + storage routing. ## Troubleshooting * `Missing settings schema for keys ...` means the app did not enqueue its schema in `init-server-filters`. * `any`-typed values usually indicate missing generic typing or missing module registry augmentation. ## Related * [Web Settings](/docs/web/features/settings) * [Keybindings](/docs/web/features/keybindings) # structure: Structure URL: /docs/structure Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/structure.mdx How the monorepo is organized and where to implement each concern. *** title: Structure description: How the monorepo is organized and where to implement each concern. ------------------------------------------------------------------------------- ## What It Does The repository separates runtime apps from reusable feature kits and shared configuration packages. ## When To Use * You need to locate the correct ownership boundary before editing code. * You are adding a feature and must decide app-level vs shared-level changes. ## Prerequisites * Basic Turborepo/pnpm workspace familiarity. This page describes the standard kit integration path; adapt app-specific paths and config names when your project differs. ## How To Use Use this mapping to decide where code should live. ### Monorepo Snapshot | Area | Purpose | | ----------------- | ------------------------------------------------------------------- | | `apps/*` | Product entrypoints (dashboard, marketing, mobile, api, docs site) | | `kit/*` | Reusable business capabilities (auth, settings, org, billing, etc.) | | `packages/shared` | App-shared config and glue (`@kit/shared`) | | `supabase/*` | Database schemas, generated app schemas, migrations, SQL tests | | `cli/*` | Project generation and feature-pruning automation | ### Package Snapshot Typical implementation flow: 1. Define shared schema/config in `packages/shared` or app config. 2. Register filters in app `lib/init-server-filters.ts` / `init-cross-env-filters.ts`. 3. Consume functionality in app routes/components. ## MCP Context ```yaml capability: repo_navigation entrypoints: - apps/ - kit/ - packages/shared/ - supabase/ - cli/ inputs: - feature_request outputs: - target_edit_locations constraints: - prefer kit reuse over app duplication - keep app-level code focused on composition/configuration side_effects: - none ``` ## Agent Recipe 1. Identify which runtime app is affected. 2. Check whether a `kit/*` module already owns the behavior. 3. Apply changes in the shared layer first, then app integration points. ## Troubleshooting * If an import path starts with `@kit/shared/*`, source files live under `packages/shared/src/*`. * If a feature works in one app and not another, compare filter initialization files. ## Related * [Benefits](/docs/benefits) * [Settings API Interest](/docs/settings-package-interest) * [Configuration](/docs/web/configuration) # Fumadocs Framework: Introduction URL: /docs/ui Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/index.mdx A bunch of react components built using the radix design system. *** title: Introduction description: A bunch of react components built using the radix design system. ----------------------------------------------------------------------------- ## Philosophy We enjoy using the [shadcn/ui](https://ui.shadcn.com) components library, built on top of the [radix primitive](https://www.radix-ui.com/primitives) components. This project must be seen as a complement to the *shadcn/ui* library. You will find in here : * components : missing components from the *shadcn/ui* library. * motion : custom animated components implemented with the [motion](https://motion.dev/) library. **Important:** Some of this components are only available with the [creatorem saas kit](/pricing). # mobile: Quickstart URL: /docs/mobile Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mobile/(root)/index.mdx Fastest path from clone to running the mobile app with dashboard API and local Supabase. *** title: Quickstart description: Fastest path from clone to running the mobile app with dashboard API and local Supabase. ----------------------------------------------------------------------------------------------------- ## What It Does This quickstart gets your native app running with the required backend dependencies (`apps/dashboard` + local Supabase). ## When To Use * First mobile setup on a new machine. * Verifying local environment after pulling repository updates. ## Prerequisites * Node.js `>=20` * `pnpm` * Docker Desktop * Xcode (iOS) and/or Android Studio (Android), depending on your target `apps/mobile` consumes APIs from `apps/dashboard`. The dashboard server must be running for authenticated flows and data reads. ## How To Use Install dependencies from repository root. ```bash pnpm install ``` Start local Supabase stack. ```bash pnpm run supabase:start ``` Prepare mobile env file. ```bash cp apps/mobile/.env.test apps/mobile/.env.local ``` Start dashboard API app. ```bash pnpm --filter ./apps/dashboard dev ``` Start Expo app. ```bash pnpm --filter ./apps/mobile dev ``` Optional platform targets: ```bash pnpm --filter ./apps/mobile ios pnpm --filter ./apps/mobile android ``` ## Capability Map | Capability | Main docs | | ---------------------- | ---------------------------------------------------------------------------- | | Mobile auth setup | [/docs/mobile/features/authentication](/docs/mobile/features/authentication) | | Mobile onboarding flow | [/docs/mobile/features/onboarding](/docs/mobile/features/onboarding) | | Mobile settings UI | [/docs/mobile/features/settings](/docs/mobile/features/settings) | | Mobile translations | [/docs/mobile/features/translations](/docs/mobile/features/translations) | ## MCP Context ```yaml capability: mobile_bootstrap entrypoints: - apps/mobile/.env.test - apps/mobile/package.json - apps/dashboard/app/api/trpc/[trpc]/route.ts inputs: - target_platform - local_env_values outputs: - running_mobile_app constraints: - apps/dashboard must run for API-backed mobile flows - docker is required for local supabase side_effects: - starts local services and dev servers ``` ## Agent Recipe 1. Install dependencies and start Supabase from repo root. 2. Copy `apps/mobile/.env.test` into `apps/mobile/.env.local`. 3. Start `apps/dashboard`, then start `apps/mobile` and verify app boot. ## Troubleshooting * If mobile auth/data calls fail, verify `EXPO_PUBLIC_DASHBOARD_URL` points to running dashboard server. * If Supabase auth fails immediately, verify `EXPO_PUBLIC_SUPABASE_API_URL` and anon key values. * If Google auth fails on iOS, verify `EXPO_PUBLIC_IOS_URL_SCHEMA` and Supabase provider config. ## Related * [Web Quickstart](/docs/web) * [Scripts](/docs/scripts) * [Database](/docs/database) # mobile: Onboarding URL: /docs/mobile/features/onboarding Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mobile/features/onboarding.mdx Configure and extend the mobile onboarding flow with schema, step config, and filters. *** title: Onboarding description: Configure and extend the mobile onboarding flow with schema, step config, and filters. --------------------------------------------------------------------------------------------------- ## What It Does `apps/mobile` uses a QuickForm stepper onboarding flow that runs before the main app stack. The flow is schema-driven and extensible via filters. ## When To Use * You need to collect user profile data before first app usage. * You need app-specific onboarding steps on top of the default flow. * You need route-level onboarding extensions (`/onboarding/[onboardingPath]`). ## Prerequisites * Authenticated user session. * `completedOnboarding` field available on user record. * `apps/mobile/config/onboarding.config.tsx` configured. ## Flow Overview * `app/(app)/_layout.tsx` redirects users with `!completedOnboarding` to `/onboarding`. * `app/onboarding/index.tsx` renders the default stepper flow. * `app/onboarding/[onboardingPath]/index.tsx` supports custom onboarding routes from filters. ## How To Use Define schema and default steps. ```tsx title="apps/mobile/config/onboarding.config.tsx" import { z } from 'zod'; export const onboardingSchema = { userImageUrl: z.string().optional().nullable(), userName: z.string().trim().min(1).max(64), userPhone: z.string().trim().max(16).optional().or(z.literal('')), userEmail: z.string().email(), userRole: z.enum(['designer', 'programmer', 'product_manager', 'tester', 'marketer']), }; export const onboardingStepsConfig = [ { type: 'step', label: 'User', settings: [ { type: 'user_media', slug: 'userImageUrl' }, { type: 'text', slug: 'userName', label: 'Name' }, { type: 'text', slug: 'userEmail', label: 'Email', disabled: true }, ], }, { type: 'step', label: 'Profession', settings: [{ type: 'question_select', slug: 'userRole' }], }, ]; ``` Render onboarding using schema/steps filters. ```tsx title="apps/mobile/app/onboarding/index.tsx" showLineNumbers {1,6,11,19} import { QuickForm } from '@kit/native-ui/quick-form'; import { applyAsyncFilter, useApplyFilter } from '@kit/utils/filters'; import { onboardingSchema, onboardingStepsConfig } from '~/config/onboarding.config'; const schema = useApplyFilter('get_onboarding_schema', onboardingSchema); const steps = useApplyFilter('get_onboarding_steps_config', onboardingStepsConfig, { clientTrpc }); const extraInputs = useApplyFilter('get_onboarding_extra_inputs', {}); ``` Update onboarding completion + redirect. Default submit path in `onboarding/index.tsx`: * calls `clientTrpc.updateUser.fetch(data)`; * refetches `getUser` query; * computes redirect via `applyAsyncFilter('on_onboarding_submit', '/', ...)`; * pushes final route. Add new fields and steps safely. 1. Add Zod field in `onboardingSchema`. 2. Add matching input node in `onboardingStepsConfig`. 3. Ensure submit handler forwards this field to API mutation. 4. If needed, register extra input component through `get_onboarding_extra_inputs` filter. ## Advanced Extension Points | Filter | Purpose | | ----------------------------- | -------------------------------------------------------------- | | `get_onboarding_schema` | Extend base schema without editing package internals. | | `get_onboarding_steps_config` | Insert/reorder/remove steps. | | `get_onboarding_extra_inputs` | Register custom QuickForm input components. | | `on_onboarding_submit` | Customize post-submit redirect + side effects. | | `render_onboarding_path` | Render custom route content in `/onboarding/[onboardingPath]`. | ## Filter API Mobile onboarding is extended through organization onboarding filters registered from the shared onboarding package layer. | Filter | Parameters | Return | Registered By (package file) | Initialized In (app entrypoint) | Environment | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------- | ----------- | | `get_onboarding_schema` | `{}` | `QuickFormSchemaMap` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/mobile/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `get_onboarding_steps_config` | `{ clientTrpc: TrpcClientWithQuery> }` | `QuickFormStepConfig[]` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/mobile/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `get_onboarding_extra_inputs` | `{}` | `SettingsInputsBase` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/mobile/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `render_onboarding_path` | `{ onboardingPath: string; clientTrpc: TrpcClientWithQuery>; queryClient: QueryClient; defaultSchema: QuickFormSchemaMap; defaultSteps: QuickFormStepConfig[] }` | `null \| { config: QuickFormConfig; inputs: SettingsInputsBase; onSubmit: (data: unknown) => Promise }` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/mobile/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `on_onboarding_submit` | `{ data: Record; clientTrpc: TrpcClientWithQuery>; queryClient: QueryClient }` | `string` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/mobile/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `get_translations` | `{ language: string; namespace: string }` | `Record \| null` | `kit/organization/src/native/filters/use-filters/use-translation-filters.tsx` | `apps/mobile/hooks/use-filters.ts` (`useOrgFilters`) | `client` | * Keep `useOrgFilters({ clientTrpc, orgConfig })` in `apps/mobile/hooks/use-filters.ts`. * Keep `applyAsyncFilter('get_translations', ...)` in `apps/mobile/config/i18n.config.ts`. ## MCP Context ```yaml capability: onboarding_mobile_flow entrypoints: - apps/mobile/config/onboarding.config.tsx - apps/mobile/app/onboarding/index.tsx - apps/mobile/app/onboarding/[onboardingPath]/index.tsx - apps/mobile/app/(app)/_layout.tsx - apps/mobile/hooks/use-filters.ts - apps/mobile/config/i18n.config.ts - kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx - kit/organization/src/native/filters/use-filters/use-onboarding-filters.tsx - kit/organization/src/native/filters/use-filters/use-translation-filters.tsx inputs: - onboarding_schema - onboarding_steps - onboarding_filter_overrides outputs: - gated_onboarding_experience constraints: - user fields in steps must exist in schema - completedOnboarding gating must stay consistent with app layout redirect side_effects: - updates user profile fields and onboarding completion status ``` ## Agent Recipe 1. Extend schema and steps in `onboarding.config.tsx`. 2. Add custom inputs/logic through onboarding filters instead of hardcoding package internals. 3. Verify `completedOnboarding` redirect behavior in `(app)/_layout.tsx` and onboarding submit path. ## Troubleshooting * If fields do not render, verify input type is registered in onboarding inputs map/filters. * If user always returns to onboarding, verify `updateUser` mutation persists completion fields and user query refresh occurs. * If custom onboarding path shows 404 (`Unmatched`), verify `render_onboarding_path` filter returns content. ## Related * [Retrieve User](/docs/mobile/features/authentication/retrieve-user) * [Settings](/docs/mobile/features/settings) * [Web Onboarding](/docs/web/features/onboarding) # mobile: Translations URL: /docs/mobile/features/translations Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mobile/features/translations.mdx Configure i18next translations in apps/mobile with package translation filters. *** title: Translations description: Configure i18next translations in apps/mobile with package translation filters. links: "i18next": "[https://www.i18next.com](https://www.i18next.com)" "react-i18next": "[https://react.i18next.com](https://react.i18next.com)" ------------------------------------------------------------------------- ## What It Does `apps/mobile` uses `@kit/i18n` with i18next and a custom resolver to merge: * app-local namespaces (`apps/mobile/locales/*`), * package namespaces injected through filters (`get_translations`). ## When To Use * You need multilingual UI in the mobile app. * You need to consume translation namespaces coming from kit packages. ## Prerequisites * `@kit/i18n` installed. * `apps/mobile/config/i18n.config.ts` configured. * `I18nProvider` mounted in root provider. This feature is implemented through the shared `@kit/i18n` package. Mobile setup mainly wires provider + resolver + namespaces. ## How To Use Define mobile i18n config and resolver. ```ts title="apps/mobile/config/i18n.config.ts" showLineNumbers {3,14,22,39} import { parseI18nConfig } from '@kit/i18n/config'; import { DEFAULT_LANG, SUPPORTED_LANGS } from '@kit/shared/config/defined-languages'; import { applyAsyncFilter } from '@kit/utils/filters'; import enCommon from '../locales/en/common.json'; import frCommon from '../locales/fr/common.json'; const translations = { en: { common: enCommon }, fr: { common: frCommon }, }; async function i18nResolver(language: keyof typeof translations, namespace: string) { const packageTranslations = await applyAsyncFilter('get_translations', null, { language, namespace, }); if (packageTranslations) { return packageTranslations; } const lang = language in translations ? language : 'en'; const ns = (namespace in translations[lang] ? namespace : 'common') as keyof (typeof translations)[typeof lang]; return translations[lang][ns] as Record; } export const i18nConfig = parseI18nConfig({ defaultLanguage: DEFAULT_LANG, languages: SUPPORTED_LANGS, namespaces: ['common', 'client', 'notification', 'order', 'product'], resolver: i18nResolver as (lang: string, namespace: string) => Promise>, }); ``` Mount provider at app root. ```tsx title="apps/mobile/components/providers/root-provider.tsx" showLineNumbers {1,8,16} import { I18nProvider } from '@kit/i18n/shared/provider'; import { i18nConfig } from '~/config/i18n.config'; import { getLocales } from 'expo-localization'; const locale = getLocales()[0]; const lang = locale?.languageCode; {children} ``` Use translations in components. ```tsx import { useTranslation } from 'react-i18next'; export function SettingsTitle() { const { t } = useTranslation('common'); return {t('settings.title')}; } ``` ## Package Translations `applyAsyncFilter('get_translations', ...)` is the integration point that lets package-level translations be resolved without duplicating JSON files in each app. If a requested namespace is provided by a package filter, the resolver uses it first. App-local fallback runs only when package translations are not returned. ## Filter API Mobile translation composition is driven by client filters resolved through `applyAsyncFilter('get_translations', ...)`. | Filter | Parameters | Return | Registered By (package file) | Initialized In (app entrypoint) | Environment | | ------------------ | ----------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------- | | `get_translations` | `{ language: string; namespace: string }` | `Record \| null` | `kit/auth/src/native/filters/use-filters/use-translation-filters.tsx`, `kit/organization/src/native/filters/use-filters/use-translation-filters.tsx` | `apps/mobile/hooks/use-filters.ts` (`useAuthFilters`, `useOrgFilters`) | `client` | * Keep `useAuthFilters()` and `useOrgFilters({ clientTrpc, orgConfig })` in `apps/mobile/hooks/use-filters.ts`. * Keep `applyAsyncFilter('get_translations', ...)` in `apps/mobile/config/i18n.config.ts`. ## MCP Context ```yaml capability: i18n_mobile_setup entrypoints: - apps/mobile/config/i18n.config.ts - apps/mobile/components/providers/root-provider.tsx - apps/mobile/hooks/use-filters.ts - kit/auth/src/native/filters/use-filters/use-translation-filters.tsx - kit/organization/src/native/filters/use-filters/use-translation-filters.tsx - apps/mobile/locales/* inputs: - language_code - namespace outputs: - translated_mobile_ui_strings constraints: - namespace must be declared in i18nConfig.namespaces - resolver should fallback to default language/namespace for missing keys side_effects: - none ``` ## Agent Recipe 1. Add/update locale JSON files under `apps/mobile/locales`. 2. Keep resolver fallback logic and package translation filter call in `i18n.config.ts`. 3. Ensure provider is mounted at root before translated components render. ## Troubleshooting * If all keys render raw (`foo.bar`), verify `I18nProvider` is mounted in root provider. * If package namespaces do not resolve, verify `get_translations` filters are initialized. * If language fallback is wrong, verify default language and supported language list. ## Related * [Web Translations](/docs/web/features/translations) * [Authentication](/docs/mobile/features/authentication) # Fumadocs Framework: Confirm Button URL: /docs/ui/components/confirm-button Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/confirm-button.mdx A high level component to handle the AlertDialog component when you need to confirm an action. *** title: Confirm Button description: A high level component to handle the AlertDialog component when you need to confirm an action. component: true links: 'Alert Dialog API': [https://www.radix-ui.com/docs/primitives/components/alert-dialog](https://www.radix-ui.com/docs/primitives/components/alert-dialog) -------------------------------------------------------------------------------------------------------------------------------------------------------- ## Benefits This component is a high level component. Which means that it is designed to simplify the usage of the AlertDialog component for a specific confirmation use case. This component is just a shortcut to a `AlertDialog` implementation. For that reason, we are not trying to replicate the **radix** design system here. If you need more heavy customization, you should use the `AlertDialog` component directly. ## Installation Make sure that the following shadcn/ui components are present in your project: * [AlertDialog](https://ui.shadcn.com/docs/components/alert-dialog) * [Button](https://ui.shadcn.com/docs/components/button) * [Form](https://ui.shadcn.com/docs/components/form) * [Input](https://ui.shadcn.com/docs/components/input) * [Label](https://ui.shadcn.com/docs/components/label) Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { ConfirmButton } from '@kit/ui/confirm-button'; ``` ```tsx showLineNumbers { console.log('Confirmation triggered!'); }} > Delete ``` ## Features * Built to avoid duplicated code. * Quickly add templates to fit your needs. * Support for write confirmation. ## API Reference # Fumadocs Framework: Number Input URL: /docs/ui/components/number-input Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/number-input.mdx An enhanced number input with keyboard, mouse wheel, and drag controls. *** title: Number Input description: An enhanced number input with keyboard, mouse wheel, and drag controls. component: true --------------- ## Installation Make sure that the following shadcn/ui components are present in your project: * [Input](https://ui.shadcn.com/docs/components/input) Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { DragWheelControls, NumberInputBase, NumberInputRoot, NumberInputUnit } from '@kit/ui/number-input'; ``` ```tsx showLineNumbers ``` Or you can use the `NumberInput` if you don't need that much customization. ```tsx showLineNumbers import { NumberInput } from '@kit/ui/number-input'; ``` ```tsx showLineNumbers ``` ## Features * Keyboard arrow key controls (↑↓) * Mouse wheel scrolling support * Click and drag vertical adjustment * Unit display support * Min/max value constraints * Decimal step increments * Accessible ARIA attributes ### Control step factor with the keyboard You can control the step factor with the keyboard by holding the `ALT`, `SHIFT`, or `CTRL` key. Number Input component anatomy ## Examples ### Horizontal Drag Switch the drag direction to horizontal. ### Custom Scale Control the sensitivity of the drag and wheel controls. ### Min/Max ### Base The `NumberInputBase` component is a simpler version of the `NumberInput` component without drag and wheel controls. ## API Reference We are exposing 2 components ### Root `NumberInputRootProps` ### Drag & Wheel Controls `DragWheelControlsProps` ### Base The input `type="number"` element. ### Unit `NumberInputUnitProps` ### All in one This component is a shortcut if you don't need heavy customization. `NumberInputProps` # Fumadocs Framework: Phone Input URL: /docs/ui/components/phone-input Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/phone-input.mdx A phone input component that simplifies the phone input. *** title: Phone Input description: A phone input component that simplifies the phone input. component: true kitRequired: true ----------------- ## Installation Install the following dependencies: We use the light-weight (145kB) [libphonenumber-js](https://www.npmjs.com/package/libphonenumber-js) library for the phone number validation. ```bash npm install libphonenumber-js ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Anatomy Phone Input component anatomy ## Usage ```tsx showLineNumbers import { PhoneInputRoot, PhoneInputBase, PhoneInputFlagMenu } from '@kit/ui/phone-input'; ``` ```tsx showLineNumbers ``` ## Features * International zip code suggestions * Flag menu * Phone number formatting ## API Reference ### Root `PhoneInputRootProps` ### Flag Menu Props: `Omit, 'children' | 'type' | 'role'>` ### Base The input component. Props: `React.InputHTMLAttributes` # Fumadocs Framework: Progression URL: /docs/ui/components/progression Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/progression.mdx A progression component to display scroll progress through content. *** title: Progression description: A progression component to display scroll progress through content. component: true --------------- ## Features * Scroll-based progress tracking * Circular and bar progress indicators * Smooth animations and transitions * Automatic content measurement * Programmatic scroll control * Responsive design ## Installation Install the following dependencies: We use `@radix-ui/react-slot` for component composition. ```bash npm install @radix-ui/react-slot ``` Make sure that the following shadcn/ui components are present in your project: * [Slot](https://www.radix-ui.com/primitives/docs/utilities/slot) Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { Progression, ProgressionBar, ProgressionCircle, ProgressionContent } from '@kit/ui/progression'; ``` ### Basic Example ```tsx showLineNumbers {/* Long content */} ``` ## API Reference ### Root The root component that provides the progression context. *No props* ### Circle Displays progress as a circular indicator with percentage text. ```tsx showLineNumbers ``` `ProgressionCircleProps` ### Bar Displays progress as a horizontal or vertical bar. ```tsx showLineNumbers ``` `ProgressionBarProps` ### Content Wraps the content you want to track scroll progress for. ```tsx showLineNumbers {/* Your content */} ``` `ProgressionContentProps` # Fumadocs Framework: QR Code URL: /docs/ui/components/qr-code Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/qr-code.mdx A compound component for generating QR codes with download functionality. *** title: QR Code description: A compound component for generating QR codes with download functionality. component: true --------------- ## Installation Install the following dependencies: We use `qrcode` for the QR code generation. ```bash npm install qrcode ``` Make sure that the following shadcn/ui components are present in your project: * [Button](https://ui.shadcn.com/docs/components/button) Copy and paste the following code into your project. Update the import paths to match your project setup. ## Anatomy QR Code component anatomy ## Usage ```tsx showLineNumbers import { QRCodeRoot, QRCodeFrame, QRCodePattern, QRCodeDownloadTrigger } from '@kit/ui/qr-code'; ``` ```tsx showLineNumbers
``` ## Features * Radix component architecture * Controlled and uncontrolled value support * Error correction level configuration (L, M, Q, H) * Download functionality with multiple image formats (PNG, JPEG, WebP) * TypeScript support with proper prop types ## Examples ### With an overlay ```tsx showLineNumbers
Your Logo
``` ## Troubleshooting It may be possible that your url is too long, or the overlay is too big. In that case try to increase the error correction level. As mentioned in the [QR Code library documentation](https://github.com/soldair/node-qrcode?tab=readme-ov-file#error-correction-level), a higher levels offer a better error resistance but reduce the symbol's capacity. | Level | Error resistance | | ----- | ---------------- | | L | \~7% | | M | \~15% | | Q | \~25% | | H | \~30% | ## API Reference ### Root Contains the context provider and a div element. We advise you to set the width of the QR code in this component using the `className` prop. ### Frame Contains the QR code frame. ### Pattern Contains the QR code SVG element. Props: `Omit, 'children'>` ### Overlay Add an overlay to make your QR code more attractive. ### Download Trigger # Fumadocs Framework: Quick Form URL: /docs/ui/components/quick-form Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/quick-form.mdx Avoid form redundancy by using a quick form component. *** title: Quick Form description: Avoid form redundancy by using a quick form component. component: true --------------- 80% of the time, when you dress a form using `react-hook-form` and `zod` : * We have to dress a zod schema * Set the `react-hook-form` hooks * Calling the same shadcn/ui [Form](https://ui.shadcn.com/docs/components/form) components : * FormField * FormItem * FormLabel * FormControl * FormMessage * ... * And we have to do it for each input we create, generating a lot of duplicated code The `QuickForm` component is a solution to this redundancy. Set your zod schema and your object config. Then let the component handle the rest. ## Installation Make sure that the following shadcn/ui components are present in your project: * [Button](https://ui.shadcn.com/docs/components/button) * [Form](https://ui.shadcn.com/docs/components/form) * [Input](https://ui.shadcn.com/docs/components/input) * [Label](https://ui.shadcn.com/docs/components/label) Copy and paste the following code into your project. Update the import paths to match your project setup. ## Features * Avoid form redundancy * Typescript auto-completion * Zod validation * Clean MVC architecture * Equivalent component for server side rendering in the kit. ## Usage
Quick Form workflow
```tsx showLineNumbers import { type QuickFormConfig } from '@kit/utils/quick-form'; import { QuickForm } from '@kit/ui/quick-form'; import { z } from 'zod'; ``` ```tsx showLineNumbers

Profile

Basic information

), settings: [ { type: 'text', slug: 'name', label: 'Name' }, { type: 'text', slug: 'email', label: 'Email' }, { type: 'phone', slug: 'phone', label: 'Phone' }, { type: 'textarea', slug: 'bio', label: 'Bio', description: 'Short bio (max 200 chars)', }, ], }, ], }} defaultValues={{ name: 'John Doe', email: 'john@example.com', phone: '', bio: '', }} onSubmit={(values) => { console.log('QuickForm submitted:', values); }} /> ``` ## API Reference ### Props `QuickFormComponentProps` ### Config `QuickFormConfig` # Fumadocs Framework: Ratio Preserver URL: /docs/ui/components/ratio-preserver Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/ratio-preserver.mdx A component that maintains aspect ratio and scales content to fit any viewport size while preserving proportions. *** title: Ratio Preserver description: A component that maintains aspect ratio and scales content to fit any viewport size while preserving proportions. component: true --------------- ## Features * **Responsive scaling**: Automatically scales content to fit available space * **Aspect ratio preservation**: Maintains exact width/height proportions * **Viewport adaptation**: Works seamlessly across all device sizes * **Transform-based scaling**: Uses CSS transforms for smooth scaling * **Context-aware**: Provides scaling information to child components ## Installation Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { RatioPreserver, RatioPreserverContent } from '@kit/ui/ratio-preserver'; ``` ```tsx showLineNumbers Example ``` ## Examples ### Device Mockup Integration Perfect integration with MutableDeviceMockupRoot for responsive device previews: **Device Mockup Integration** This component is commonly used with the [MutableDeviceMockupRoot](/docs/ui/motion/mutable-device-mockup) component to ensure device mockups look great on small screens. The scaling ensures the mockup remains readable and proportional regardless of the viewport size. ## How It Works The RatioPreserver component works by: 1. **Setting container aspect ratio** using `padding-top` percentage 2. **Calculating optimal scale** based on available width and height 3. **Applying CSS transform** to scale content proportionally 4. **Centering content** using absolute positioning and transforms The scaling calculation ensures content fits within the container while maintaining the exact aspect ratio specified. ## API Reference ### RatioPreserver ### RatioPreserverContent ## Accessibility * The component preserves all accessibility features of its children * Scaling does not affect screen reader navigation * Focus management remains intact during scaling * Interactive elements maintain their functionality ## Performance * Uses CSS transforms for hardware-accelerated scaling * Optimized with `requestAnimationFrame` for smooth updates * Minimal re-renders with efficient context usage * Scales content without affecting layout calculations # Fumadocs Framework: Skeleton URL: /docs/ui/components/skeleton Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/skeleton.mdx Loading placeholder component with shimmer animations. *** title: Skeleton description: Loading placeholder component with shimmer animations. component: true --------------- A skeleton component displays a placeholder while content is loading. ## Installation Copy and paste the following code into your project. Add the required shimmer animation styles to your `globals.css` file: ```css /* shimmer animation */ @keyframes shimmer-animation { 0% { background-position: var(--shimmer-start-x, -1000px) 0; } 100% { background-position: var(--shimmer-end-x, 1000px) 0; } } @theme { --animate-shimmer: shimmer-animation 2s linear infinite; } @utility shimmer-with-pulse { animation: shimmer-animation 2s linear infinite, var(--animate-pulse, pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite); } @utility animate-shimmer { --_shimmer-center: var(--shimmer-center, 0.65); /* 0.5 centered */ --_shimmer-width: var(--shimmer-width, 200px); --_shimmer-color: var(--shimmer-color, color-mix(in oklab, var(--color-opposite) 3%, transparent 100%)); --_reference: 50%; --_shimmer-half-width: calc(var(--_shimmer-width) / 2); --_lower-breakpoint: calc(var(--_reference) - var(--_shimmer-half-width)); --_upper-breakpoint: calc(var(--_reference) + var(--_shimmer-half-width)); --_main-breakpoint: calc(var(--_lower-breakpoint) + var(--_shimmer-width) * var(--_shimmer-center)); background-image: linear-gradient( 110deg, transparent 0%, transparent var(--_lower-breakpoint), var(--_shimmer-color) var(--_main-breakpoint), transparent var(--_upper-breakpoint), transparent 100% ); background-size: cover; background-repeat: no-repeat; } ``` Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { Skeleton } from '@kit/ui/skeleton'; ``` ```tsx showLineNumbers ``` ## Custom Shimmer Color Customize the shimmer color using the `--shimmer-color` CSS variable: ## API Reference # Fumadocs Framework: Speech Input URL: /docs/ui/components/speech-input Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/speech-input.mdx A compound component for capturing and transcribing audio input using the Web Speech API with real-time visualization. *** title: Speech Input description: A compound component for capturing and transcribing audio input using the Web Speech API with real-time visualization. component: true links: 'Web Speech API': [https://developer.mozilla.org/en-US/docs/Web/API/Web\_Speech\_API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API) ------------------------------------------------------------------------------------------------------------------------------------------------------ Speech Input is a compound component for capturing voice input with real-time transcription and animated audio visualization. Built on the Web Speech API with Radix design system principles. ## Features * **Real-time transcription** with interim and final results * **Animated equalizer** showing audio activity * **Flexible composition** using Radix compound components * **Browser support detection** with graceful fallbacks * **Language support** with customizable locales * **Callback hooks** for lifecycle events * **Keyboard editable** input field * **Cancellation support** to discard transcriptions ## Installation Install the following dependencies: ```bash npm install motion ``` Make sure that the following packages are present in your project: * [Radix UI Slot](https://www.radix-ui.com/primitives/docs/utilities/slot) Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ### Basic Setup ```tsx showLineNumbers import { SpeechInput, SpeechInputTrigger, SpeechInputBase, SpeechInputCancel } from '@kit/ui/speech-input'; console.log('Started listening')} onSpeechChange={(text) => console.log('Final:', text)} > ; ``` ### With Custom Components The `asChild` prop lets you compose with your own components: ```tsx showLineNumbers ``` ### Cancelling Input The `SpeechInputCancel` button discards the transcription and prevents the `onSpeechChange` callback: ```tsx showLineNumbers {/* Only enabled while listening */} ``` ## API Reference ### SpeechInput Root provider managing speech recognition state. ### SpeechInputTrigger Button to start/stop speech recognition. Supports `asChild` for composition. ### SpeechInputCancel Button to cancel recording and discard transcription. Disabled when not listening. ### SpeechInputEqualizer Animated equalizer showing real-time audio activity. ### SpeechInputBase Input field displaying transcribed text. Fully editable by keyboard. ## Troubleshooting | Issue | Solution | | ----------------------- | ------------------------------------------------------------------- | | Microphone blocked | Check browser permissions and grant microphone access | | No text appearing | Verify microphone works and Web Speech API is supported | | Language not recognized | Use valid language codes like `en-US`, `fr-FR`, `de-DE` | | Input not editable | Use `asChild` prop or ensure `SpeechInputBase` is properly composed | # Fumadocs Framework: Stepper URL: /docs/ui/components/stepper Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/stepper.mdx A stepper component to display step by step content. *** title: Stepper description: A stepper component to display step by step content. component: true --------------- ## Features * `react-hook-form` integration, validation and submit handling * Customizable style * Navigation controls ## Installation Install the following dependencies: For typing purposes, make sure that `react-hook-form` is installed. If you want to use an animated stepper, you need to install `motion`. Otherwise delete the `StepperMotionContent` component.
`bash npm install react-hook-form motion `
Make sure that the following shadcn/ui components are present in your project: * [Form](https://ui.shadcn.com/docs/components/form) * [Button](https://ui.shadcn.com/docs/components/button) * [Slot](https://www.radix-ui.com/primitives/docs/utilities/slot) Copy and paste the following code into your project. Update the import paths to match your project setup.
## Usage ```tsx showLineNumbers import { Stepper, StepperContent, StepperNext, StepperPrevious, StepperStep, StepperTrigger, } from '@kit/ui/stepper'; ``` ```tsx showLineNumbers <>{/* Step content 1 */} <>{/* Step content 2 */} <>{/* Step content 3 */}
``` ### Anatomy Stepper anatomy diagram ## Examples ### Motion You can easily animate step transitions using `motion` and its `AnimatePresence` component. To do that you need to use the `StepperMotionContent` component instead of the `StepperContent` component. ```tsx showLineNumbers {2-6} {/* Your steps come here ... */}
``` ### Form implementation The example at the top shows a simple stepper component with form validation and submit handling. Follow these instructions to properly implement the stepper component with form validation and submit handling. Declare the form methods and schema Optional: set `disableForwardNav` to `true` to disable the forward navigation, prevent your users to skip a step without validating the previous steps. We are using the `name` props of the `` children to detect which fields are present in the current step. For that reason, you have to use shadcn/ui's `` component to properly integrate your form. ```tsx showLineNumbers {1-5,8,13,15,32,34,50,63} const methods = useForm({ mode: 'onChange', resolver: zodResolver(yourSchema), defaultValues: { /* ... */ }, }); return (
( First Name )} /> ( Last Name )} /> {/* other steps come here ... */} {/* flex row reverse for focus control */}
); ``` ## Progress Bar variant Here are some premade progress bar that you can use or adapt to your needs. ### Simple ### Bullets ### Panels Borders ### Circles ### Connecting Lines ### Dots ### Panels Progress ## API Reference ### Root ### Content Props: `React.ComponentPropsWithoutRef<'div'>` ### MotionContent Motion version of the `StepperContent` component. Props: `{ children: React.ReactNode } & HTMLMotionProps<'div'>` ### Step Allow to define the content of a single step. Must be the direct child of StepperContent. `StepperStepProps` ### Previous Previous step button. `StepperPreviousProps` ### Next Next step button. `StepperNextProps` ### Trigger `StepperTriggerProps` ### ActiveStep A React Fragment that contains the active step number. ### StepLength A React Fragment that contains the number of steps. # Fumadocs Framework: Tour URL: /docs/ui/components/tour Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/tour.mdx A guided tour that helps users understand the interface. *** title: Tour description: A guided tour that helps users understand the interface. component: true links: 'Popover API': [https://www.radix-ui.com/docs/primitives/components/popover](https://www.radix-ui.com/docs/primitives/components/popover) ----------------------------------------------------------------------------------------------------------------------------------------- ## Installation Install the following dependencies: We use `motion/react` for the animations and `react-remove-scroll` is used by radix and shadcn/ui to prevent the scroll when the tour is open.
`bash npm install motion/react react-remove-scroll `
Make sure that the following shadcn/ui components are present in your project: * [Popover](https://ui.shadcn.com/docs/components/popover) * [Button](https://ui.shadcn.com/docs/components/button) Copy and paste the following code into your project. Update the import paths to match your project setup.
## Usage ```tsx showLineNumbers import { Tour, TourArrow, TourClose, TourContent, TourDescription, TourFrame, TourNext, TourOverlay, TourPortal, TourPrevious, TourProgress, TourTitle, TourTrigger, type TourStep, } from '@kit/ui/tour'; ```
```tsx showLineNumbers
```
## Features * Built on top of the shadcn/ui components, using the radix design system * Support for different step types such as "dialog" and "floating" * Support for customizable content per step * Flexible positioning of the tour dialog per step * Progress tracking shows users their progress through the tour ### Keyboard controls Tour component keyboard controls | Key | Action | | -------------------- | ------------- | | `ArrowRight` `Space` | Next step | | `ArrowLeft` | Previous step | | `Escape` | Close tour | ## API Reference ### Root Contains all the parts of the tour. ### Trigger An extended version of the [PopoverTrigger](https://www.radix-ui.com/primitives/docs/components/popover#trigger) component. ### Portal An extended version of the [PopoverPortal](https://www.radix-ui.com/primitives/docs/components/popover#portal) component. ### Frame The frame that wrap the highlighted element. Optional according your styling preferences. Takes `React.ComponentProps<'div'>` or `React.ComponentProps` props. ### Overlay The overlay that cover the entire screen except the highlighted element. ### Content Takes the same props as the [PopoverContent](https://www.radix-ui.com/primitives/docs/components/popover#content) component. Calls the `RemoveScroll` component to prevent the scroll when the tour is open. When the `dialogDisplay` is true, it display another `div` different than the `PopoverContent` component to display the dialog. *We are calling the preventDefault method on the `onInteractOutside` prop to prevent the tour from being closed when the user clicks on the dialog.* ### Title To display the title of the active step. Props : `React.HTMLAttributes`. ### Description To display the description of the active step. Props : `React.HTMLAttributes`. ### Progress A progress component to show which step the user is on. ### Arrow An extended version of the [PopoverArrow](https://www.radix-ui.com/primitives/docs/components/popover#arrow) component. ### Close A button to close/skip the tour. `TourCloseProps` ### Previous `TourPreviousProps` ### Next `TourNextProps` # Fumadocs Framework: Use Copy To Clipboard URL: /docs/ui/hooks/use-copy-to-clipboard Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/hooks/use-copy-to-clipboard.mdx A simple hook to copy to clipboard. *** title: Use Copy To Clipboard description: A simple hook to copy to clipboard. component: false ---------------- ## Installation Copy and paste the following code into your project. ## Usage ```tsx showLineNumbers import { useCopyToClipboard } from '@kit/utils/hooks/use-copy-to-clipboard'; ``` ```tsx showLineNumbers const { copyToClipboard, isCopied } = useCopyToClipboard(); return ( ); ``` ## API Reference Nothing special here. # Fumadocs Framework: Delay URL: /docs/ui/hooks/use-delay Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/hooks/use-delay.mdx Delay your react states. *** title: Delay description: Delay your react states. component: false ---------------- Delay a state update. Very handy for animations and other UI effects. ## Installation Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { useDelay, useFnDelay } from '@kit/ui/hooks/use-delay'; ``` ```tsx showLineNumbers const [count, setCount] = useState(0); const delayedCount = useDelay(count, 1000); // function approach const conditionalDelayResult = useFnDelay( async (delay) => { if (count < 5) return count; await delay(2000); return count; }, [count] ); ``` ## API Reference ### useDelay Takes : `(value: T, delayMs: number) => T` ### useFnDelay Takes : ```ts (asyncFactory: (delay: (timeMs: number) => Promise) => Promise, deps: React.DependencyList) => T; ``` # Fumadocs Framework: Input Drag Control URL: /docs/ui/hooks/use-input-drag-control Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/hooks/use-input-drag-control.mdx Update a number using drag controls *** title: Input Drag Control description: Update a number using drag controls component: false ---------------- This component is used in the [Number Input](/docs/ui/components/number-input) component to implement the drag behavior. ## Installation Copy and paste the following code into your project. Nothing else, no dependencies. ## Usage ```tsx showLineNumbers import { useInputDragControl } from '@kit/ui/hooks/use-input-drag-control'; ``` ```tsx showLineNumbers const { handleMouseDown, isDragging } = useInputDragControl({ containerRef: localRef, value: currentValue, step, min, max, onDrag: onValueChange, dragScale, lockToStep, dragDirection, }); ``` Look at the [API Reference](#api-reference) for more details on the parameters. ## Features * Drag controls * Inifnite drag * Keyboard support * Scale, direction, step customization ### Control step factor with the keyboard You can control the step factor with the keyboard by holding the `ALT`, `SHIFT`, or `CTRL` key. Number Input component anatomy ## API Reference `UseInputDragControlParams` # Fumadocs Framework: Dialog URL: /docs/ui/motion/dialog Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/motion/dialog.mdx An animated dialog component powered by motion. *** title: Dialog description: An animated dialog component powered by motion. component: true links: 'Motion Layout': [https://motion.dev/docs/react-layout-animations](https://motion.dev/docs/react-layout-animations) ------------------------------------------------------------------------------------------------------------------- ## Features * Seamless transition between trigger and content * Radix component architecture * Handle open state logic internally * Remove scrollbar when the dialog is open ### Netflix card ### Images A dialog component providing a user experience close to a native app animation. It gives the illusion that the element is always present in the viewport during the transition to a `fixed` position. We are using the [motion layout](https://motion.dev/docs/react-layout-animations) layoutId props to create seamless "magic motion" effects between two separate elements ## Installation Install the following dependencies: We use `motion/react` and `framer-motion` for animations, as well as `react-remove-scroll` to prevent the scroll when the dialog is open. ```bash npm install motion/react framer-motion react-remove-scroll ``` Make sure that the following radix [portal](https://www.radix-ui.com/primitives/docs/utilities/portal) is present in your project Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ### Anatomy ```tsx showLineNumbers import { Dialog, DialogAnimatePresenceDiv, DialogContent, DialogMotionImage, DialogMotionImageWrapper, DialogOverlay, DialogPortal, DialogTrigger, } from '@kit/ui/motion/dialog'; ``` ```tsx showLineNumbers ``` Creatorem Dialog component anatomy ### How it works **Here is a short explanation of how layout animations are handled in `motion`.** Let's call : * *origin* : the original element * *target* : the target element having the style that we would like to transition to. To give the illusion that the element is always present in the viewport, `motion` looks at the future and present (position, size) of the *origin* and *target* before the animation is applied. Knowing that, `motion` will do several operations at the same time: * on the *origin* : * apply animated `translate` and `scale` transformations to fit the future (position, size) * use a fade-out to smoothly make it disappear * on the *target* : * apply animated `translate` and `scale` transformations to fit the *origin* (position, size) * use a fade-in to smoothly make it appear As the fade-out of the *origin* and the fade-in of the *target* are place on top of each other (by making sure that they share the same (position, size)), it gives the illusion that the element is always present in the viewport. Finally, `motion` use the `layoutId` to know which *origin* and *target* are related to each other. A *target* is a `motion` component wrapped in an `` component. Better you will understand how [motion layout](https://motion.dev/docs/react-layout-animations) works, the better you will be able to use this component. Here is a schema that tries to illustrate what we said above: Dialog motion layout schema ### Layout vs non-layout components In this page, what we call a *layout* component is a component that will be present in the *origin* and the *target* and that will be animated during the transitions to the new position. Non-layout components are : * components that will be present in the *target* only * non-motion components * motion components without a `layoutId` prop The dialog component is based on the layoutId props. For that reason, a layout component is not just a motion component with the `layout` attribute, the `layoutId` is required. | Layout component | Non-layout component | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `DialogTrigger`, `DialogContent`, `MotionImageWrapper`, `MotionImage`,`DialogMotionDiv` (with a `layoutId` prop) | `DialogAnimatePresenceDiv`, `DialogOverlay`, `DialogPortal`, `DialogClose`, `DialogMotionDiv` (without `layoutId`) | ## Examples ### Variant 1 ### Variant 2 ## Tailwind animation The components are built to animate components with css and tailwindcss. Each one of our components has a `data-open` attribute that you can use to animate your content with tailwind. To have a better understanding of how it works, here is a timeline of the animation: Dialog timeline **When opening** We change the `data-open` to `true` after adding the *DialogContent* to the react tree to be able to trigger transitions with the `data-open` attribute. **When closing** For the same reason, we change the `data-open` to `false` before removing the *DialogContent* from the react tree to be able to trigger transitions with the `data-open` attribute before the content is removed. ### CSS variables We are exposing css variables to access the animation duration that you passed to the component. | Variable | Value | | ---------------------- | ----------------------------- | | `--dialog-duration` | The duration of the animation | | `--dialog-duration-95` | 95% of the animation duration | | `--dialog-duration-90` | 90% | | `--dialog-duration-80` | 80% | | `--dialog-duration-70` | 70% | | `--dialog-duration-60` | 60% | | `--dialog-duration-50` | 50% | | `--dialog-duration-40` | 40% | | `--dialog-duration-30` | 30% | | `--dialog-duration-20` | 20% | | `--dialog-duration-10` | 10% | ### Classname usage You can use the `data-open` attribute to animate your content with tailwind. The following examples are equivalent: ```tsx showLineNumbers {children} ``` ```tsx showLineNumbers {children} ``` If you want to animate other component, use the parent group. * the `dialog-trigger` group for trigger children * the `dialog` group for content children ```tsx showLineNumbers
{children}
``` ## Troubleshooting ### Why do we use an ImageWrapper ? `motion` uses the scaleX and scaleY transform properties to change the size of the element. This may lead to deformation of the element, making it hard to properly render images. Wrapping the image with position `absolute` in a `relative` container avoid this issue. This requires several things: * the image must be bigger than the wrapper * set yourself the x and y position of the image to make it covers the entire `relative` wrapper ## API Reference ### Root `DialogProps` ### Trigger The *Trigger* has the same `layoutId` than the *Content* component. Props: `Omit, 'layoutId' | 'transition'> & React.PropsWithChildren` ### Content The *Content* has the same `layoutId` than the *Trigger* component. ### MotionImageWrapper ### MotionImage ### MotionDiv Wrapping a text with this component avoid deformation. Props: `HTMLMotionProps<'div'>` ### AnimatePresenceDiv Used to animate new content (not present in the *origin*) in the dialog content. We are using a local `` and open state effect to trigger `motion` *initial*, *animate* and *exit* animation states. `DialogAnimatePresenceDivProps` ### Overlay Props: `Omit, 'layoutId'>` ### Portal The radix [portal](https://www.radix-ui.com/primitives/docs/utilities/portal) component. ### Close Props: `HTMLMotionProps<'button'>` # Fumadocs Framework: Glow SVG URL: /docs/ui/motion/glow-svg Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/motion/glow-svg.mdx Apply glowing effects to SVG elements with cursor tracking. *** title: Glow SVG description: Apply glowing effects to SVG elements with cursor tracking. component: true --------------- ## Installation Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { Glow, GlowSvg } from '@kit/ui/motion/glow-svg'; ``` ```tsx showLineNumbers ``` ## Features * Cursor-responsive glow effects for SVG elements * Radial gradient masks that follow mouse movement * Customizable colors and radius * Local or global positioning modes * Smooth transitions and animations ## API Reference ### Glow (Root) ### GlowDiv # Fumadocs Framework: Glow URL: /docs/ui/motion/glow Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/motion/glow.mdx Add a glowing effect to your components. *** title: Glow description: Add a glowing effect to your components. component: true --------------- ## Installation Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { Glow, GlowingDiv } from '@kit/ui/motion/glow'; ``` ```tsx showLineNumbers
``` ## Features * Efficient and performant animations * Powered by motion library * Use SVG mask feature for efficient rendering ## API Reference ### Props ### Root ### Div # Fumadocs Framework: Liquid Glass URL: /docs/ui/motion/liquid-glass Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/motion/liquid-glass.mdx Simulate light refraction respecting the Snell laws. Same effect used in iOS 26. *** title: Liquid Glass description: Simulate light refraction respecting the Snell laws. Same effect used in iOS 26. component: true links: 'Motion React': [https://motion.dev/docs/react-quick-start](https://motion.dev/docs/react-quick-start) ------------------------------------------------------------------------------------------------------ This liquid component is based on the incredible work made by Chris in this blog post : [https://kube.io/blog/liquid-glass-css-svg/](https://kube.io/blog/liquid-glass-css-svg/) This component is experimental, there is still issues that we need to fix to support all different sizes and border radius values. `@creatorem/web-glass-effect` ships this component (plus slider, switch, filter, and surface helpers) as a standalone package. ```bash pnpm add @creatorem/web-glass-effect motion ``` ```tsx showLineNumbers import '@creatorem/web-glass-effect/styles.css'; import { LiquidGlass, useLiquidSurface } from '@creatorem/web-glass-effect'; ``` If you're working inside this monorepo, you can still use the `@kit/ui/...` imports. A comprehensive glass effect system that can transform any content with realistic liquid glass visual effects. Features automatic sizing, responsive updates, and both component and hook-based APIs for maximum flexibility. ## Installation ### Option 1: Install package (recommended) ```bash pnpm add @creatorem/web-glass-effect motion ``` ```tsx showLineNumbers import '@creatorem/web-glass-effect/styles.css'; import { LiquidGlass, useLiquidSurface } from '@creatorem/web-glass-effect'; ``` ### Option 2: Copy source files Copy and paste the following code into your project. Copy the liquid filter component. Copy the liquid utilities library. Update the import paths to match your project setup. ## Usage ### Component API ```tsx showLineNumbers import { LiquidGlass } from '@creatorem/web-glass-effect'; ``` #### Basic usage ```tsx showLineNumbers

Glass Content

This content appears behind realistic glass.

``` ### Hook API ```tsx showLineNumbers import { useLiquidSurface } from '@creatorem/web-glass-effect'; ``` #### Hook basic usage ```tsx showLineNumbers function FlexibleGlass() { const { Filter, filterStyles, ref } = useLiquidSurface({ glassThickness: 50, }); return ( <>
Content with glass effect
); } ``` ## Examples ### Form Integration This example demonstrates how to integrate LiquidGlass with form components like inputs, textareas, and select dropdowns for a cohesive glass effect throughout your forms. ### Integration Patterns The examples show three main integration patterns: 1. **Wrapper Component**: Using `` as a container 2. **Hook Integration**: Using `useLiquidSurface()` for existing components 3. **Overlay Pattern**: Positioning LiquidGlass as an overlay with absolute positioning ### Interactive Playground Experiment with different glass properties in real-time to understand how each parameter affects the liquid glass appearance. The playground includes: * **Visual feedback**: See changes instantly as you adjust sliders * **Background imagery**: Rich background to showcase refraction effects * **Preset configurations**: Quick access to light, medium, and heavy glass effects * **Parameter explanations**: Understand what each property controls ## Surface Functions Different surface functions create unique glass edge profiles. Each function defines how the bezel height changes from edge to center: ## Browser Compatibility Only chromium browsers support usage of a svg filter with the backdrop filter property. It represent about 75% of the users in 2025. Meaning the liquid feature won't work on safari (about 18% in 2025) and firefox (2.6% in 2025). ## Troubleshooting ### FPS impact It is important to be aware that a too big `LiquidGlass` component will consume to much ressources and may slow down your website. ### Glass Effect Not Visible If you can't see the glass effect, check these common issues: #### Border Radius Requirement The liquid glass component **requires a border radius** to function properly. Without it, the glass effect may not render correctly. ```tsx showLineNumbers // ❌ Won't work properly - no border radius Content // ✅ Works correctly - has border radius Content ``` #### Minimum Border Radius for Spectacle Effect For the **spectacular border effect** to work properly, you need a minimum border radius of **26px**: ```tsx showLineNumbers // ❌ Too small - spectacle effect may not work {/* 2px radius */} Content // ⚠️ Minimal - basic glass effect only {/* 12px radius */} Content // ✅ Optimal - full spectacle effect Content ``` ### Performance Issues If you experience performance issues: * **Reduce `glassThickness`** - Lower values require less computation * **Decrease `blur`** - High blur values can impact performance * **Limit concurrent instances** - Multiple glass components may affect performance * **Use `useMemo`** for complex content inside the glass component ### Glass Effect Appears Distorted If the glass effect looks wrong: * **Check container dimensions** - Ensure the component has proper width/height * **Verify border radius** - Very large radius values relative to size can cause issues * **Adjust `bezelWidth`** - Should be proportional to the component size * **Test `refractiveIndex`** - Extreme values (\< 1.0 or > 3.0) may cause artifacts ## API Reference ### LiquidGlass Component ### useLiquidSurface Hook The hook returns an object with: * `Filter`: React component to render the SVG filter * `filterStyles`: CSS styles to apply the glass effect * `ref`: Ref to attach to the target element (if no targetRef provided) * `filterId`: Unique ID of the generated filter ```tsx const { Filter, filterStyles, ref, filterId } = useLiquidSurface(props); ``` # Fumadocs Framework: Liquid Slider URL: /docs/ui/motion/liquid-slider Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/motion/liquid-slider.mdx A liquid glass-effect slider component with smooth animations and customizable appearance. *** title: Liquid Slider description: A liquid glass-effect slider component with smooth animations and customizable appearance. component: true links: 'Motion React': [https://motion.dev/docs/react-quick-start](https://motion.dev/docs/react-quick-start) ------------------------------------------------------------------------------------------------------ This liquid component is based on the incredible work made by Chris in this blog post : [https://kube.io/blog/liquid-glass-css-svg/](https://kube.io/blog/liquid-glass-css-svg/) This component is experimental, there is still issues that we need to fix to support all different sizes and border radius values. `@creatorem/web-glass-effect` ships `LiquidSlider` as a standalone package. ```bash pnpm add @creatorem/web-glass-effect motion ``` ```tsx showLineNumbers import '@creatorem/web-glass-effect/styles.css'; import { LiquidSlider } from '@creatorem/web-glass-effect'; ``` If you're working inside this monorepo, you can still use the `@kit/ui/...` imports. A slider component that combines the functionality of a traditional range slider with a stunning liquid glass visual effect. The component features realistic refraction, smooth animations, and customizable appearance. ## Installation ### Option 1: Install package (recommended) ```bash pnpm add @creatorem/web-glass-effect motion ``` ```tsx showLineNumbers import '@creatorem/web-glass-effect/styles.css'; import { LiquidSlider } from '@creatorem/web-glass-effect'; ``` ### Option 2: Copy source files Install the following dependencies: We use `motion` for animations and `@kit/utils` for utility functions. ```bash npm install motion ``` Copy and paste the following code into your project. Copy the liquid filter component. Copy the liquid utilities library. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { LiquidSlider } from '@creatorem/web-glass-effect'; ``` ### Basic usage ```tsx showLineNumbers ``` ### With custom size ```tsx showLineNumbers ``` ### With custom glass properties ```tsx showLineNumbers ``` ## Examples ### Sizes The component comes with four size presets: * `xs`: Compact size for dense interfaces * `sm`: Small size for secondary controls * `md`: Default medium size * `lg`: Large size for primary controls ### Glass Effects The liquid glass effect is created using SVG filters that simulate: * **Refraction**: Light bending through the glass surface * **Blur**: Realistic glass distortion * **Specular highlights**: Glossy surface reflections * **Scale transformations**: Dynamic size changes on interaction ## API Reference # Fumadocs Framework: Liquid Switch URL: /docs/ui/motion/liquid-switch Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/motion/liquid-switch.mdx A toggle switch component with liquid glass visual effects and smooth animations. *** title: Liquid Switch description: A toggle switch component with liquid glass visual effects and smooth animations. component: true links: 'Motion React': [https://motion.dev/docs/react-quick-start](https://motion.dev/docs/react-quick-start) ------------------------------------------------------------------------------------------------------ This liquid component is based on the incredible work made by Chris in this blog post : [https://kube.io/blog/liquid-glass-css-svg/](https://kube.io/blog/liquid-glass-css-svg/) This component is experimental, there is still issues that we need to fix to support all different sizes and border radius values. `@creatorem/web-glass-effect` ships `LiquidSwitch` as a standalone package. ```bash pnpm add @creatorem/web-glass-effect motion ``` ```tsx showLineNumbers import '@creatorem/web-glass-effect/styles.css'; import { LiquidSwitch } from '@creatorem/web-glass-effect'; ``` If you're working inside this monorepo, you can still use the `@kit/ui/...` imports. A toggle switch component that combines standard switch functionality with stunning liquid glass visual effects. Features realistic refraction, smooth animations, and intuitive drag-to-toggle interactions. ## Installation ### Option 1: Install package (recommended) ```bash pnpm add @creatorem/web-glass-effect motion ``` ```tsx showLineNumbers import '@creatorem/web-glass-effect/styles.css'; import { LiquidSwitch } from '@creatorem/web-glass-effect'; ``` ### Option 2: Copy source files Install the following dependencies: We use `motion` for animations and `@kit/utils` for utility functions. ```bash npm install motion ``` Copy and paste the following code into your project. Copy the liquid filter component. Copy the liquid utilities library. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { LiquidSwitch } from '@creatorem/web-glass-effect'; ``` ### Basic usage ```tsx showLineNumbers ``` ### Uncontrolled with default state ```tsx showLineNumbers console.log('Switched to:', checked)} /> ``` ### Different sizes ```tsx showLineNumbers ``` ### Custom glass properties ```tsx showLineNumbers ``` ### Disabled state ```tsx showLineNumbers ``` ## Examples ### Sizes The component comes with four size presets: * `xs`: Extra small for compact interfaces * `sm`: Small for dense layouts * `md`: Default medium size * `lg`: Large for prominent switches ### Interaction Modes The switch supports multiple interaction methods: * **Click to toggle**: Single click anywhere on the switch * **Drag to toggle**: Drag the thumb left or right to change state * **Keyboard accessible**: Standard switch keyboard navigation ### Glass Effects The liquid glass effect includes: * **Dynamic refraction**: Light bending based on switch state * **Realistic blur**: Glass-like distortion effects * **Specular highlights**: Glossy surface reflections * **Smooth transitions**: Animated state changes with spring physics * **LIP surface profile**: Realistic glass edge curvature ## API Reference # Fumadocs Framework: Device Mockup URL: /docs/ui/motion/mutable-device-mockup Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/motion/mutable-device-mockup.mdx An animated mockup to switch and render macOS, iPhone and Android devices. *** title: Device Mockup description: An animated mockup to switch and render macOS, iPhone and Android devices. component: true --------------- ## Installation Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage ```tsx showLineNumbers import { Camera, DeviceContent, DeviceSelector, Keyboard, MobileButtons, MutableDeviceMockupRoot, Screen, TopBar, Viewport, } from '@kit/ui/motion/mutable-device-mockup'; ``` ```tsx showLineNumbers {/* Desktop content */} {/* Android and iOS content */} ``` ## Features * MacOS, iPhone and Android mockups. * Animated transitions. * Powered by motion library * Radix components architecture. ## API Reference ### Root `MutableDeviceMockupRootProps` ### Selector `DeviceSelectorProps` ### Viewport ### Screen The screen of all the devices. `React.PropsWithChildren` ### Keyboard The macOS keyboard. ### MacOSTopBar `MacOSTopBarProps` ### IOSTopBar The top bar on iOS devices. ### AndroidTopBar The top bar on Android devices. ### AppleTopCamera The top camera on macOS and iOS devices. ### AndroidFloatingCamera The floating camera on Android devices. ### PowerButton The power button on mobile devices. ### IOSButtons Add mobile buttons according an iOS layout. ### AndroidButtons Add mobile buttons according an Android layout. ### DeviceContent `DeviceContentProps` ### Shortcut components Use this components to avoid the pain of handling all the previous components. #### MobileButtons Add mobile buttons according an iOS or Android layout. #### TopBar Add the top bar according an macOS, iOS or Android layout. #### Camera Add the camera according an macOS, iOS or Android layout. ### MutableDeviceMockup The main component to render the device mockup. Takes the same props as `Root` : `MutableDeviceMockupRootProps`. # web: Configuration URL: /docs/web/configuration Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/(root)/configuration.mdx Core config files that control behavior across the web apps. *** title: Configuration description: Core config files that control behavior across the web apps. ------------------------------------------------------------------------- ## What It Does Configuration files define routes, auth behavior, i18n, analytics, billing, settings UI, and app identity. ## When To Use * Bootstrapping a new app. * Switching providers (billing, analytics, email). * Adding/removing feature modules. ## Prerequisites * Understand app-level config location (`apps//config/*`). This page describes the standard kit integration path; adapt app-specific paths and config names when your project differs. ## How To Use ### Essential config files in `apps/dashboard/config` | File | Purpose | | ------------------------ | ------------------------------------------- | | `app.config.ts` | app name/title/description + email branding | | `auth.config.ts` | auth routes/providers/password rules | | `i18n.config.ts` | language resolver + namespaces | | `analytics.config.ts` | active analytics engines | | `billing.config.ts` | billing provider/products | | `keybindings.config.ts` | shortcut model | | `settings.ui.config.tsx` | settings page composition | ### Shared config package `@kit/shared/config/*` (source in `packages/shared/src/config/*`) provides route constants, default languages, and shared settings schema. ### Filters initialization Keep these files synchronized with enabled features: * `lib/init-cross-env-filters.ts` * `lib/init-server-filters.ts` * `hooks/use-filters.ts` ## MCP Context ```yaml capability: app_configuration entrypoints: - apps/dashboard/config/ - apps/dashboard/lib/init-*.ts - apps/dashboard/hooks/use-filters.ts - packages/shared/src/config/ inputs: - desired_feature_behavior outputs: - updated_app_runtime_configuration constraints: - config and filters must stay consistent - shared routes/languages should be imported from @kit/shared side_effects: - changes runtime behavior across auth/settings/billing/etc. ``` ## Agent Recipe 1. Update the smallest relevant config file first. 2. Ensure feature filters are initialized in both server and client paths when needed. 3. Validate by loading impacted routes and UI sections. ## Troubleshooting * If UI appears but data is missing, verify server filter registration. * If translations are missing, verify namespace list and resolver wiring. ## Related * [Quickstart](/docs/web) * [Settings](/docs/web/features/settings) * [Authentication](/docs/web/features/authentication) # web: Deployment URL: /docs/web/deployment Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/(root)/deployment.mdx Production deployment flow for Supabase-backed web apps. *** title: Deployment description: Production deployment flow for Supabase-backed web apps. --------------------------------------------------------------------- ## What It Does In this guide, we gonna show you how to deploy the **dashboard** and **marketing** applications with *supabase* and *vercel* ## Supabase First deploy a [supabase instance here](https://supabase.com/dashboard/project/). Once your supabase database created push migration files from your local project using the following commands : ```bash npx supabase link --project-ref your-project-ref npx supabase db push ``` You can find your project ref in your Supabase dashboard URL: `https://supabase.com/dashboard/project/your-project-ref` ### Authentication provider Go to Authentication > Sign In / Providers and fill the required field to set you oAuth providers. For instance with google: * click on "Enable Sign in with Google" * enter your "Client IDs" and you "Client Secret (for OAuth)" * click "Skip nonce checks" * click "Save" By default the `Email` provider will be enabled. ### Authentication Emails The creatorem saas kit provide premade templates to personalize the UI of your [authentication email templates](docs/web/features/email/templates) : * Confirm signup * Invite user * Magic Link * Change Email Address * Reset Password Here is the required setup. Go to Authentication > Auth Hooks. Click on "Add a new hook" and select "Send Email hook". Hook type select "HTTPS" In the URL field use : [https://your-domain-name.com/api/auth-hook](https://your-domain-name.com/api/auth-hook) Require that the [auth-hook api endpoint](docs/web/features/authentication) is set in your application. Then generate a "Secret" token and keep it. You gonna need to to set the `AUTH_WEBHOOK_SECRET` environment variable in the vercel dashboard. ### Authentication Redirect URI You have to specify [your application url and the allowed redirect URLs](https://supabase.com/dashboard/project) once user logged in with oAuth provider. Go to "Authentication" > "URL Configuration" and add your application url and the allowed redirect URLs. In "Site URL" field, enter the application url where the auth feature is deployed. In "Redirect URLs" field, enter something like this: `http://localhost:3000/auth/callback` ### Expose the `kit` and `storage` database schema Go to "Project Settings" > "Data API". In the "Exposed schemas" field, add the `kit` and `storage` schema. In the "Extra search path" field, add the `kit` table. Click on "Save". You can safely expose the `kit` and `storage` schema because their are protected by RLS policies. ## Vercel Create a project in the [vercel dashboard](https://vercel.com) Once you repository selected, chose the `apps/dashboard` or `apps/marketing` path as root of the project. ### Set you environment variables Copy paste your environment variables from the .env.local file to the vercel dashboard. You will have to set the following supabase environment variables according your previous setup : | Environment Variable | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | NEXT\_PUBLIC\_SUPABASE\_URL | Go to "Project Settings" > "Data API" | | NEXT\_PUBLIC\_SUPABASE\_ANON\_KEY | Go to "Project Settings" > "API Keys" | | SUPABASE\_SERVICE\_ROLE\_KEY | Go to "Project Settings" > "API Keys" | | SUPABASE\_DATABASE\_URL | To access the supabase connection instruction, go to your dashboard project and add `?showConnect=true` at the end of the url. | Use the "Transaction Pooler" method for the `SUPABASE_DATABASE_URL` variable. Your `SUPABASE_DATABASE_URL` must look like this : ```bash postgresql://postgres.[YOUR-PROJECT-REF]:[YOUR-PASSWORD]@[YOUR-REGION].pooler.supabase.com:6543/postgres ``` ## MCP Context ```yaml capability: production_deployment entrypoints: - package.json db scripts - apps/dashboard/app/api/auth-email-webhook/route.ts - apps/dashboard/app/api/billing/webhook/route.ts inputs: - supabase_project_ref - production_env_vars outputs: - deployed_web_app constraints: - auth redirect urls must match deployed domains - webhook secrets and keys must match provider dashboards side_effects: - mutates production database and integrations ``` ## Agent Recipe 1. Generate SQL and push database changes. 2. Configure provider credentials and webhooks. 3. Deploy apps, then run smoke tests on auth/billing/settings. ## Troubleshooting * If webhooks fail, verify provider secret values and endpoint URLs. * If auth callback fails, verify redirect URL configuration in Supabase. ## Related * [Database](/docs/database) * [Emails](/docs/web/features/emails) * [Billing](/docs/web/features/billing) # web: Quickstart URL: /docs/web Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/(root)/index.mdx Fastest path from clone to running apps. *** title: Quickstart description: Fastest path from clone to running apps. ----------------------------------------------------- ## What It Does This quickstart gets you from dependency install to running app(s) with local Supabase. ## When To Use * First local run. * Verifying environment after pulling updates. ## Prerequisites * Node.js `>=20` * `pnpm` * Docker Desktop This page describes the standard kit integration path; adapt app-specific paths and config names when your project differs. ## How To Use Install dependencies. ```bash pnpm install ``` Generate SQL artifacts and start Supabase. ```bash pnpm run db:generate pnpm run supabase:start ``` Copy test env template for the app you run. ```bash cp apps/dashboard/.env.test apps/dashboard/.env.local cp apps/marketing/.env.test apps/marketing/.env.local ``` Start app dev server. ```bash pnpm --filter ./apps/dashboard dev # or pnpm --filter ./apps/marketing dev ``` ## Capability Map | Capability | Main docs | | ------------ | ---------------------------------------------------------------------- | | Settings API | [/docs/web/features/settings](/docs/web/features/settings) | | Auth | [/docs/web/features/authentication](/docs/web/features/authentication) | | Billing | [/docs/web/features/billing](/docs/web/features/billing) | | Monitoring | [/docs/web/features/monitoring](/docs/web/features/monitoring) | | Translations | [/docs/web/features/translations](/docs/web/features/translations) | | CMS/Docs | [/docs/web/features/cms](/docs/web/features/cms) | ## MCP Context ```yaml capability: bootstrap_project entrypoints: - package.json scripts - apps/*/.env.test inputs: - selected_app outputs: - running_local_app constraints: - docker required for local supabase - app env vars must be present side_effects: - installs dependencies - starts local services ``` ## Agent Recipe 1. Run install and DB bootstrap commands from root. 2. Copy the relevant `.env.test` to `.env.local`. 3. Start one app with workspace filtering and validate route load. ## Troubleshooting * If auth/database routes fail, confirm Supabase is running (`pnpm run supabase:start`). * If build fails on missing envs, compare `.env.local` against `envs.ts` in that app. ## Related * [Configuration](/docs/web/configuration) * [Deployment](/docs/web/deployment) * [MCP Capabilities](/docs/web/mcp-capabilities) # web: MCP Capabilities URL: /docs/web/mcp-capabilities Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/(root)/mcp-capabilities.mdx Stable capability map for coding agents consuming this documentation. *** title: MCP Capabilities description: Stable capability map for coding agents consuming this documentation. ---------------------------------------------------------------------------------- ## What It Does This page defines stable capability-to-doc mappings for MCP ingestion and agent retrieval. ## When To Use * Building an MCP server on top of this docs website. * Prompting coding agents to navigate the kit quickly. ## Prerequisites * Access to `/docs/*` and `/llms.mdx/*` endpoints. * Access to `/mcp-index.json` generated capability endpoint. ## How To Use Use this map as the first retrieval layer. The table below is generated from each page `## MCP Context` block (Common + Web + Mobile scope).\ Source artifact: `/mcp-index.json`. ## MCP Context ```yaml capability: mcp_doc_index entrypoints: - /docs/web/mcp-capabilities - /llms.mdx/[...slug] - /mcp-index.json inputs: - capability_id outputs: - doc_urls_for_retrieval constraints: - capability ids should remain stable for MCP clients side_effects: - none ``` ## Agent Recipe 1. Resolve user intent to one capability id. 2. Retrieve primary page first, then secondary pages. 3. If code edits are requested, map docs guidance to real paths in `apps/*` and `kit/*`. ## Troubleshooting * If a URL is stale, update this page first and keep capability ids unchanged. * If retrieval quality is low, narrow capability ids instead of adding broad pages. ## Related * [Quickstart](/docs/web) * [Documentation](/docs/web/features/documentation) # web: Documentation URL: /docs/web/features/documentation Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/documentation.mdx How this docs website is structured and how to adapt it for customers. *** title: Documentation description: How this docs website is structured and how to adapt it for customers. ----------------------------------------------------------------------------------- ## What It Does The docs app (`apps/creatorem`) uses Fumadocs with MDX content under `content/docs` and exposes per-page LLM text endpoints. ## When To Use * Customizing docs architecture. * Preparing docs for MCP retrieval. ## Prerequisites * Understand Fumadocs source config and docs route setup. This page describes the standard kit integration path; adapt app-specific paths and config names when your project differs. ## How To Use Core pieces: * `source.config.ts` defines docs source + frontmatter schema. * `lib/fumadocs/source.ts` loads docs tree under `/docs`. * `app/(docs)/docs/[...slug]/page.tsx` renders docs pages. * `app/llms.mdx/[...slug]/route.ts` exposes page-level LLM text. * `app/mcp-index.json/route.ts` exposes generated capability index for MCP consumers. * `scripts/generate-mcp-index.mts` and `scripts/check-mcp-contract.mts` generate and validate machine-readable contracts. For MCP readiness, keep page structure predictable and include machine-readable context blocks. ## MCP Context ```yaml capability: docs_platform entrypoints: - apps/creatorem/source.config.ts - apps/creatorem/content/docs/ - apps/creatorem/app/llms.mdx/[...slug]/route.ts - apps/creatorem/app/mcp-index.json/route.ts inputs: - mdx_docs_content outputs: - rendered_docs_and_llm_text_endpoints - generated_mcp_capability_index constraints: - docs tree and metadata must stay coherent side_effects: - static docs generation ``` ## Agent Recipe 1. Update docs content and meta files together. 2. Validate docs routes and LLM route output. 3. Keep docs section contract stable for MCP consumers. ## Troubleshooting * Broken side navigation usually comes from invalid `meta.json` references. * Broken LLM page output usually means unresolved docs slug. ## Related * [MCP Capabilities](/docs/web/mcp-capabilities) * [Fumadocs](/docs/web/features/cms/fumadocs) # web: Monitoring URL: /docs/web/features/monitoring Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/monitoring.mdx Error and request monitoring with @kit/monitoring and Sentry. *** title: Monitoring description: Error and request monitoring with @kit/monitoring and Sentry. links: Sentry: [https://sentry.io/](https://sentry.io/) ------------------------------------------------ ## What It Does `@kit/monitoring` wires instrumentation and provider-level monitoring hooks for web apps. ## When To Use * You need production error capture and tracing. ## Prerequisites * Monitoring env vars configured. Validate credentials, secrets, and runtime environment values before promoting changes to production. ## How To Use ### Instrumentation file ```ts title="apps/dashboard/instrumentation.ts" import { MonitoringProvider } from '@kit/monitoring/provider'; export const register = MonitoringProvider.register; export const onRequestError = MonitoringProvider.captureRequestError; ``` ### Client filter wiring * `useMonitoringFilters()` in app hooks. * Included in app provider filter pipeline. ### Env vars ```dotenv SENTRY_ORG=your-org SENTRY_PROJECT=your-project SENTRY_AUTH_TOKEN=sntrys_xxx NEXT_PUBLIC_SENTRY_DSN=https://xxx.ingest.sentry.io/xxx ``` ## Filter API Monitoring is injected through provider filters, then context-level filters bind auth/error events to the monitoring provider. | Filter | Parameters | Return | Registered By (package file) | Initialized In (app entrypoint) | Environment | | ---------------------- | ------------------------------------------------------------------------------------------------ | ----------------- | --------------------------------------------------------- | --------------------------------------------------------------- | ----------- | | `display_app_provider` | `{ analytics?: AnalyticsManager }` | `React.ReactNode` | `kit/monitoring/src/www/filters/use-filters.tsx` | `apps/dashboard/hooks/use-filters.ts` (`useMonitoringFilters`) | `client` | | `capture_global_error` | `{ error: { name: string; message: string; stack?: string; cause?: unknown }; digest?: string }` | `null` | `kit/monitoring/src/www/filters/use-filters-with-ctx.tsx` | `MonitoringProvider` context mounted via `display_app_provider` | `client` | | `user_signed_in` | `{ userId: string; traits?: Record }` | `null` | `kit/monitoring/src/www/filters/use-filters-with-ctx.tsx` | `MonitoringProvider` context mounted via `display_app_provider` | `client` | * Keep `useMonitoringFilters()` in `apps/dashboard/hooks/use-filters.ts`. * Ensure app tree includes `` in `apps/dashboard/components/providers/app-provider.tsx`. ## MCP Context ```yaml capability: monitoring_setup entrypoints: - apps/dashboard/instrumentation.ts - kit/monitoring/src/www/filters/use-filters.tsx - kit/monitoring/src/www/filters/use-filters-with-ctx.tsx - apps/dashboard/hooks/use-filters.ts - apps/dashboard/components/providers/app-provider.tsx - kit/monitoring/envs.ts inputs: - sentry_credentials outputs: - runtime_error_capture constraints: - dsn and auth token must match Sentry project/org side_effects: - sends errors and traces to monitoring provider ``` ## Agent Recipe 1. Add instrumentation exports. 2. Initialize monitoring filters in client hooks. 3. Configure env vars and verify captured events. ## Troubleshooting * Missing server traces: verify `instrumentation.ts` is present in app root. * Missing client events: verify `NEXT_PUBLIC_SENTRY_DSN` is set. ## Related * [Analytics](/docs/web/features/analytics) # web: Onboarding URL: /docs/web/features/onboarding Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/onboarding.mdx Customize the web onboarding flow with typed schema, step configuration, and filters. *** title: Onboarding description: Customize the web onboarding flow with typed schema, step configuration, and filters. -------------------------------------------------------------------------------------------------- ## What It Does Onboarding is driven by a typed QuickForm schema and step config, then extended through filters for app-specific behavior (organization creation, custom routes, extra inputs, and submit side effects). ## When To Use * You want to collect additional user or organization data right after sign-up. * You need app-specific onboarding steps without forking core onboarding pages. ## Prerequisites * Onboarding schema and step config in `config/onboarding.config.tsx`. * Dashboard onboarding routes mounted. * Filter initialization running in app providers/hooks. This page describes the standard kit integration path; adapt app-specific paths and config names when your project differs. ## How To Use ### Core files ### Add new fields to onboarding Extend the onboarding schema. Add your new field in `apps/dashboard/config/onboarding.config.tsx`: ```ts export const onboardingSchema = { ...onboardingUserSchema, userRole: z.enum(['designer', 'programmer', 'product_manager', 'tester', 'marketer']), userJobTitle: z.string().min(2, 'Job title is required.'), }; ``` Add the field to a step config. ```ts export const onboardingStepsConfig: QuickFormStepConfig[] = [ { type: 'step', label: 'User', settings: [ { type: 'text', slug: 'userName', label: 'Name' }, { type: 'text', slug: 'userJobTitle', label: 'Job title' }, ], }, ]; ``` Provide default values for the new field. Update `defaultValues` in `apps/dashboard/app/onboarding/page.client.tsx`: ```tsx defaultValues={{ userName: user?.name ?? 'Unknown', userJobTitle: '', }} ``` Persist the new field in the correct submit path. * If the field belongs to `public.user`, extend `kit/auth/src/router/update-user.ts` (`updateUserSchema` + `updateUserAction`). * If the field belongs to another table or feature, persist it in the `on_onboarding_submit` filter. `clientTrpc.updateUser.fetch(data)` only persists fields defined in `kit/auth/src/router/update-user.ts`. Extra onboarding fields must be saved through your own onboarding submit filter. ### Add a new onboarding step Declare step fields in schema. Every step field must exist in the onboarding schema (or be injected by `get_onboarding_schema`). Append a typed step in `onboardingStepsConfig`. Use `QuickFormStepConfig[]` so `slug` values stay type-safe: ```ts { type: 'step', label: 'Team', settings: [ { type: 'question_select', slug: 'teamSize', question: 'How large is your team?', answers: [ { value: '1', label: 'Just me' }, { value: '2-10', label: '2-10' }, ], }, ], } ``` Add async validation with `canGoNext` when needed. For example, validate unique values (slug, subdomain, etc.) before moving to the next step. ### Extend onboarding through filters | Filter | Use | | ----------------------------- | ----------------------------------------------------------- | | `get_onboarding_schema` | Add new fields to the global onboarding schema | | `get_onboarding_steps_config` | Inject additional steps into the stepper | | `get_onboarding_extra_inputs` | Register custom QuickForm input components | | `on_onboarding_submit` | Persist non-user onboarding data and customize redirect URL | | `render_onboarding_path` | Render dedicated forms for `/onboarding/{path}` routes | In `apps/dashboard/hooks/use-filters.ts`, call package onboarding filters (for example `useOrgFilters`) so these hooks are enqueued. ### Add a dedicated onboarding path (`/onboarding/{path}`) Use `render_onboarding_path` to return `{ config, inputs, onSubmit }` for each path: ```ts const renderCustomPath: FilterCallback<'render_onboarding_path'> = (value, options) => { switch (options.onboardingPath) { case 'organization': return { config, inputs, onSubmit: handleSubmit, }; default: return null; } }; ``` If your filter returns `null`, `app/onboarding/[onboardingPath]/page.client.tsx` calls `notFound()`, so the route becomes a 404. ## Filter API Onboarding extensibility is driven by a filter pipeline shared across auth and organization packages. | Filter | Parameters | Return | Registered By (package file) | Initialized In (app entrypoint) | Environment | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------- | | `get_onboarding_schema` | `{}` | `QuickFormSchemaMap` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/dashboard/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `get_onboarding_steps_config` | `{ clientTrpc: TrpcClientWithQuery> }` | `QuickFormStepConfig[]` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/dashboard/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `get_onboarding_extra_inputs` | `{}` | `SettingsInputsBase` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/dashboard/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `render_onboarding_path` | `{ onboardingPath: string; clientTrpc: TrpcClientWithQuery>; queryClient: QueryClient; defaultSchema: QuickFormSchemaMap; defaultSteps: QuickFormStepConfig[] }` | `null \| { config: QuickFormConfig; inputs: SettingsInputsBase; onSubmit: (data: unknown) => Promise }` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/dashboard/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `on_onboarding_submit` | `{ data: Record; clientTrpc: TrpcClientWithQuery>; queryClient: QueryClient }` | `string` | `kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx` | `apps/dashboard/hooks/use-filters.ts` (`useOrgFilters`) | `client` | | `server_redirect_onboarding` | `{}` | `string \| null` | `kit/organization/src/www/filters/server-filters.ts` | `apps/dashboard/lib/init-server-filters.ts` (`initOrgServerFilters`) | `server` | * Keep `useOrgFilters({ orgConfig })` in `apps/dashboard/hooks/use-filters.ts`. * Keep `initOrgServerFilters({ orgConfig })` in `apps/dashboard/lib/init-server-filters.ts`. ## MCP Context ```yaml capability: onboarding_flow entrypoints: - apps/dashboard/config/onboarding.config.tsx - apps/dashboard/app/onboarding/page.tsx - apps/dashboard/app/onboarding/page.client.tsx - apps/dashboard/app/onboarding/[onboardingPath]/page.client.tsx - apps/dashboard/hooks/use-filters.ts - apps/dashboard/lib/init-server-filters.ts - kit/organization/src/shared/filters/use-filters/use-onboarding-filters.tsx - kit/organization/src/www/filters/server-filters.ts - kit/auth/src/router/update-user.ts inputs: - onboarding_form_values outputs: - updated_user_profile - optional organization/bootstrap data constraints: - flow should run before user has completedOnboarding side_effects: - updates user data and redirects - may create organization and refresh org membership queries ``` ## Agent Recipe 1. Add new fields to `onboardingSchema`. 2. Place fields in `onboardingStepsConfig` (or inject them through `get_onboarding_steps_config`). 3. Ensure default values exist in onboarding client pages. 4. Persist fields through `updateUser` (user table) or `on_onboarding_submit` (feature-specific tables). 5. Keep `completedOnboarding` gating in server onboarding page. ## Troubleshooting * If onboarding never appears, verify `completedOnboarding` checks and onboarding redirects. * If a custom field renders but is not saved, verify whether it should be persisted in `updateUser` or `on_onboarding_submit`. * If `/onboarding/{path}` returns 404, verify `render_onboarding_path` returns config for that exact path. * If an async step validation never runs, verify it is declared in the step `canGoNext` function. ## Related * [Authentication](/docs/web/features/authentication) * [Quick Form](/docs/ui/components/quick-form) * [Stepper](/docs/ui/components/stepper) # web: Roadmap URL: /docs/web/features/roadmap Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/roadmap.mdx Publish product roadmap items from Notion-backed content. *** title: Roadmap description: Publish product roadmap items from Notion-backed content. ----------------------------------------------------------------------