# benefits: Benefits
URL: /docs/benefits
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/benefits.mdx

Why does this kit exist ? And why should I use it ?
        
***

title: Benefits
description: Why does this kit exist ? And why should I use it ?
----------------------------------------------------------------

## What is the interest ?

Do not waste your time to reinvent the wheel. In 2025, it has never been easier to build software. Many libraries became standard and known by the community (react, tailwind, expo, shadcn/radix, Next.js, etc...). The creatorem saas kit provides you with a coding interface that aims to be as clean as possible to easily understand and customize what you need, to build powerful applications that are easy to maintain and scale.

<Callout icon="Sparkles" title="To keep it simple">
  **Important:** If the modern tools like Next.js, shadcn/ui, expo, etc... are the bricks to create your applications, creatorem is the cement to glue them together.
</Callout>

## For which environments ?

Monorepo tools, featured with the react native ecosystem, allows to build web and native applications with the same codebase. (At least to be as close as never before)

For that reason the creatorem saas kit aims to build tools and applications for :

* **Web applications** : Powered using [**Next.js**](https://nextjs.org/) and [**React**](https://react.dev/).
* **Native applications** : Powered using [**Expo**](https://expo.dev/) and [**React Native**](https://reactnative.dev/).

<Callout variant="info">
  **Note:** Native applications implies to develop **IOS** and **Android** mobile apps.
</Callout>

<Image src="/docs/cross-environment.light.png" themed width="520" height="480" alt="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.

<Callout>
  **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.*
</Callout>

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**.

<Callout variant="info">
  Even if a such AI exists, it would either take a lot of time to build or to be very expensive.
</Callout>


# database: Database
URL: /docs/database
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/database.mdx

Database management for the creatorem saas kit.
        
***

title: Database
description: Database management for the creatorem saas kit.
links:
'Supabase': "[https://supabase.com/](https://supabase.com/)"
------------------------------------------------------------

We are using [Supabase](https://supabase.com/) to host our database.

<ComponentSection name="database" />

## Why Supabase ?

[Supabase](https://supabase.com/) is a modern PostgreSQL database platform that provides a lot of features out of the box. It is a great choice for a saas application.

Here are our favorite features :

| Feature              | Description                                                                                                                         |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| ✨ Row Level Security | RLS allows you to control access to your database based on the user's role.                                                         |
| Api REST             | Supabase provides a REST API to access and edit your database.                                                                      |
| Hosting              | Supabase Cloud provides affordable pricing and a free tier, perfect when you are just starting.                                     |
| Open Source          | If you want to host your own database, you can host it yourself as [Supabase is open source](https://github.com/supabase/supabase). |
| Web client           | You can view and edit your database in a Supabase Studio, a web interface to manage your database.                                  |
| Authentication       | Supabase provides a built-in authentication system with many oAuth providers.                                                       |
| Much more...         | Version management, test, realtime database, bucket storage, etc...                                                                 |

<Callout>
  Most of all, **Supabase**, is built on top of PostgreSQL, giving you a huge flexibility and efficiency to manage your data.
</Callout>

`sql` is a language built to **efficiently** handle a **huge amount of data**.
`sql` allows you to set more than *tables* and *constraints*. You can define *functions*, *triggers*, *views*, *enums*, etc...

Defining as much logic as possible using `sql`, you highly simplify your application logic. As all the data checking, control access, coercing, etc... are done by the database.

## Project structure

By default, we have single database by monorepo. As the core of an appplication is its data, and the web/mobile/etc applications are closer to entry points to access and edit your data.

| File/Folder   | Description                                                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `migrations`  | All migrations files. **Do not touch**, they are automatically generated using *creatorem* or *supabase* tools.                                         |
| `schemas`     | **The most important files**. Contains all the data logic declaration, tables, relations, etc...                                                        |
| `env-schemas` | That files contains examples of tables definition that you might use in your products. Can be used in `dev` environment to generate migrations.         |
| `tests`       | Supabase test files.                                                                                                                                    |
| `.env`        | The environment variables for the database.                                                                                                             |
| `config.toml` | The config file for the database. Allow you to configure the supabase database on environment variables. For example, you can set oAuth providers here. |
| `seed.sql`    | To seed the database with some data.                                                                                                                    |

<Files>
  <Folder name="your-saas-comes-here" defaultOpen>
    <Folder name="apps">
      <Folder name="dashboard">
        <Folder name="app">
          <Folder name="other-endpoints">
            <File name="..." />
          </Folder>

          <File name="globals.css" />

          <File name="layout.tsx" />

          <File name="not-found.tsx" />

          <File name="page.tsx" />
        </Folder>

        <File name="next.config.ts" />

        <File name="package.json" />
      </Folder>

      <Folder name="marketing">
        <Folder name="app">
          <Folder name="other-endpoints">
            <File name="..." />
          </Folder>

          <File name="globals.css" />

          <File name="layout.tsx" />

          <File name="not-found.tsx" />

          <File name="page.tsx" />
        </Folder>

        <File name="next.config.ts" />

        <File name="package.json" />
      </Folder>

      <Folder name="...">
        <File name="..." />
      </Folder>
    </Folder>

    <Folder name="kit">
      <Folder name="i18n">
        <Folder name="src">
          <Folder name="components">
            <File name="button.tsx" />
          </Folder>

          <File name="i18n.client.ts" />

          <File name="i18n.server.ts" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="...">
        <File name="..." />
      </Folder>
    </Folder>

    <Folder name="supabase" defaultOpen>
      <Folder name="migrations" defaultOpen>
        <File name="20250817141810_generated_from_schemas.sql" />
      </Folder>

      <Folder name="env-schemas" defaultOpen>
        <File name="booking.sql" />
      </Folder>

      <Folder name="schemas" defaultOpen>
        <File name="000-privileges.sql" />

        <File name="001-enums.sql" />

        <File name="nnn-other-schemas.sql" />
      </Folder>

      <Folder name="tests">
        <File name="kit_base.test.sql" />

        <File name="other.test.sql" />
      </Folder>

      <File name=".env" />

      <File name="config.toml" />

      <File name="seed.sql" />
    </Folder>

    <Folder name="tooling">
      <Folder name="eslint-config">
        <Folder name="src">
          <File name="index.ts" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="prettier-config">
        <Folder name="src">
          <File name="index.ts" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="tailwind-config">
        <Folder name="src">
          <File name="theme.css" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="tsconfig">
        <Folder name="src">
          <File name="index.ts" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="...">
        <File name="..." />
      </Folder>
    </Folder>

    <File name="package.json" />

    <File name="turbo.json" />
  </Folder>
</Files>

## Migration generation

To assemble the migration file, you can use the following command :

```bash
npm run db:generate-migration
```

If you start with an empty project, you may want example tables to see all the kit power in action.

You can also create your migration with the example `booking.sql` file in the `supabase/env-schemas` folder using the following command :

```bash
npm run db:generate-migration --env-schemas booking
```

## Commands

### Start

First, make sure that **docker** is running.

```bash
npm run supabase:start
```

### Stop

```bash
npm run supabase:stop
```

### Test

```bash
npm run supabase:test
```

### Reset

The reset command will rebuild the migration file and recreate a new empty database instance.

```bash
npm run db:reset
```

If you want to reset with the example `booking.sql` schema, you can use the following command :

```bash
npm run db:reset:booking
```

### Types generation

<Callout>
  The previous `supabase` commands where close to a ordinary `supabase` cli usage. But this command also generate the drizzle declaration files and extra types.

  *For that reason, we do not advise to use the `supabase gen types typescript`, from the `supabase` cli command.*
</Callout>

```bash
npm run db:types
```

That command will :

* generate the `supabase` types in the `kit/db/core/src/database.types.ts` file.
* generate the `drizzle` declaration files in the `@kit/drizzle/src/drizzle/` package.
* create extra types in the `@kit/drizzle/src/tables.ts` file to improve a cleaner development experience.

<Callout variant="info">
  We are using the `drizzle` client in web applications because it offers better type checking and better autocompletion than the `supabase` client.

  We are working to use it also on native applications. But `supabase` ecosystem is not fully compatible with mobile app and PostgresQL database yet.
</Callout>

### Dump

```bash
npm run supabase:db:dump:local
```

### Deploy

```bash
npm run supabase:deploy
```


# scripts: Scripts
URL: /docs/scripts
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(common)/scripts.mdx

All the scripts commands from the the root `package.json` file.
        
***

title: Scripts
description: All the scripts commands from the the root `package.json` file.
----------------------------------------------------------------------------

In this page, you will learn the role of each script command from the root `package.json` file.

```json title="package.json"
{
  "name": "your-project-name",
  "version": "1.0.0",
  "scripts": {
    "build": "...", // build all apps and packages for production
    "clean": "...", // rm node_modules, dist, .next, etc...
    "dev": "..", // trigger dev cmd for all apps in parallel
    "format": "...", // format the code with `prettier`
    "format:fix": "...", // format the code and fix issues
    "lint": "...", // lint the code with `eslint`
    "lint:fix": "...", // lint the code and fix issues
    "typecheck": "...", // ts type checking using `tsc`
    // other scripts...
  }
  // dependencies, etc...
}
```

We are using the `turbo` tool to run the scripts, one by one for each application/packages.

## Development Scripts

### Dev

The `dev` script starts the development servers for all applications in parallel.

```bash
npm run dev
```

This command uses `turbo dev --parallel` to run development servers concurrently for all apps (marketing, dashboard, creatorem, mobile) and packages.

### Build

The `build` script builds all applications and packages for production.

```bash
npm run build
```

This uses `turbo build` with caching to compile all projects efficiently.

### Clean

The `clean` script removes all generated files and dependencies.

```bash
npm run clean
```

This command cleans `node_modules`, `dist`, `.next` directories and other build artifacts.

## Code Quality Scripts

### Lint

The `lint` script runs ESLint on all affected packages and checks for package mismatches.

```bash
npm run lint
```

This uses `turbo lint --affected` to only lint files that have changed, improving performance.

### Lint:fix

The `lint:fix` script automatically fixes ESLint issues and package mismatches.

```bash
npm run lint:fix
```

This command fixes linting errors and corrects package dependency inconsistencies.

### Format

The `format` script checks code formatting using Prettier.

```bash
npm run format
```

This command verifies that all code follows the project's formatting standards.

### Format:fix

The `format:fix` script automatically formats all code files.

```bash
npm run format:fix
```

This command applies Prettier formatting to fix any formatting issues.

### Typecheck

The `typecheck` script runs TypeScript type checking across all packages.

```bash
npm run typecheck
```

This uses `turbo typecheck --affected` to only check types for changed files.

## Testing Scripts

### Test

The `test` script runs all test suites across the monorepo.

```bash
npm run test
```

This command executes unit tests, integration tests, and other test types defined in each package.

### Analyze

The `analyze` script runs bundle analysis tools to optimize build sizes.

```bash
npm run analyze
```

This helps identify large dependencies and optimization opportunities.

## Package Management Scripts

### Syncpack:list

The `syncpack:list` script lists mismatched package versions across the monorepo.

```bash
npm run syncpack:list
```

This helps identify packages that have different versions in different workspaces.

### Syncpack:fix

The `syncpack:fix` script automatically fixes package version mismatches.

```bash
npm run syncpack:fix
```

This ensures all packages use consistent versions across the monorepo.

## Database Scripts

Check the [database commands](./docs/database#commands) for more information.

## Payment Scripts

### Stripe:listen

The `stripe:listen` script starts the Stripe webhook listener for local development.

```bash
npm run stripe:listen
```

This enables local testing of Stripe webhooks and payment flows.


# 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](/docs/ui/components) : missing components from the *shadcn/ui* library.
* [motion](/docs/ui/motion) : custom animated components implemented with the [motion](https://motion.dev/) library.

<Callout icon="Megaphone">
  **Important:** Some of this components are only available with the [creatorem saas kit](/pricing).
</Callout>


# mobile: Not implemented yet
URL: /docs/mobile
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mobile/(root)/index.mdx

Mobile environment tools
        
***

title: Not implemented yet
description: Mobile environment tools
-------------------------------------

<Callout>
  The mobile environment tools are not implemented yet. The mobile app will be launched **the 30th of November 2025**.
</Callout>


# 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)
--------------------------------------------------------------------------------------------------------------------------------------------------------

<ComponentPreview name="confirm-button-demo" description="A confirm button" align="center" />

## 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.

<Callout title="What do you means by high level component?">
  This component is just a shortcut to a `AlertDialog` implementation.
</Callout>

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

<Steps>
  <Step>Make sure that the following shadcn/ui components are present in your project:</Step>

  * [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)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="confirm-button" title="components/ui/confirm-button.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { ConfirmButton } from '@kit/ui/confirm-button';
```

```tsx showLineNumbers
<ConfirmButton
    aria-label="Delete item"
    template="delete"
    onConfirmation={() => {
        console.log('Confirmation triggered!');
    }}
>
    Delete
</ConfirmButton>
```

## Features

* Built to avoid duplicated code.
* Quickly add templates to fit your needs.
* Support for write confirmation.

## API Reference

<AutoTypeTable path="../../kit/www/ui/src/components/confirm-button.tsx" name="ConfirmButtonProps" defaultOpen={['buttonLabels']} />


# Fumadocs Framework: File Upload
URL: /docs/ui/components/file-upload
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/file-upload.mdx

A simple file input with validation for formats and size.
        
***

title: File Upload
description: A simple file input with validation for formats and size.
component: true
---------------

<ComponentPreview name="file-upload-demo" description="Upload a single file and validate type/size" align="center" />

## Installation

<Steps>
  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="file-upload" title="components/ui/file-upload.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { FileInput } from '@kit/ui/file-upload';
```

```tsx showLineNumbers
<FileInput
    idName="demo"
    formatType="image"
    onFileChange={(file) => {
        console.log('Selected file:', file);
    }}
/>
```

## Features

* Validates file type and size
* Configurable accepted formats by category
* Simple API for handling selected file

## API Reference

<AutoTypeTable path="../../kit/www/ui/src/components/file-upload.tsx" name="FileInputProps" />


# Fumadocs Framework: Image Dropzone
URL: /docs/ui/components/image-dropzone
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/image-dropzone.mdx

Drag & drop or click to select an image, with preview support.
        
***

title: Image Dropzone
description: Drag & drop or click to select an image, with preview support.
component: true
---------------

<ComponentPreview name="image-dropzone-demo" description="Drop or select an image and preview it" align="center" />

## Installation

<Steps>
  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="image-dropzone" title="components/ui/image-dropzone.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { ImageDropzone } from '@kit/ui/image-dropzone';
```

```tsx showLineNumbers
<ImageDropzone
    borderRadius="md"
    onDrop={(accepted) => {
        const first = accepted[0];
        if (first) {
            const url = URL.createObjectURL(first);
            console.log('Dropped file URL:', url);
        }
    }}
/>
```

## Features

* Drag & drop integration
* Optional preview via `src` prop
* Border radius presets and easy styling

## API Reference

<AutoTypeTable path="../../kit/www/ui/src/components/image-dropzone.tsx" name="ImageDropzoneProps" />


# Fumadocs Framework: Media Manager
URL: /docs/ui/components/media-manager
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/media-manager.mdx

A full-featured media picker and manager with selection, edit, and upload.
        
***

title: Media Manager
description: A full-featured media picker and manager with selection, edit, and upload.
component: true
---------------

<ComponentPreview name="media-manager-demo" description="Open a dialog to manage and select media" align="center" />

## Installation

<Steps>
  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="media-manager" title="components/ui/media-manager.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { MediaManager, MediaManagerTrigger, MediaManagerContent } from '@kit/ui/media-manager';
```

```tsx showLineNumbers
<MediaManager
    rootPath={["public"]}
    medias={[]}
    onPathChange={() => {}}
    getUrl={(media, path) => `https://example.com/${[...path, media.name].join('/')}`}
    value={null}
    onValueChange={(val) => console.log('Selected:', val)}
>
    <MediaManagerTrigger />
    <MediaManagerContent />
</MediaManager>
```

## Features

* Dialog-based manager with list, selection, and details pane
* Works with URLs or object values; single or multiple selection
* Upload flow integration and metadata editing

## API Reference

<AutoTypeTable path="../../kit/www/ui/src/components/media-manager.tsx" name="MediaManagerProps" />


# 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
---------------

<ComponentPreview name="number-input-demo" description="Interactive number input with multiple control methods" align="center" />

## Installation

<Steps>
  <Step>Make sure that the following shadcn/ui components are present in your project:</Step>

  * [Input](https://ui.shadcn.com/docs/components/input)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="use-input-drag-control" title="hooks/use-input-drag-control.ts" />

  <ComponentSource name="number-input" title="components/ui/number-input.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { DragWheelControls, NumberInputBase, NumberInputRoot, NumberInputUnit } from '@kit/ui/number-input';
```

```tsx showLineNumbers
<NumberInputRoot unit="px">
    <DragWheelControls>
        <NumberInputBase placeholder="Your placeholder here" className="w-24 text-right" />
        <NumberInputUnit />
    </DragWheelControls>
</NumberInputRoot>
```

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
<NumberInput unit="px" />
```

## 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.

<Image src="/docs/number-input-key-step-factor.light.png" themed size="sm" width="630" height="430" alt="Number Input component anatomy" />

## Examples

### Horizontal Drag

Switch the drag direction to horizontal.

<ComponentPreview name="number-input-horizontal-demo" description="Horizontal drag example" variant="content" align="center" />

### Custom Scale

Control the sensitivity of the drag and wheel controls.

<ComponentPreview name="number-input-custom-scale-demo" description="Custom scale example" variant="content" align="center" />

### Min/Max

<ComponentPreview name="number-input-min-max-demo" description="Min/max example" variant="content" align="center" />

### Base

The `NumberInputBase` component is a simpler version of the `NumberInput` component without drag and wheel controls.

<ComponentPreview name="number-input-base-demo" description="Base example" variant="content" align="center" />

## API Reference

We are exposing 2 components

### Root

`NumberInputRootProps`

<AutoTypeTable path="../../kit/www/ui/src/components/number-input.tsx" name="NumberInputRootProps" />

### Drag & Wheel Controls

`DragWheelControlsProps`

<AutoTypeTable path="../../kit/www/ui/src/components/number-input.tsx" name="DragWheelControlsProps" />

### Base

The input `type="number"` element.

### Unit

`NumberInputUnitProps`

<AutoTypeTable path="../../kit/www/ui/src/components/number-input.tsx" name="NumberInputUnitProps" />

### All in one

<Callout type="note">
  This component is a shortcut if you don't need heavy customization.
</Callout>

`NumberInputProps`

<AutoTypeTable path="../../kit/www/ui/src/components/number-input.tsx" name="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
-----------------

<ComponentPreview name="phone-input-demo" description="A phone input component" align="center" />

## Installation

<Steps>
  <Step>Install the following dependencies:</Step>

  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
  ```

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="phone-input" title="components/ui/phone-input.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Anatomy

<Image src="/docs/phone-input-anatomy.light.png" themed width="420" height="260" alt="Phone Input component anatomy" />

## Usage

```tsx showLineNumbers
import { PhoneInputRoot, PhoneInputBase, PhoneInputFlagMenu } from '@kit/ui/phone-input';
```

```tsx showLineNumbers
<PhoneInputRoot value={value || ''} onPhoneInputChange={handleChange}>
    <PhoneInputFlagMenu className="bg-muted/50 focus-visible:bg-background" />
    <PhoneInputBase className={cn('max-w-md', value ? 'bg-muted/50 focus-visible:bg-background' : '')} />
</PhoneInputRoot>
```

## Features

* International zip code suggestions
* Flag menu
* Phone number formatting

## API Reference

### Root

`PhoneInputRootProps`

<AutoTypeTable path="../../kit/www/ui/src/components/phone-input/phone-input.tsx" name="PhoneInputRootProps" />

### Flag Menu

Props: `Omit<React.HTMLAttributes<HTMLButtonElement>, 'children' | 'type' | 'role'>`

### Base

The input component.

Props: `React.InputHTMLAttributes<HTMLInputElement>`


# 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

<ComponentPreview name="progression-demo" description="A progression component showing scroll progress" align="center" innerClassName="overflow-visible" />

## Installation

<Steps>
  <Step>Install the following dependencies:</Step>

  We use `@radix-ui/react-slot` for component composition.

  ```bash
  npm install @radix-ui/react-slot
  ```

  <Step>Make sure that the following shadcn/ui components are present in your project:</Step>

  * [Slot](https://www.radix-ui.com/primitives/docs/utilities/slot)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="progression" title="components/ui/progression.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { Progression, ProgressionBar, ProgressionCircle, ProgressionContent } from '@kit/ui/progression';
```

### Basic Example

```tsx showLineNumbers
<Progression>
    <ProgressionContent className="min-h-screen">
        {/* Long content */}
    </ProgressionContent>

    <ProgressionCircle />
    <ProgressionBar />
</Progression>
```

## 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
<ProgressionCircle
    size={40}
    strokeWidth={2}
    strokeLinecap="round"
    className="text-primary"
    textClassName="text-xs font-medium"
/>
```

`ProgressionCircleProps`

<AutoTypeTable path="../../kit/www/ui/src/components/progression.tsx" name="ProgressionCircleProps" />

### Bar

Displays progress as a horizontal or vertical bar.

```tsx showLineNumbers
<ProgressionBar
    thickness={4}
    className="w-full"
    barClassName="bg-primary"
    direction="horizontal"
/>
```

`ProgressionBarProps`

<AutoTypeTable path="../../kit/www/ui/src/components/progression.tsx" name="ProgressionBarProps" />

### Content

Wraps the content you want to track scroll progress for.

```tsx showLineNumbers
<ProgressionContent className="max-w-4xl mx-auto p-4">
    {/* Your content */}
</ProgressionContent>
```

`ProgressionContentProps`

<AutoTypeTable path="../../kit/www/ui/src/components/progression.tsx" name="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
---------------

<ComponentPreview name="qr-code-demo" description="Generate QR codes with different values and download them" align="center" />

## Installation

<Steps>
  <Step>Install the following dependencies:</Step>

  We use `qrcode` for the QR code generation.

  ```bash
  npm install qrcode
  ```

  <Step>Make sure that the following shadcn/ui components are present in your project:</Step>

  * [Button](https://ui.shadcn.com/docs/components/button)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="qr-code" title="components/ui/qr-code.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Anatomy

<Image src="/docs/qr-code-anatomy.light.png" themed size="full" width="630" height="430" alt="QR Code component anatomy" />

## Usage

```tsx showLineNumbers
import { QRCodeRoot, QRCodeFrame, QRCodePattern, QRCodeDownloadTrigger } from '@kit/ui/qr-code';
```

```tsx showLineNumbers
<QRCode value={'https://example.com'} pixelSize={4} errorCorrectionLevel="M">
    <QRCodeFrame>
        <QRCodePattern />
    </QRCodeFrame>
    <QRCodeDownloadTrigger />
</QRCode>
```

## 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
<QRCode value={routes.url} pixelSize={4} errorCorrectionLevel="M">
    <QRCodeFrame>
        <QRCodePattern />
        <QRCodeOverlay className="bg-primary border-4 inset-shadow-2xs">
          <Image src="path/to/your/logo.svg" width={16} height={16} alt="Your Logo" />
        </QRCodeOverlay>
    </QRCodeFrame>
    <QRCodeDownloadTrigger />
</QRCode>
```

## 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.

<Callout>
  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.
</Callout>

| Level | Error resistance |
| ----- | ---------------- |
| L     | \~7%             |
| M     | \~15%            |
| Q     | \~25%            |
| H     | \~30%            |

## API Reference

### Root

Contains the context provider and a div element.

<Callout>
  We advise you to set the width of the QR code in this component using the `className` prop.
</Callout>

<AutoTypeTable path="../../kit/www/ui/src/components/qr-code.tsx" name="QRCodeRootProps" />

### Frame

Contains the QR code frame.

<AutoTypeTable path="../../kit/www/ui/src/components/qr-code.tsx" name="QRCodeFrameProps" />

### Pattern

Contains the QR code SVG element.

Props: `Omit<React.SVGAttributes<SVGSVGElement>, 'children'>`

### Overlay

Add an overlay to make your QR code more attractive.

<AutoTypeTable path="../../kit/www/ui/src/components/qr-code.tsx" name="QRCodeOverlayProps" />

### Download Trigger

<AutoTypeTable path="../../kit/www/ui/src/components/qr-code.tsx" name="QRCodeDownloadTriggerProps" />


# 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.

<ComponentPreview name="quick-form-demo" description="A quick form component" align="center" />

## Installation

<Steps>
  <Step>Make sure that the following shadcn/ui components are present in your project:</Step>

  * [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)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="quick-form" title="components/ui/quick-form.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Features

* Avoid form redundancy
* Typescript auto-completion
* Zod validation
* Clean MVC architecture
* Equivalent component for server side rendering in the kit.

## Usage

<div className="my-12">
  <Image src="/docs/quick-form-workflow.light.png" themed size="lg" width="550" height="710" alt="Quick Form workflow" />
</div>

```tsx showLineNumbers
import { QuickForm, type QuickFormConfig } from '@kit/ui/quick-form';
import { z } from 'zod';
```

```tsx showLineNumbers
<QuickForm
    config={{
        id: 'my-from',
        schema: {
            name: z.string().min(2, 'Please enter at least 2 characters'),
            email: z.string().email('Please enter a valid email'),
            phone: z.string().optional().default(''),
            bio: z.string().max(200, 'Max 200 characters').default(''),
        },
        settings: [
            {
                type: 'wrapper',
                header: (
                    <div className="space-y-1">
                        <h3 className="text-lg font-semibold">Profile</h3>
                        <p className="text-muted-foreground text-sm">Basic information</p>
                    </div>
                ),
                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`

<AutoTypeTable path="../../kit/www/ui/src/components/quick-form/quick-form.tsx" name="QuickFormComponentProps" />

### Config

`QuickFormConfig`

<AutoTypeTable path="../../kit/www/ui/src/components/quick-form/types.ts" name="QuickFormConfig" />

### Inputs

You can find all the inputs available by default here :

<AutoTypeTable path="../../kit/www/ui/src/components/quick-form/registered-inputs.ts" type="typeof REGISTERED_INPUTS" />


# 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)
------------------------------------------------------------------------------------------------------------------------------------------------------

<ComponentPreview name="speech-input-demo" description="A speech input component with real-time transcription" align="center" />

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

<Steps>
  <Step>Install the following dependencies:</Step>

  ```bash
  npm install motion
  ```

  <Step>Make sure that the following packages are present in your project:</Step>

  * [Radix UI Slot](https://www.radix-ui.com/primitives/docs/utilities/slot)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="speech-input" title="components/ui/speech-input.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

### Basic Setup

```tsx showLineNumbers
import { SpeechInput, SpeechInputTrigger, SpeechInputBase, SpeechInputCancel } from '@kit/ui/speech-input';

<SpeechInput
    lang="en-US"
    onSpeechStart={() => console.log('Started listening')}
    onSpeechChange={(text) => console.log('Final:', text)}
>
    <SpeechInputTrigger />
    <SpeechInputCancel />
    <SpeechInputBase asChild>
        <Input placeholder="Speak or type..." />
    </SpeechInputBase>
</SpeechInput>
```

### With Custom Components

The `asChild` prop lets you compose with your own components:

```tsx showLineNumbers
<SpeechInputTrigger asChild>
    <Button>
        <SpeechInputEqualizer className="h-4 w-4" />
        Record
    </Button>
</SpeechInputTrigger>

<SpeechInputBase asChild>
    <CustomInput />
</SpeechInputBase>
```

### Cancelling Input

The `SpeechInputCancel` button discards the transcription and prevents the `onSpeechChange` callback:

```tsx showLineNumbers
<SpeechInputCancel />  {/* Only enabled while listening */}
```

## API Reference

### SpeechInput

Root provider managing speech recognition state.

<AutoTypeTable path="../../kit/www/ui/src/components/speech-input.tsx" name="SpeechInputProps" />

### SpeechInputTrigger

Button to start/stop speech recognition. Supports `asChild` for composition.

### SpeechInputCancel

Button to cancel recording and discard transcription. Disabled when not listening.

<AutoTypeTable path="../../kit/www/ui/src/components/speech-input.tsx" name="SpeechInputCancelProps" />

### SpeechInputEqualizer

Animated equalizer showing real-time audio activity.

<AutoTypeTable path="../../kit/www/ui/src/components/speech-input.tsx" name="SpeechInputEqualizerProps" />

### SpeechInputBase

Input field displaying transcribed text. Fully editable by keyboard.

<AutoTypeTable path="../../kit/www/ui/src/components/speech-input.tsx" name="SpeechInputBaseProps" />

## 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

<ComponentPreview name="stepper-demo" description="A stepper component" align="center" />

## Installation

<Steps>
  <Step>Install the following dependencies:</Step>

  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.

  <div id="installation-cmd">
    ```bash
    npm install react-hook-form motion
    ```
  </div>

  <Step>Make sure that the following shadcn/ui components are present in your project:</Step>

  * [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)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="stepper" title="components/ui/stepper.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { Stepper, StepperContent, StepperNext, StepperPrevious, StepperStep, StepperTrigger } from '@kit/ui/stepper';
```

```tsx showLineNumbers
<Stepper>
    <nav className="flex gap-2">
        <StepperTrigger step={1}>Step 1</StepperTrigger>
        <StepperTrigger step={2}>Step 2</StepperTrigger>
        <StepperTrigger step={3}>Step 3</StepperTrigger>
    </nav>

    <StepperContent>
        <StepperStep type={1}>
            <>{/* Step content 1 */}</>
        </StepperStep>
        <StepperStep type={2}>
            <>{/* Step content 2 */}</>
        </StepperStep>
        <StepperStep type={3}>
            <>{/* Step content 3 */}</>
        </StepperStep>
    </StepperContent>

    <div className="mt-12 flex flex-row-reverse">
        <StepperNext />
        <StepperPrevious />
    </div>
</Stepper>
```

### Anatomy

<Image src="/docs/stepper-anatomy.light.png" themed size="full" width="875" height="600" alt="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}
<Stepper>
    <StepperMotionContent
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        exit={{ opacity: 0 }}
    >
        {/* Your steps come here ... */}
    </StepperMotionContent>

    <div className="mt-12 flex flex-row-reverse">
        <StepperNext />
        <StepperPrevious />
    </div>
</Stepper>
```

<ComponentPreview name="stepper-motion-demo" description="An animated stepper component with motion" align="center" />

### 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.

<Steps>
  <Step>Declare the form methods and schema</Step>

  <Step>Optional: set `disableForwardNav` to `true` to disable the forward navigation, prevent your users to skip a step without validating the previous steps.</Step>

  <Step>We are using the `name` props of the `<FormField />` children to detect which fields are present in the current step.</Step>

  <Callout>
    For that reason, you have to use shadcn/ui's `<FormField />` component to properly integrate your form.
  </Callout>
</Steps>

```tsx showLineNumbers {1-5,8,13,15,32,34,50,63}
 const methods = useForm<FormData>({
    mode: 'onChange',
    resolver: zodResolver(yourSchema),
    defaultValues: {/* ... */}
});

return (
    <Stepper reactForm={methods} disableForwardNav>
        <Form {...methods}>
            <form onSubmit={methods.handleSubmit(console.log)} className="w-full space-y-6">
                <StepperContent>
                    <StepperStep>
                        <FormField
                            control={methods.control}
                            name="firstName"
                            render={({ field }) => (
                                <FormItem className="flex w-full flex-col">
                                    <FormLabel>First Name</FormLabel>
                                    <FormControl>
                                        <Input
                                            type="text"
                                            maxLength={512}
                                            disabled={methods.formState.isSubmitting}
                                            placeholder="John"
                                            {...field}
                                        />
                                    </FormControl>
                                    <FormMessage />
                                </FormItem>
                            )}
                        />
                        <FormField
                            control={methods.control}
                            name="lastName"
                            render={({ field }) => (
                                <FormItem className="flex w-full flex-col">
                                    <FormLabel>Last Name</FormLabel>
                                    <FormControl>
                                        <Input
                                            type="text"
                                            maxLength={512}
                                            disabled={methods.formState.isSubmitting}
                                            placeholder="Doe"
                                            {...field}
                                        />
                                    </FormControl>
                                    <FormMessage />
                                </FormItem>
                            )}
                        />
                    </StepperStep>
                    {/* other steps come here ... */}
                </StepperContent>

                {/* flex row reverse for focus control */}
                <div className="mt-12 flex flex-row-reverse justify-between">
                    <StepperNext />

                    <StepperPrevious />
                </div>
            </form>
        </Form>
    </Stepper>
);
```

## Progress Bar variant

Here are some premade progress bar that you can use or adapt to your needs.

### Simple

<ComponentPreview name="stepper-nav-simple" description="A simple navigation variant stepper component" align="center" className="[&_.preview]:min-h-[320px]" />

### Bullets

<ComponentPreview name="stepper-nav-bullets" description="A bullets navigation variant stepper component" align="center" className="[&_.preview]:min-h-[320px]" />

### Panels Borders

<ComponentPreview name="stepper-nav-panels-borders" description="A panels borders navigation variant stepper component" align="center" className="[&_.preview]:min-h-[320px]" />

### Circles

<ComponentPreview name="stepper-nav-circles" description="A circles navigation variant stepper component" align="center" className="[&_.preview]:min-h-[320px]" />

### Connecting Lines

<ComponentPreview name="stepper-nav-connecting-lines" description="A connecting lines navigation variant stepper component" align="center" className="[&_.preview]:min-h-[320px]" />

### Dots

<ComponentPreview name="stepper-nav-dots" description="A dots navigation variant stepper component" align="center" className="[&_.preview]:min-h-[320px]" />

### Panels Progress

<ComponentPreview name="stepper-nav-panels-progress" description="A panels progress navigation variant stepper component" align="center" className="[&_.preview]:min-h-[320px]" />

## API Reference

### Root

<AutoTypeTable path="../../kit/www/ui/src/components/stepper.tsx" name="StepperProps" />

### 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.

<Callout>
  Must be the direct child of StepperContent.
</Callout>

`StepperStepProps`

<AutoTypeTable path="../../kit/www/ui/src/components/stepper.tsx" name="StepperStepProps" />

### Previous

Previous step button.

`StepperPreviousProps`

<AutoTypeTable path="../../kit/www/ui/src/components/stepper.tsx" name="StepperPreviousProps" />

### Next

Next step button.

`StepperNextProps`

<AutoTypeTable path="../../kit/www/ui/src/components/stepper.tsx" name="StepperNextProps" />

### Trigger

`StepperTriggerProps`

<AutoTypeTable path="../../kit/www/ui/src/components/stepper.tsx" name="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)
-----------------------------------------------------------------------------------------------------------------------------------------

<ComponentPreview name="tour-demo" description="An accordion with three items" align="center" />

## Installation

<Steps>
  <Step>Install the following dependencies:</Step>

  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.

  <div id="installation-cmd">
    ```bash
    npm install motion/react react-remove-scroll
    ```
  </div>

  <Step>Make sure that the following shadcn/ui components are present in your project:</Step>

  * [Popover](https://ui.shadcn.com/docs/components/popover)
  * [Button](https://ui.shadcn.com/docs/components/button)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="tour" title="components/ui/tour.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { Tour, TourArrow, TourClose, TourContent, TourDescription, TourFrame, TourNext, TourOverlay, TourPortal, TourPrevious, TourProgress, TourTitle, TourTrigger, type TourStep } from '@kit/ui/tour';
```

<div id="tour-demo-cmd">
  ```tsx showLineNumbers
  <TourRoot config={{ steps: [{ element: '#app', title: 'App', description: 'App' }] }}>
      <TourTrigger />
      <TourPortal>
          <TourOverlay />
          <TourFrame />
          <TourContent>
              <TourArrow />
              <TourProgress />
              <TourTitle />
              <TourDescription />

              <div className="flex w-full flex-row-reverse justify-between gap-2">
                  <div className="flex flex-row-reverse gap-2">
                      <TourNext />
                      <TourPrevious />
                  </div>
                  <TourClose />
              </div>
          </TourContent>
      </TourPortal>
  </TourRoot>
  ```
</div>

## 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

<Image src="/docs/tour-keyboard-controls.light.png" themed size="lg" width="810" height="430" alt="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.

<AutoTypeTable path="../../kit/www/ui/src/components/tour.tsx" name="TourProviderProps" defaultOpen={['config']} />

### 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<typeof motion.div>` props.

### Overlay

The overlay that cover the entire screen except the highlighted element.

<AutoTypeTable path="../../kit/www/ui/src/components/tour.tsx" name="TourOverlayProps" />

### 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.

<Callout>
  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.*
</Callout>

### Title

To display the title of the active step.

Props : `React.HTMLAttributes<HTMLHeadingElement>`.

### Description

To display the description of the active step.

Props : `React.HTMLAttributes<HTMLParagraphElement>`.

### Progress

A progress component to show which step the user is on.

<AutoTypeTable path="../../kit/www/ui/src/components/tour.tsx" name="TourProgressProps" />

### 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`

<AutoTypeTable path="../../kit/www/ui/src/components/tour.tsx" name="TourCloseProps" />

### Previous

`TourPreviousProps`

<AutoTypeTable path="../../kit/www/ui/src/components/tour.tsx" name="TourPreviousProps" />

### Next

`TourNextProps`

<AutoTypeTable path="../../kit/www/ui/src/components/tour.tsx" name="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
----------------

<ComponentPreview name="use-copy-to-clipboard-demo" description="A simple hook to copy to clipboard." align="center" />

## Installation

<Steps>
  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="use-copy-to-clipboard" title="hooks/use-copy-to-clipboard.ts" />
</Steps>

## Usage

```tsx showLineNumbers
import { useCopyToClipboard } from '@kit/ui/hooks/use-copy-to-clipboard';
```

```tsx showLineNumbers
const { copyToClipboard, isCopied } = useCopyToClipboard();

return (
    <Button
        aria-label="Copy to clipboard"
        onClick={() => copyToClipboard(TEXT_TO_COPY)}
    >
        {isCopied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
    </Button>
)
```

## 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.

<ComponentPreview name="use-delay-demo" description="A delay hook component" align="center" />

## Installation

<Steps>
  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="use-delay" title="hooks/use-delay.ts" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## 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 : `<T>(value: T, delayMs: number) => T`

### useFnDelay

Takes :

```ts
<T>(
    asyncFactory: (delay: (timeMs: number) => Promise<void>) => Promise<T>,
    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.

<ComponentPreview name="number-input-demo" description="A input number component that use the useInputDragControl hook to implement the drag behavior." align="center" />

## Installation

<Steps>
  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="use-input-drag-control" title="hooks/use-input-drag-control.ts" />

  <Step>Nothing else, no dependencies.</Step>
</Steps>

## 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.

<Image src="/docs/number-input-key-step-factor.light.png" themed size="sm" width="630" height="430" alt="Number Input component anatomy" />

## API Reference

`UseInputDragControlParams`

<AutoTypeTable path="../../kit/www/ui/src/hooks/use-input-drag-control.ts" name="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

<ComponentPreview name="dialog-demo" description="An animated dialog component" align="center" />

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.

<Callout>
  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
</Callout>

## Installation

<Steps>
  <Step>Install the following dependencies:</Step>

  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
  ```

  <Step>Make sure that the following radix [portal](https://www.radix-ui.com/primitives/docs/utilities/portal) is present in your project</Step>

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="use-delay" title="hooks/use-delay.ts" />

  <ComponentSource name="dialog" title="components/motion/dialog.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

### Anatomy

```tsx showLineNumbers
import { Dialog, DialogAnimatePresenceDiv, DialogContent, DialogMotionImage, DialogMotionImageWrapper, DialogOverlay, DialogPortal, DialogTrigger } from '@kit/ui/motion/dialog';
```

```tsx showLineNumbers
 <Dialog>
    <DialogTrigger className="w-48 h-56">
        <DialogMotionImageWrapper layoutId="my-img">
            <DialogMotionImage />
        </DialogMotionImageWrapper>

        <DialogMotionDiv layoutId="my-div" />
    </DialogTrigger>

    <DialogPortal>
        <DialogContent className="w-[560px] h-[560px]">
            <DialogMotionImageWrapper layoutId="my-img">
                <DialogMotionImage />
            </DialogMotionImageWrapper>

            <DialogMotionDiv layoutId="my-div" />

            <DialogAnimatePresenceDiv />
        </DialogContent>
        <DialogOverlay />
    </DialogPortal>
</Dialog>
```

<Image src="/docs/dialog-anatomy.light.png" themed size="full" width="900" height="650" alt="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 `<AnimatePresence>` component.

<Callout variant="info" icon="Info" title="To know more">
  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.
</Callout>

Here is a schema that tries to illustrate what we said above:

<Image src="/docs/dialog-motion-layout-schema.light.png" themed size="full" width="780" height="560" alt="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

<Callout title="For those who know motion">
  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.
</Callout>

| Layout component                                                                                                 | Non-layout component                                                                                               |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `DialogTrigger`, `DialogContent`, `MotionImageWrapper`, `MotionImage`,`DialogMotionDiv` (with a `layoutId` prop) | `DialogAnimatePresenceDiv`, `DialogOverlay`, `DialogPortal`, `DialogClose`, `DialogMotionDiv` (without `layoutId`) |

## Examples

### Variant 1

<ComponentPreview name="dialog-single-variant-1" description="A single variant dialog, variant 1" align="center" />

### Variant 2

<ComponentPreview name="dialog-single-variant-2" description="A single variant dialog, variant 2" align="center" />

### Netflix card

<ComponentPreview name="dialog-netflix-variant" description="A single variant dialog, variant netflix card" align="center" />

## 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:

<Image src="/docs/dialog-timeline.light.png" themed size="full" width="930" height="420" alt="Dialog timeline" />

<Callout>
  **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.
</Callout>

### 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
<DialogAnimatePresenceDiv
    onceOpen
    durationFactor={0.4}
    delayFactor={0.8}
    initial={{ opacity: 0 }}
    animate={{ opacity: 1 }}
    exit={{ opacity: 0 }}
    transition={{ type: 'tween', ease: 'linear' }}
    className="absolute inset-0 z-10 h-[520px]"
>
    {children}
</DialogAnimatePresenceDiv>
```

```tsx showLineNumbers
<DialogMotionDiv
    className={cn(
        'absolute inset-0 z-10 h-[520px]',
        'duration-[var(--dialog-duration-40)]',
        'data-[open=true]:opacity-100',
        'data-[open=false]:opacity-0'
    )}
>
    {children}
</DialogMotionDiv>
```

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
<div
    className={cn(
        'absolute inset-0 z-10 h-[520px]',
        'duration-[var(--dialog-duration-40)]',
        'group-data-[open=true]/dialog:opacity-100',
        'group-data-[open=false]/dialog:opacity-0'
    )}
>
    {children}
</div>
```

## 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`

<AutoTypeTable path="../../kit/www/ui/src/motion/dialog.tsx" name="DialogProps" />

### Trigger

The *Trigger* has the same `layoutId` than the *Content* component.

Props: `Omit<HTMLMotionProps<'div'>, 'layoutId' | 'transition'> & React.PropsWithChildren`

### Content

The *Content* has the same `layoutId` than the *Trigger* component.

<AutoTypeTable path="../../kit/www/ui/src/motion/dialog.tsx" name="DialogContentProps" />

### MotionImageWrapper

<AutoTypeTable path="../../kit/www/ui/src/motion/dialog.tsx" name="DialogLayoutProps" />

### MotionImage

<AutoTypeTable path="../../kit/www/ui/src/motion/dialog.tsx" name="DialogLayoutProps" />

### 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 `<AnimatePresence>` and open state effect to trigger `motion` *initial*, *animate* and *exit* animation states.

`DialogAnimatePresenceDivProps`

<AutoTypeTable path="../../kit/www/ui/src/motion/dialog.tsx" name="DialogAnimatePresenceDivProps" />

### Overlay

Props: `Omit<HTMLMotionProps<'div'>, 'layoutId'>`

### Portal

The radix [portal](https://www.radix-ui.com/primitives/docs/utilities/portal) component.

### Close

Props: `HTMLMotionProps<'button'>`


# 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
---------------

<ComponentPreview name="glow-demo" description="A glowing effect component" align="center" />

## Installation

<Steps>
  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="glow" title="components/motion/glow.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { Glow, GlowingDiv } from '@kit/ui/motion/glow';
```

```tsx showLineNumbers
<Glow color="#ff8a0d" radius={180} revertToInitialOnLeave>
    <div className="rounded-xl size-64">
        <GlowingDiv borderWidth={2} />
    </div>
</Glow>
```

## Features

* Efficient and performant animations
* Powered by motion library
* Use SVG mask feature for efficient rendering

## API Reference

### Props

### Root

<AutoTypeTable path="../../kit/www/ui/src/motion/glow.tsx" name="GlowRootProps" />

### Div

<AutoTypeTable path="../../kit/www/ui/src/motion/glow.tsx" name="GlowingDivProps" />


# 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
---------------

<ComponentPreview name="mutable-device-mockup-demo" description="A mutable device mockup component" className="[&_[data-tab=preview]]:overflow-hidden" align="center" />

## Installation

<Steps>
  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="mutable-device-mockup" title="components/motion/mutable-device-mockup.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import {
    Camera,
    DeviceContent,
    DeviceSelector,
    Keyboard,
    MobileButtons,
    MutableDeviceMockupRoot,
    Screen,
    TopBar,
    Viewport,
} from '@kit/ui/motion/mutable-device-mockup';
```

```tsx showLineNumbers
<MutableDeviceMockupRoot defaultDevice="ios" toggleDeviceOnClick>
    <DeviceSelector />
    <Viewport origin="top" className="aspect-678/409 w-full">
        <Screen>
            <Camera />
            <TopBar />
            <MobileButtons />

            <DeviceContent
                visibleIf={'desktop'}
                className="flex items-center justify-center pb-0"
                visibleAfter={5}
            >
                {/* Desktop content */}
            </DeviceContent>
            <DeviceContent
                visibleIf={['android', 'ios']}
                className="flex items-center justify-center pb-0"
            >
                {/* Android and iOS content */}
            </DeviceContent>
        </Screen>
    </Viewport>
    <Keyboard />
</MutableDeviceMockupRoot>
```

## Features

* MacOS, iPhone and Android mockups.
* Animated transitions.
* Powered by motion library
* Radix components architecture.

## API Reference

### Root

`MutableDeviceMockupRootProps`

<AutoTypeTable path="../../kit/www/ui/src/motion/mutable-device-mockup.tsx" name="MutableDeviceMockupRootProps" />

### Selector

`DeviceSelectorProps`

<AutoTypeTable path="../../kit/www/ui/src/motion/mutable-device-mockup.tsx" name="DeviceSelectorProps" />

### Viewport

<AutoTypeTable path="../../kit/www/ui/src/motion/mutable-device-mockup.tsx" name="ViewportProps" />

### Screen

The screen of all the devices.

`React.PropsWithChildren`

### Keyboard

The macOS keyboard.

### MacOSTopBar

`MacOSTopBarProps`

<AutoTypeTable path="../../kit/www/ui/src/motion/mutable-device-mockup.tsx" name="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`

<AutoTypeTable path="../../kit/www/ui/src/motion/mutable-device-mockup.tsx" name="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

All the steps to install and keep up to date the creatorem saas kit.
        
***

title: Configuration
description: All the steps to install and keep up to date the creatorem saas kit.
---------------------------------------------------------------------------------

## App config

The `app.config.ts` file is used to get the application name, description, ...
If also implements [email templates](/docs/web/features/emails/templates) data in the `email` attribute.

```ts
import { parseAppConfig } from '@kit/shared/config';

export const appConfig = parseAppConfig({
    name: 'acme',
    title: 'Acme | Your company goals.',
    description: 'Acme is a company that helps you achieve your goals.',
    theme: 'light',
    email: {
        template: {
            logo: {
                url: routes.url + '/images/logo-name.png',
                width: 176,
                height: 32,
            },
        },
        contactEmail: 'hello@acme.com',
        supportEmail: 'hello@acme.com',
    },
});
```

`AppConfig`

<AutoTypeTable path="../../kit/shared/src/config/app-config.ts" name="AppConfig" />

## Routes constants

It is very handy to have a constants routes object to easliy the different routes of your applications.

All the routes are stored in `kit/shared/config/routes.ts` file.

### Routes usage

```tsx
import { dashboardRoutes, marketingRoutes } from '@kit/shared/config';

export default function Home() {
    return (
        <div>
            <Link href={dashboardRoutes.paths.auth.signIn}>Login</Link>
            <Link href={marketingRoutes.url}>Marketing</Link>
        </div>
    );
}

```


# 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

Implement your own documentation website with Fumadocs.
        
***

title: Deployment
description: Implement your own documentation website with Fumadocs.
--------------------------------------------------------------------

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
```

<Callout variant="note">
  You can find your project ref in your Supabase dashboard URL: `https://supabase.com/dashboard/project/your-project-ref`
</Callout>

### 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"

<Callout variant="note">
  By default the `Email` provider will be enabled.
</Callout>

### 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.

<Steps>
  <Step>Go to Authentication > Auth Hooks.</Step>

  <Step>Click on "Add a new hook" and select "Send Email hook".</Step>

  <Step>Hook type select "HTTPS"</Step>

  <Step>In the URL field use : [https://your-domain-name.com/api/auth-hook](https://your-domain-name.com/api/auth-hook)</Step>

  <Callout>
    Require that the [auth-hook api endpoint](docs/web/features/authentication) is set in your application.
  </Callout>

  <Step>Then generate a "Secret" token and keep it.</Step>

  You gonna need to to set the `AUTH_WEBHOOK_SECRET` environment variable in the vercel dashboard.
</Steps>

### 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.

<Steps>
  <Step>Go to "Authentication" > "URL Configuration" and add your application url and the allowed redirect URLs.</Step>

  <Step>In "Site URL" field, enter the application url where the auth feature is deployed.</Step>

  <Step>In "Redirect URLs" field, enter something like this: `http://localhost:3000/auth/callback`</Step>
</Steps>

### Expose the `kit` and `storage` database schema

<Steps>
  <Step>Go to "Project Settings" > "Data API".</Step>

  <Step>In the "Exposed schemas" field, add the `kit` and `storage` schema.</Step>

  <Step>In the "Extra search path" field, add the `kit` table.</Step>

  <Step>Click on "Save".</Step>
</Steps>

<Callout>
  You can safely expose the `kit` and `storage` schema because their are protected by RLS policies.
</Callout>

## 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
```


# web: Environment Variables
URL: /docs/web/environment-variables
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/(root)/environment-variables.mdx

All the environment variables you need to configure the creatorem saas kit.
        
***

title: Environment Variables
description: All the environment variables you need to configure the creatorem saas kit.
----------------------------------------------------------------------------------------

To implement


# web: Introduction
URL: /docs/web
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/(root)/index.mdx

Provides all the tools you need to build scalable saas applications.
        
***

title: Introduction
description: Provides all the tools you need to build scalable saas applications.
---------------------------------------------------------------------------------

## Our mission

The goal is to deploy applications as fast as possible. This includes :

* you new projects
* existing applications

<Callout>
  To improve readability, some packages use a [config file](/docs/web/configuration) to configure the behavior of the package features.
</Callout>

## Our stack

* [turborepo](https://turborepo.org/) : Turborepo is a build system for monorepos, built by vercel.
* [turbopack](https://turbo.build/pack) : Turbopack is a fast, disk space efficient package manager for JavaScript, built by vercel.
* [next.js](https://nextjs.org/) : Next.js is a framework for building server-side rendered and static websites using React, built by vercel.
* [pnpm](https://pnpm.io/) : pnpm is a fast, disk space efficient package manager for JavaScript.
* [supabase](https://supabase.com/) : Supabase is a open source firebase alternative, built by supabase.
* [tailwindcss](https://tailwindcss.com/) : Tailwind CSS is a utility-first CSS framework for rapidly building custom user interfaces.
* [shadcn/ui](https://ui.shadcn.com/) : Shadcn/UI is a library of reusable UI components for React, built by shadcn.
* [react](https://react.dev/) : React is a library for building user interfaces, built by facebook.

## Monorepo structure

<Files>
  <Folder name="your-saas-comes-here" defaultOpen>
    <Folder name="apps" defaultOpen>
      <Folder name="dashboard">
        <Folder name="app">
          <Folder name="other-endpoints">
            <File name="..." />
          </Folder>

          <File name="globals.css" />

          <File name="layout.tsx" />

          <File name="not-found.tsx" />

          <File name="page.tsx" />
        </Folder>

        <File name="next.config.ts" />

        <File name="package.json" />
      </Folder>

      <Folder name="marketing">
        <Folder name="app">
          <Folder name="other-endpoints">
            <File name="..." />
          </Folder>

          <File name="globals.css" />

          <File name="layout.tsx" />

          <File name="not-found.tsx" />

          <File name="page.tsx" />
        </Folder>

        <File name="next.config.ts" />

        <File name="package.json" />
      </Folder>

      <Folder name="...">
        <File name="..." />
      </Folder>
    </Folder>

    <Folder name="kit" defaultOpen>
      <Folder name="i18n">
        <Folder name="src">
          <Folder name="components">
            <File name="button.tsx" />
          </Folder>

          <File name="i18n.client.ts" />

          <File name="i18n.server.ts" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="...">
        <File name="..." />
      </Folder>
    </Folder>

    <Folder name="supabase">
      <Folder name="migrations">
        <File name="20250817141810_generated_from_schemas.sql" />
      </Folder>

      <Folder name="schemas">
        <File name="000-privileges.sql" />

        <File name="001-enums.sql" />

        <File name="nnn-other-schemas.sql" />
      </Folder>

      <Folder name="tests">
        <File name="kit_base.test.sql" />

        <File name="other.test.sql" />
      </Folder>

      <File name="config.toml" />

      <File name="seed.sql" />
    </Folder>

    <Folder name="tooling" defaultOpen>
      <Folder name="eslint-config">
        <Folder name="src">
          <File name="index.ts" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="prettier-config">
        <Folder name="src">
          <File name="index.ts" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="tailwind-config">
        <Folder name="src">
          <File name="theme.css" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="tsconfig">
        <Folder name="src">
          <File name="index.ts" />
        </Folder>

        <File name="components.json" />

        <File name="package.json" />
      </Folder>

      <Folder name="...">
        <File name="..." />
      </Folder>
    </Folder>

    <File name="package.json" />

    <File name="turbo.json" />
  </Folder>
</Files>

* `apps` : The applications of your saas.
* `kit` : All packages of your saas.
* `supabase` : The supabase configuration.
* `tooling` : Contains dev tools configurations like eslint, prettier, tailwind, tsconfig, etc.


# 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

Implement your own documentation website with Fumadocs.
        
***

title: Documentation
description: Implement your own documentation website with Fumadocs.
links:
'Fumadocs': "[https://fumadocs.dev](https://fumadocs.dev)"
'Marketing App': "/marketing/docs"
----------------------------------

<Callout>
  Check the [Fumadocs page](/docs/web/features/cms/fumadocs) to learn more about Fumadocs in the kit.
</Callout>

## Overview

We use [Fumadocs](https://fumadocs.dev) to implement comprehensive documentation websites across our applications. The marketing application includes a fully functional Fumadocs implementation that serves as a reference for building your own documentation sites.

## Fumadocs Implementation

### In the Marketing Application

The marketing app demonstrates a complete Fumadocs setup with the following structure:

**Configuration**

* `source.config.ts` - Defines the documentation source with MDX options using `@kit/fumadocs/mdx-options`
* Content stored in `content/docs/` directory with structured folders and MDX files
* Metadata configuration through `meta.json` files for navigation structure

**Layout & Navigation**

* `app/docs/layout.tsx` - Main layout with `DocsProvider` and `DocsSidebar` components
* `app/docs/[[...slug]]/page.tsx` - Dynamic page rendering with breadcrumbs, navigation, and table of contents
* Responsive sidebar navigation with collapsible tree structure

**Features**

* Static generation for optimal performance (`generateStaticParams`)
* SEO-friendly metadata generation (`generateMetadata`)
* Table of contents with scroll-to-top functionality
* Previous/next page navigation
* Copy page content and AI-powered search features

### Key Components Used

The implementation leverages the `@kit/fumadocs` package which provides:

* Pre-configured MDX options with syntax highlighting
* Custom MDX components for rich documentation content
* UI components like `DocsSidebar`, `DocsBottomNavigation`, and `DocsBreadcrumb`
* LLM processing utilities for AI-powered features

## Getting Started

To implement Fumadocs in your own application:

1. **Install Dependencies**: Follow the [Fumadocs quick start guide](https://fumadocs.dev/docs/getting-started/quick-start)
2. **Configure Source**: Set up your `source.config.ts` similar to the marketing app
3. **Create Layout**: Implement the docs layout with sidebar and navigation
4. **Add Content**: Structure your documentation in MDX files
5. **Customize Styling**: Apply your theme and branding

## Learn More

For detailed information about the Fumadocs API, components, and advanced features, see the [Fumadocs documentation](/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

Tools to monitor your application, to track errors and events.
        
***

title: Monitoring
description: Tools to monitor your application, to track errors and events.
links:
'Sentry': "[https://sentry.io/](https://sentry.io/)"
----------------------------------------------------

In this page, we will see how to setup monitoring in your application.

<Callout>
  This feature is implemented in the `@kit/monitoring` package.
</Callout>

We are using [Sentry](https://sentry.io/) as monitoring provider.

<Callout variant="info">
  **Note:** No need to use this package if you want to use the vercel monitoring provider, just follow the
  instructions in the [Vercel docs](https://vercel.com/docs/query/monitoring/quickstart).
</Callout>

## Installation

### Project Setup

<Steps>
  <Step>Make sure that the `@kit/monitoring` package is installed.</Step>

  ```bash
  npm install '@kit/monitoring@workspace:*'
  ```

  <Step>Paste the following code in your `instrumentation.ts` file of your application.</Step>

  ```ts title="instrumentation.ts" showLineNumbers {1}
  import { MonitoringProvider } from '@kit/monitoring';

  export const register = MonitoringProvider.register;
  export const onRequestError = MonitoringProvider.captureRequestError;

  ```

  <Step>The next step is to set the **sentry** environment variables.</Step>
</Steps>

### Sentry Setup

Here is where you will find the **sentry** environment variables.

| Environment Variable     | Description                                                                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SENTRY_ORG`             | The organization slug. <br /> Go to Sentry > Settings > [Organization](https://sentry.io/settings/organization/). <br />You can also find it in the url subdomain.         |
| `SENTRY_PROJECT`         | The project name. <br /> Present in the url after `/projects/`                                                                                                             |
| `NEXT_PUBLIC_SENTRY_DSN` | The Sentry DSN. <br /> Go to the [project settings](https://sentry.io/settings/projects/) page. Then click on `Client Keys (DSN)`.                                         |
| `SENTRY_AUTH_TOKEN`      | The Sentry auth token. <br /> Go to Sentry > Sentry > [Organization Tokens](https://sentry.io/settings/auth-tokens/) <br /> Then create and copy a token for your project. |

## Environment variables

```dotenv showLineNumbers noCollapse
# ============================================
# 📈 MONITORING & ERROR TRACKING
# ============================================

SENTRY_ORG="your-sentry-org"
SENTRY_PROJECT="your-sentry-project"
NEXT_PUBLIC_SENTRY_DSN='https://xxxxxxxxxxx@xxxxx.ingest.de.sentry.io/xxxxxxxx'
SENTRY_AUTH_TOKEN="your-sentry-auth-token"
```


# 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

Keep your users aware of your progress with a smooth roadmap process.
        
***

title: Roadmap
description: Keep your users aware of your progress with a smooth roadmap process.
links:
'Notion': "[https://www.notion.com](https://www.notion.com)"
------------------------------------------------------------

<Video src="/docs/notion/roadmap-update.mp4" title="Update your roadmap in real-time to keep your users aware of your progress" size="full" muted autoPlay loop controls={false} />

We offer you the ability to keep your users aware of your progress with a smooth roadmap process using [notion](/docs/web/features/cms/notion).

## Setup

See the [notion](/docs/web/features/cms/notion) documentation to setup your roadmap. Same way as implementing a blog with notion.

But instead you gonna use this notion database template :

<DownloadButton href="/docs/notion/database-templates/Roadmap.csv" filename="Roadmap.csv" className="mx-auto">
  Roadmap Template
</DownloadButton>

<Callout>
  We recommend you to use our template to make it work with the already existing ui. But you can customize it to your needs.
</Callout>

Instead of setting the `NOTION_POSTS_DB_ID`, you gonna set the `NOTION_ROADMAP_DB_ID`.

## Content type definition requirements

### Required fields

Here is the list of the required fields for a content type definition:

* `title`: `title`
* `status`: `status`

<Callout>
  Contrary to the other notion content type definitions, you do not need to have a `slug` field.
</Callout>

## Config file

Your config file should look like this:

```ts showLineNumbers title="config/cms.config.ts" {21-30}
'server-only';

import { parseNotionConfig } from '@kit/notion/config';
import { envs } from '~/envs';

export const notionConfig = parseNotionConfig({
    auth: envs().NOTION_INTEGRATION_SECRET,
    contentTypes: {
        posts: {
            id: envs().NOTION_POSTS_DB_ID,
            def: {
                categories: 'multi_select',
                language: 'select',
                description: 'rich_text',
                slug: 'rich_text',
                image: 'files',
                status: 'status',
                title: 'title',
            },
        },
        roadmap: {
            id: envs().NOTION_ROADMAP_DB_ID,
            def: {
                status: 'status',
                tags: 'multi_select',
                priority: 'select',
                deadline: 'date',
                title: 'title',
            },
        },
    },
});

```

## Environment variables

```dotenv
NOTION_ROADMAP_DB_ID="your-database-source-id"
```


# web: Settings
URL: /docs/web/features/settings
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/settings.mdx

Manage your application settings with ease.
        
***

title: Settings
description: Manage your application settings with ease.
--------------------------------------------------------

The `@kit/settings` package is a type-safe settings management system designed to simplify the development of settings pages. It provides a declarative approach to define, store, and render settings with built-in support for multiple storage providers, form validation, and UI rendering.

## The problem

When you want to implement a settings section in your application, you need to:

* Define the page endpoints
* Fetch the settings from the database
* Render a settings form with `react-hook-form` to handle type validation
* Handle the form submission to the database
* Request the setting to the database to reuse it in the appropriate place

As you have to do this for each settings page, it leads to a lot of duplicated code.

<Callout variant="destructive">
  For those reasons, manual implementation is **painful**, **error-prone**, **hard to maintain** and you have to handle the UI by yourself.
</Callout>

## The solution

To solve this, we chose an architecture close to a MVC (Model-View-Controller) architecture.

<Image src="/docs/web/settings-solution.light.png" themed size="full" width="740" height="680" alt="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.

## Features

* **Centralized Configuration**: Define all settings in a single object
* **Type Safety**: Full typescript support with autocompletion for setting keys
* **Database Connection**: Automatically fetch and save settings to the appropriate database tables
* **Schema Validation**: Uses Zod schemas for validation before database update
* **Form Generation**: Automatically generate forms
* **Navigation**: Built-in navigation UI
* **Customization**: Easily add custom UI and storage providers

<Callout title="Key Benefits" icon="WandSparkles">
  **For developers**, it makes it easier to maintain and add new settings in no time.<br />
  **For applications**, it provides a consistent settings UI across the application.
</Callout>

## Setup

If you are using the `apps/dashboard` application, you can skip this section and go to the [Add a new settings page](#add-new-settings) section.

<Steps>
  <Step>Installation</Step>

  ```bash
  npm install '@kit/settings@workspace:*'
  ```

  <Step>Create Settings Configuration</Step>

  ```tsx title="config/settings.config.tsx" showLineNumbers
  import { createSettingModel } from '@kit/settings';
  import { getDBClient } from '~/lib/get-db-client';
  import { z } from 'zod';
  // other imports...

  export const settingsModel = createSettingModel(
      'your-settings-id',
      getDBClient,
      {
          // User Profile Settings
          user_profile_url: {
              schema: z.string().nullable().default(null),
              storage: 'user_attributes',
          },
          user_name: {
              schema: z.string().default(''),
              storage: 'user_attributes',
          },
          user_phone: {
              schema: z.string().nullable().default(null),
              storage: 'user_attributes',
          },
          user_bio: {
              schema: z.string().max(500).default(''),
              storage: 'user_settings',
          },

          // Appearance Settings
          // other settings...
      },
      [
          {
              group: 'index',
              label: 'About you',
              settingsPages: [
                  {
                      // match : "/" endpoint
                      slug: 'index',
                      icon: <Icon.user className="h-4 w-4" />,
                      title: 'Profile',
                      description: 'User profile settings',
                      settings: [
                          {
                              type: 'form',
                              id: 'profile-form',
                              header: (
                                  <>
                                      <div className="text-2xl font-bold">Profile</div>
                                      <Muted>Edit your profile information here.</Muted>
                                  </>
                              ),
                              submitButton: {
                                  text: 'Save Profile',
                              },
                              settings: [
                                  {
                                      type: 'user_media',
                                      slug: 'user_profile_url',
                                      label: 'Profile URL',
                                      triggerClassName: 'h-48 w-48 rounded-full',
                                      imageClassName: 'w-full h-full object-cover',
                                      placeholder: <AvatarPlaceholder className="size-full text-6xl" />,
                                  },
                                  {
                                      type: 'text',
                                      slug: 'user_name',
                                      label: 'Name',
                                      description:
                                          'May appear when you are mentioned or when you add content to the platform',
                                  },
                                  {
                                      type: 'textarea',
                                      slug: 'user_bio',
                                      label: 'Bio',
                                      description: 'Tell us more about yourself',
                                  },
                                  {
                                      type: 'ui',
                                      render: <Separator />, // to add custom ui
                                  },
                                  {
                                      type: 'phone',
                                      slug: 'user_phone',
                                      label: 'Phone',
                                      description: 'Used for authentication purposes only',
                                  },
                              ],
                          },
                      ],
                  },
                  // set you other pages here {...},
              ],
          },
          // other page groups here {...},
      ]
  );

  ```

  <Step>Add the settings pages</Step>

  ```tsx title="app/settings/[[...settings]]/page.tsx" showLineNumbers {15,22}
  'use server';

  import React from 'react';

  import { SettingSaveButtonAnchor, SettingsPages } from '@kit/settings/ui';
  import { settingsModel } from '~/config/settings.config';

  async function SettingsPage({
      params,
  }: {
      params: {
          settings: string[];
      };
  }): Promise<React.JSX.Element> {
      const awaitedParams = await params;
      return (
          <div className="flex flex-col">
              <div className="flex h-24">{/* your top bar component */}
                  <SettingSaveButtonAnchor />{/* display a save button outside of the settings pages */}
              </div>
              <div className="flex-1">
                  <SettingsPages model={settingsModel} params={awaitedParams} />
              </div>
          </div>
      );
  }

  export default SettingsPage;

  ```

  <Step>Use the settings sidebar</Step>

  First you need to get the ui config from the server.

  ```tsx title="app/dashboard/[slug]/layout.tsx" showLineNumbers {11,15}
  'use server';

  import React from 'react';
  import { settingsModel } from '~/config/settings.config';
  import { SettingsSidebar } from '~/components/settings-sidebar';

  export default async function OrganizationLayout({
      children,
  }: React.PropsWithChildren): Promise<React.JSX.Element> {
      // we must serialize the ui config to use it client side
      const uiConfig = settingsModel.getSerializedUIConfig();

      return (
          <div className="flex h-screen flex-row overflow-hidden">
              <SettingsSidebar uiConfig={uiConfig} />
              <div className="flex-1">{children}</div>
          </div>
      );
  }
  ```

  Then you can use the settings sidebar component in your layout.

  ```tsx title="components/settings-sidebar.tsx" showLineNumbers {10-13}
  'use client';

  import React from 'react';
  import { SettingsNavigation, type UIConfig } from '@kit/settings';
  import { ScrollArea } from '@kit/ui/scroll-area';

  export default function SettingsSidebar({ uiConfig }: { uiConfig: UIConfig<any>[] }): React.JSX.Element {
      return (
          <ScrollArea className="h-full">
              <SettingsNavigation
                  uiConfig={uiConfig}
                  basePath={"/settings"}
              />
          </ScrollArea>
      );
  }

  ```

  <Step>Use the settings in your codebase</Step>

  ```tsx title="somewhere-in-your-codebase.tsx" showLineNumbers {1,4}
  import { settingsModel } from '~/config/settings.config';

  export default async function SomewhereInYourCodebase() {
      const { 'user_name': userName } = await settingsModel.getSettings(['user_name']);
      return <div>{userName}</div>;
  }

  ```
</Steps>

<Callout>
  `settingsModel` works only on the server side.
</Callout>

## Add new settings

Now that you have your settings model, you can add new settings to it.

Let's try to add a `use_full_width` setting to the settings model.

<Steps>
  <Step>Add the setting to the settings model</Step>

  We gonna use the `user_settings` storage provider. See the [Storage](#storage) section for more information.

  ```tsx title="config/settings.config.tsx" showLineNumbers {9-12,49-54}
  import { settingsModel } from '~/config/settings.config';
  import { z } from 'zod';

  export const settingsModel = createSettingModel(
      'your-settings-id',
      getDBClient,
      {
          // Your existing settings...
          use_full_width: {
              schema: z.boolean().default(false),
              storage: 'user_settings',
          },
          // Your existing settings...
      },
      // Your existing settings pages...
  [
          {
              group: 'index',
              label: 'About you',
              settingsPages: [
                  {
                      // match : "/" endpoint
                      slug: 'index',
                      icon: <Icon.user className="h-4 w-4" />,
                      title: 'Profile',
                      description: 'User profile settings',
                      settings: [
                          // Your existing settings...
                          {
                              type: 'form',
                              id: 'profile-form',
                              header: (
                                  <>
                                      <div className="text-2xl font-bold">Profile</div>
                                      <Muted>Edit your profile information here.</Muted>
                                  </>
                              ),
                              submitButton: {
                                  text: 'Save Profile',
                              },
                              settings: [
                                  // Your existing settings...
                                  {
                                      type: 'phone',
                                      slug: 'user_phone',
                                      label: 'Phone',
                                      description: 'Used for authentication purposes only',
                                  },
                                  {
                                      type: 'checkbox',
                                      slug: 'use_full_width',
                                      label: 'Use full width',
                                      description: 'Always display the application in full width on mobile and desktop',
                                  },
                                  // Your existing settings...
                              ],
                          },
                      ],
                  },
                  // set you other pages here {...},
              ],
          }
          // other page groups here {...},
      ]
  );
  ```

  <Step>The settings UI and database storage is already handled, just use your new `use_full_width` setting</Step>

  ```tsx title="somewhere-in-your-codebase.tsx" showLineNumbers {1,4}
  import { settingsModel } from '~/config/settings.config';

  export default async function SomewhereInYourCodebase({children}: React.PropsWithChildren) {
      const { checkbox } = await settingsModel.getSettings(['checkbox']);

      return <div className={cn(checkbox ? 'w-full' : 'w-1/2')}>
          {children}
      </div>;
  }

  ```
</Steps>

## Storage

The database storage is handled by the `StorageProvider`s.

`StorageProvider`

<AutoTypeTable path="../../kit/settings/src/setting-model.ts" type="StorageProvider" />

By default, two storage providers are present:

* `user_settings`: Stores settings in the `user_setting` table as row entries.
* `user_attributes`: Stores settings in the `user` table as column entries.

### Add new storage providers

You can pass new storage providers to the `createSettingModel` function.

<Callout variant="info">
  Must of the time you gonna save you settings to the database. But you are free to do whatever you want (localStorage, sessionStorage, use another api service, ...).
</Callout>

```tsx title="config/settings.config.tsx" showLineNumbers {6-19,27}
import { createSettingModel, type StorageProvider } from '@kit/settings';
import { getDBClient } from '~/lib/get-db-client';
import { z } from 'zod';
// other imports...

const yourNewStorageProvider: StorageProvider = {
    fetchFromStorage: async (keys: string[]) => {
        const db = await getDBClient();

        // do your things to fetch the settings record

        return settingsRecord; // {'key1': value1, 'key2': value2, ...}
    },
    saveToStorage: async (values: Record<string, any>) => {
        const db = await getDBClient();

        // save the settings where you want
    },
};

export const settingsModel = createSettingModel(
    'your-settings-id',
    getDBClient,
    {}, // schemas
    [], // ui config
    {
        your_new_storage_provider: yourNewStorageProvider,
    }
);

```

Now you can use your new storage provider in your settings model.

```tsx title="config/settings.config.tsx" showLineNumbers {11,17}
import { settingsModel } from '~/config/settings.config';
// ...

export const settingsModel = createSettingModel(
    'your-settings-id',
    getDBClient,
    {
        // ...
        your_new_setting: {
            schema: z.string().default(''),
            storage: 'your_new_storage_provider',
        },
        // ...
    },
    {}, // ui config
    {
        your_new_storage_provider: yourNewStorageProvider,
    }
);
```

## Inputs

<Callout>
  Under the hood, we are using the [Quick Form](/docs/ui/components/quick-form) component to generate the settings form.
</Callout>

By default, we add the following inputs to the QuickForm component :

* `user_media`: **UserSettingMedia** to manage user media
* `organization_media`: **OrganizationSettingMedia** to manage organization media

Check the [Media Manager](/docs/web/features/media-manager) page to learn more about the `user_media` and `organization_media` inputs.

<AutoTypeTable path="../../kit/settings/src/registered-inputs.ts" type="typeof REGISTERED_INPUTS" />


# web: Google Analytics
URL: /docs/web/features/analytics/google-analytics
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/analytics/google-analytics.mdx

Setup Google Analytics for your project.
        
***

title: Google Analytics
description: Setup Google Analytics for your project.
links:
'Google Analytics': "[https://analytics.google.com/](https://analytics.google.com/)"
------------------------------------------------------------------------------------

In this page, we will see how to setup Google Analytics for an application.

## To-do list

You will need to get your `GA_MEASUREMENT_ID` token. Here are the steps to get it:

<Steps>
  <Step>Go to the [Google Analytics](https://analytics.google.com/) website and create an account and a new property.</Step>

  <Step>In [Admin](https://analytics.google.com/analytics/web/#/?pagename=admin\&utm_source=gahc\&utm_medium=dlinks), under Data collection and modification, click [Data Streams](https://analytics.google.com/analytics/web/#/?pagename=admin-streams\&utm_source=gahc\&utm_medium=dlinks)</Step>

  <Step>Select the Web tab.</Step>

  <Step>You will get your `GA_MEASUREMENT_ID` at the top right corner.</Step>

  <Image src="/docs/web/google-analytics-measurement-id.png" alt="Google Analytics Measurement ID location" width="500" height="230" size="md" />
</Steps>

<Callout>
  If you have issues, you can also refer to the google [analytics developer guide](https://developers.google.com/analytics/devguides/collection/ga4) to get started.
</Callout>

## Useful links

* [Google Analytics](https://analytics.google.com/)
* [Find your Google Analytics Measurement ID](https://support.google.com/analytics/answer/12270356)
* [Google Analytics for developers](https://developers.google.com/analytics/devguides/collection/ga4)
* [Setup Google Analytics for a website or an app](https://support.google.com/analytics/answer/9304153)

## Environment variables

```dotenv showLineNumbers noCollapse
# ============================================
# 📊 ANALYTICS
# ============================================

# For Google Analytics
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
NEXT_PUBLIC_GA_DISABLE_LOCALHOST_TRACKING=true
NEXT_PUBLIC_GA_DISABLE_PAGE_VIEWS_TRACKING=false
```


# web: Analytics
URL: /docs/web/features/analytics
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/analytics/index.mdx

Tools to track user behavior and events using different analytics providers.
        
***

title: Analytics
description: Tools to track user behavior and events using different analytics providers.
-----------------------------------------------------------------------------------------

In this page, we will see how to setup analytics in your application.

<Callout>
  This feature is implemented in the `@kit/analytics` package.
</Callout>

<Callout variant="info">
  **Note:** No need to use this package if you want to use the `@vercel/analytics` package, just follow the
  instructions in the [Vercel docs](https://vercel.com/docs/analytics/quickstart).
</Callout>

## Installation

<Steps>
  <Step>Make sure that the `@kit/analytics` package is installed.</Step>

  ```bash
  npm install '@kit/analytics@workspace:*'
  ```

  <Step>Set your analytics config file to select your [provider](#providers).</Step>

  ```ts title="config/analytics.config.ts" showLineNumbers {3}
  import { createAnalyticsManager } from '@kit/analytics';

  export const analytics = createAnalyticsManager(['google']);
  ```

  <Step>Check the page documentation of your provider to see how to set the environment variables.</Step>

  * [Google Analytics](/docs/web/features/analytics/google-analytics)
  * [Umami](/docs/web/features/analytics/umami)
</Steps>

## Usage

Once the `@kit/analytics` package is setup, you can use the `analytics` object to track events and page views.

```tsx title="components/providers/analytics-provider.tsx" showLineNumbers {3,37,41,44,47,56}
'use client';

import { analytics } from '~/config/analytics.config';
import { ActionCallback, ActionSlug, enqueueAction, isBrowser, removeAction } from '@kit/shared';
import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';

type AnalyticsMapping = {
    [K in ActionSlug]?: ActionCallback<K>;
};

/**
 * Hook to subscribe to app events and map them to analytics actions
 * @param mapping
 */
function useAnalyticsMapping(mapping: AnalyticsMapping) {
    useEffect(() => {
        const subscriptions = Object.entries(mapping).map(([eventType, handler]) => {
            enqueueAction(eventType as ActionSlug, handler as ActionCallback<ActionSlug>);

            return () => removeAction(eventType as ActionSlug, handler as ActionCallback<ActionSlug>);
        });

        return () => {
            subscriptions.forEach((unsubscribe) => unsubscribe());
        };
    }, [mapping]);
}

/**
 * Define a mapping of app events to analytics actions
 * Add new mappings here to track new events in the analytics service from app events
 */
const analyticsMapping: AnalyticsMapping = {
    user_signed_in: ({ userId, ...traits }) => {
        if (userId) {
            return analytics.identify(userId, traits);
        }
    },
    user_signed_up: ({ method }: { method: 'magiclink' | 'password' }) => {
        return analytics.trackEvent('user_signed_up', { method });
    },
    checkout_started: ({ priceId, productId }: { priceId: string; productId: string }) => {
        return analytics.trackEvent('checkout_started', { priceId, productId });
    },
    user_updated: () => {
        return analytics.trackEvent('user_updated');
    },
};

function AnalyticsProviderBrowser(props: React.PropsWithChildren) {
    // Subscribe to app events and map them to analytics actions
    useAnalyticsMapping(analyticsMapping);

    // Report page views to the analytics service
    useReportPageView((url) => analytics.trackPageView(url));

    // Render children
    return props.children;
}

/**
 * Provider for the analytics service
 */
export function AnalyticsProvider(props: React.PropsWithChildren) {
    if (!isBrowser()) {
        return props.children;
    }

    return <AnalyticsProviderBrowser>{props.children}</AnalyticsProviderBrowser>;
}

/**
 * Hook to report page views to the analytics service
 * @param reportAnalyticsFn
 */
function useReportPageView(reportAnalyticsFn: (url: string) => unknown) {
    const pathname = usePathname();
    const searchParams = useSearchParams();

    useEffect(() => {
        const url = [pathname, searchParams.toString()].filter(Boolean).join('?');

        reportAnalyticsFn(url);
    }, [pathname, reportAnalyticsFn, searchParams]);
}
```

The last thing to do is to wrap your app with the `AnalyticsProvider` component.

## Environment variables

```dotenv showLineNumbers noCollapse
# ============================================
# 📊 ANALYTICS
# ============================================

# For Google Analytics
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
NEXT_PUBLIC_GA_DISABLE_LOCALHOST_TRACKING=true
NEXT_PUBLIC_GA_DISABLE_PAGE_VIEWS_TRACKING=false

# For Umami
NEXT_PUBLIC_UMAMI_HOST=https://your-umami-instance.com
NEXT_PUBLIC_UMAMI_WEBSITE_ID=1234567890
NEXT_PUBLIC_UMAMI_DISABLE_LOCALHOST_TRACKING=true
```


# web: Umami
URL: /docs/web/features/analytics/umami
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/analytics/umami.mdx

Umami is an open-source analytics solution.
        
***

title: Umami
description: Umami is an open-source analytics solution.
links:
'Umami Repository': "[https://github.com/umami-software/umami](https://github.com/umami-software/umami)"
'Umami Cloud': "[https://umami.is/](https://umami.is/)"
-------------------------------------------------------

In this page, we will see how to setup Umami for an application.

You can self host Umami yourself or use the [Umami cloud](https://umami.is/).

## To-do list

We assume that you already have your `NEXT_PUBLIC_UMAMI_HOST`, corresponding to the host of your Umami instance.

You will need to get your `UMAMI_WEBSITE_ID` token. Here are the steps to get it:

<Steps>
  <Step>Once logged in, go to the website page.</Step>

  <Step>Click on the `Tracking code` tab, .</Step>

  You should see a `script` tag looking like this:

  ```html
  <script
      async
      src="your-NEXT_PUBLIC_UMAMI_HOST"
      data-website-id="your-UMAMI_WEBSITE_ID"
  ></script>
  ```

  <Step>Copy paste the following values in your environment variables.</Step>

  The following values are the ones you should use in your `NEXT_PUBLIC_UMAMI_HOST` and `UMAMI_WEBSITE_ID` environment variables.

  | Attribute         | Value                    |
  | ----------------- | ------------------------ |
  | `src`             | `NEXT_PUBLIC_UMAMI_HOST` |
  | `data-website-id` | `UMAMI_WEBSITE_ID`       |
</Steps>

## Useful links

* [Umami docs](https://umami.is/docs/track-events)

## Environment variables

```dotenv showLineNumbers noCollapse
# ============================================
# 📊 ANALYTICS
# ============================================

# For Umami
NEXT_PUBLIC_UMAMI_HOST=https://your-umami-instance.com
NEXT_PUBLIC_UMAMI_WEBSITE_ID=1234567890
NEXT_PUBLIC_UMAMI_DISABLE_LOCALHOST_TRACKING=true
```


# web: Captcha
URL: /docs/web/features/authentication/captcha
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/authentication/captcha.mdx

Protect your app from spam with Cloudflare Turnstile CAPTCHA
        
***

title: Captcha
description: Protect your app from spam with Cloudflare Turnstile CAPTCHA
-------------------------------------------------------------------------

CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) is a security feature that
helps protect your application from automated abuse, spam, and malicious bots.

We use Cloudflare Turnstile CAPTCHA to protect forms from automated abuse and spam.

## Setup

<Steps>
  <Step>Get Cloudflare Turnstile keys at [cloudflare.com/products/turnstile](https://www.cloudflare.com/products/turnstile/)</Step>

  <Step>Add environment variables:</Step>

  ```bash
  # Client-side (safe to expose)
  NEXT_PUBLIC_CAPTCHA_SITE_KEY=your_site_key

  # Server-side (keep secret)
  CAPTCHA_SECRET_KEY=your_secret_key
  ```
</Steps>

## Client Setup

### Provider

Wrap your app with `CaptchaProvider`:

```tsx showLineNumbers {1,5}
import { CaptchaProvider } from '@kit/auth/captcha/client';

export function RootLayout({ children }) {
    return (
        <CaptchaProvider siteKey={process.env.NEXT_PUBLIC_CAPTCHA_SITE_KEY}>
            {children}
        </CaptchaProvider>
    );
}
```

#### Options

Customize CAPTCHA appearance:

```tsx showLineNumbers {4-8}
<CaptchaProvider
    siteKey={process.env.NEXT_PUBLIC_CAPTCHA_SITE_KEY}
    options={{
        options: {
            size: 'normal', // 'normal', 'invisible', 'compact'
            theme: 'light', // 'light', 'dark'
            language: 'en',
        }
    }}
>
    {children}
</CaptchaProvider>
```

##### Test

slut

###### subTest

# Hook usage

Use the hook in forms:

```tsx showLineNumbers {3,6,10,11,13}
'use client';

import { useCaptchaToken } from '@kit/auth/captcha/client';

export function ContactForm() {
    const { captchaToken, resetCaptchaToken } = useCaptchaToken();

    const handleSubmit = async (formData) => {
        try {
            await submitAction({ ...formData, captchaToken });
            resetCaptchaToken();
        } catch (error) {
            resetCaptchaToken(); // Allow retry
        }
    };

    return (
        <form onSubmit={handleSubmit}>
            {/* Your form fields */}
            <button type="submit">Submit</button>
        </form>
    );
}
```

## Server Setup

Use `captchaActionClient` for protected actions:

```ts showLineNumbers {3,12}
'use server';

import { captchaActionClient } from '@kit/auth/captcha/server';
import { z } from 'zod';

const schema = z.object({
    email: z.string().email(),
    message: z.string().min(10),
    // captchaToken is optional and verified automatically
});

export const submitContact = captchaActionClient
    .metadata({ actionName: 'submitContact' })
    .schema(schema)
    .action(async ({ parsedInput: { email, message } }) => {
        // CAPTCHA already verified if token provided

        // Your logic here
        console.log(`Contact: ${email} - ${message}`);

        return { success: true, message: 'Sent!' };
    });
```

For authenticated actions with CAPTCHA:

```ts showLineNumbers {1,3}
import { authCaptchaActionClient } from '@kit/auth/captcha/server';

export const protectedAction = authCaptchaActionClient
    .metadata({ actionName: 'protectedAction' })
    .schema(schema)
    .action(async ({ ctx: { db }, parsedInput }) => {
        // Has CAPTCHA verification + authenticated database access
        const user = await db.user.get();
        return { user };
    });
```

## Manual Verification

For custom server logic:

```ts showLineNumbers {1,7}
import { verifyCaptcha } from '@kit/auth/captcha/server';

export async function customAction(formData: FormData) {
    const token = formData.get('captchaToken');

    try {
        await verifyCaptcha(token);
        // Proceed with action
        return { success: true };
    } catch (error) {
        throw new Error('CAPTCHA verification failed');
    }
}
```


# web: Authentication
URL: /docs/web/features/authentication
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/authentication/index.mdx

The only authentication documentation page you need if you just want to setup the dashboard application.
        
***

title: Authentication
description: The only authentication documentation page you need if you just want to setup the dashboard application.
links:
'Supabase Auth': "[https://supabase.com/docs/guides/auth](https://supabase.com/docs/guides/auth)"
-------------------------------------------------------------------------------------------------

In this page, we will see :

* how to setup your database for authentication
* how to setup `apps/dashboard` for authentication

<Callout>
  This feature is implemented with the `@kit/auth` package and the [Supabase Auth](https://supabase.com/docs/guides/auth) features.
</Callout>

For now, only the `apps/dashboard` application implement the authentication feature.

<Callout variant="info">
  If you want to setup the authentication in another application, you must implement all the code that consume the `@kit/auth` package in `apps/dashboard`.
</Callout>

## Password

<Steps>
  <Step>Go to you `supabase/config.toml` file.</Step>

  <Step>To enable the email provider, make sure that the **auth.email** section matches the following code.</Step>

  ```toml
  [auth.email]
  # Allow/disallow new user signups via email to your project.
  enable_signup = true
  # If enabled, a user will be required to confirm any email change on both the old, and new email
  # addresses. If disabled, only the new email is required to confirm.
  double_confirm_changes = true
  # If enabled, users need to confirm their email address before signing in.
  enable_confirmations = true
  ```

  <Step>Set your `apps/dashboard/config/auth.config.ts` file to fit use the password provider.</Step>

  ```ts title="auth.config.ts" showLineNumbers {15}
  import { parseAuthConfig } from '@kit/auth/config';
  import { envs } from '~/envs';

  export const authConfig = parseAuthConfig({
      // NB: This is a public key, so it's safe to expose.
      // Copy the value from the Supabase Dashboard.
      captchaSiteKey: envs().NEXT_PUBLIC_CAPTCHA_SITE_KEY,

      // whether to display the terms checkbox during sign-up
      displayTermsCheckbox: true,

      // NB: Enable the providers below in the Supabase Console
      // in your production project
      providers: {
          password: true,
      },
  });
  ```
</Steps>

### Authentication emails

The password provider requires emails to work. As Supabase will send a **Confirm signup** email to the user.

<Callout title="Supabase auth emails in development environment">
  Local dev uses an "in bucket" port for showing what would be sent in email.

  Go to [http://localhost:54324/](http://localhost:54324/) to see the emails sent by Supabase.

  Use [custom SMTP server for production environment](/docs/web/features/emails#supabase)
</Callout>

## oAuth providers

<Steps>
  <Step>Go to you `supabase/config.toml` file.</Step>

  <Step>Add an external OAuth provider for the development environment. You can find all the supported oAuth providers in the [here](https://supabase.com/docs/guides/auth#social-auth).</Step>

  **For the example, we will add the Google provider.**

  ```toml
  [auth.external.google]
  enabled = true
  client_id = "env(SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_ID)"
  secret = "env(SUPABASE_AUTH_EXTERNAL_GOOGLE_SECRET)"
  redirect_uri = "env(SUPABASE_AUTH_EXTERNAL_REDIRECT_URI)"
  ```

  <Step>Go to the [Google Developer Console](https://console.cloud.google.com) and create a new OAuth client ID.</Step>

  Allow to access the following fields :

  * `.../auth/userinfo.email`
  * `.../auth/userinfo.profile`

  <Step>Create a new api key for web application to get the client id and secret.</Step>

  <Step>Set the environement variables in the database `.env` file at `supabase/.env`.</Step>

  ```dotenv showLineNumbers noCollapse
  SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_ID="your-google-client-id"
  SUPABASE_AUTH_EXTERNAL_GOOGLE_SECRET="your-google-secret"
  SUPABASE_AUTH_EXTERNAL_REDIRECT_URI="your-google-redirect-uri"
  ```

  <Step>Set your `apps/dashboard/config/auth.config.ts` file to fit use the new oAuth provider.</Step>

  ```ts title="auth.config.ts" showLineNumbers {16}
  import { parseAuthConfig } from '@kit/auth/config';
  import { envs } from '~/envs';

  export const authConfig = parseAuthConfig({
      // NB: This is a public key, so it's safe to expose.
      // Copy the value from the Supabase Dashboard.
      captchaSiteKey: envs().NEXT_PUBLIC_CAPTCHA_SITE_KEY,

      // whether to display the terms checkbox during sign-up
      displayTermsCheckbox: true,

      // NB: Enable the providers below in the Supabase Console
      // in your production project
      providers: {
          password: true,
          oAuth: ['google'],
      },
  });
  ```
</Steps>

## Environment variables

```dotenv showLineNumbers noCollapse
# ============================================
# AUTHENTICATION
# ============================================

# To adapt for your oAuth provider
SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_ID="your-google-client-id"
SUPABASE_AUTH_EXTERNAL_GOOGLE_SECRET="your-google-secret"
SUPABASE_AUTH_EXTERNAL_REDIRECT_URI="your-google-redirect-uri"
```


# web: Integration
URL: /docs/web/features/authentication/integration
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/authentication/integration.mdx

How to implement the authentication feature in an existing application.
        
***

title: Integration
description: How to implement the authentication feature in an existing application.
links:
'Supabase Auth': "[https://supabase.com/docs/guides/auth](https://supabase.com/docs/guides/auth)"
-------------------------------------------------------------------------------------------------

This guide explains how to implement the authentication feature in a new/existing application using the `@kit/auth` package.

## Installation

First, install the authentication package:

```bash showLineNumbers
npm install '@kit/auth@workspace:*'
```

## Configuration File

Create the authentication configuration in `config/auth.config.ts`.

This object will contain all customization options, allowing you to change the behavior of the authentication system.

You gonna pass this object to almost all the code coming from the `@kit/auth` package.

```ts title="config/auth.config.ts" showLineNumbers
import { parseAuthConfig } from '@kit/auth/config';

export const authConfig = parseAuthConfig({
    scopePatterns: {
        auth: '/auth/*?',
        private: '/your-protected-website-endpoints/*?',
    },
    urls: {
        home: '/your-protected-website-endpoints',
        callback: '/auth/callback',
        signIn: '/auth/sign-in',
        signUp: '/auth/sign-up',
        forgottenPassword: '/auth/forgotten-password',
        verifyMfa: '/auth/verify-mfa',
    },
    captchaSiteKey: process.env.NEXT_PUBLIC_CAPTCHA_SITE_KEY,
    displayTermsCheckbox: true,
    providers: {
        password: true,
        oAuth: ['google'],
    },
    passwordRequirements: {
        minLength: 3,
        maxLength: 99,
        specialChars: false,
        numbers: false,
        uppercase: false,
    },
});
```

`AuthConfig`

<AutoTypeTable path="../../kit/www/features/auth/src/config.ts" name="AuthConfig" />

## Proxy

```ts title="proxy.ts" showLineNumbers noCollapse {1,8,9}
import { authProxy } from '@kit/auth/proxy/auth';
import { NextResponse, type NextRequest } from 'next/server';
import { authConfig } from './config/auth.config';

export async function proxy(request: NextRequest): Promise<NextResponse<unknown>> {
    const response = NextResponse.next();

    const authResponse = await authProxy(request, response, authConfig);
    if (authResponse) return authResponse;

    // ...other proxy logic

    return response;
}

export const config = {
    matcher: ['/((?!_next/static|_next/image|images|locales|assets|api/*).*)'],
};
```

<Callout variant="info">
  When the `authResponse` is truthy, it means that the `authProxy` has handled the request and we don't need to execute other proxy.
</Callout>

## Auth Provider

You must wrap your app with the `AuthProvider` component.

<Callout>
  The `AuthProvider` component make sure that the user is authenticated.

  For instance, if the user logout in another tab, the `AuthProvider` will redirect the user to the sign in page for all tabs opened in the browser.
</Callout>

```tsx title="app/layout.tsx" showLineNumbers noCollapse {2,10,12}
import React from 'react';
import { AuthProvider } from '@kit/auth/ui/auth-provider';
import { authConfig } from '~/config/auth.config';

export default function Layout({ children }: React.PropsWithChildren) {
    
    return (
        <html>
            <body>
                <AuthProvider authConfig={authConfig}>
                    {children}
                </AuthProvider>
            </body>
        </html>
    );
}

```

`AuthProviderProps`

<AutoTypeTable path="../../kit/www/features/auth/src/ui/auth-provider.tsx" name="AuthProviderProps" />

<Callout variant="info">
  The `onEvent` props may be useful trigger action for monitoring or analytics purposes. Check the source code of the kit in the dashboard app for more details.
</Callout>

## Auth Pages

Now you need to create the authentication pages in a `app/auth/` directory.

To simplify as much as possible the integration, we created the following helper functions to generate the authentication pages:

| Function                                                   | Description                           |
| ---------------------------------------------------------- | ------------------------------------- |
| **createSignInPage** `(authConfig, joinOrganizationPath?)` | Generates the sign in page            |
| **createSignUpPage** `(authConfig)`                        | Generates the sign up page            |
| **createForgottenPasswordPage** `(authConfig)`             | Generates the forgotten password page |
| **createVerifyMfaPage** `(authConfig)`                     | Generates the MFA verification page   |

You just gonna need to pass the `authConfig` object to the helper function to generate the page.

### Example

```tsx title="app/auth/sign-in/page.tsx" showLineNumbers {4}
import { createSignInPage } from '@kit/auth/pages/sign-in';
import { authConfig } from '~/config/auth.config';

export default createSignInPage(authConfig, '/dashboard');
```

Now do the same for the other pages:

* `app/auth/sign-up/page.tsx`
* `app/auth/forgotten-password/page.tsx`
* `app/auth/verify-mfa/page.tsx`

<Callout variant="info">
  The `joinOrganizationPath` is optional and will be used to redirect the user to the organization page after the sign in. See the [organization](/docs/web/features/organization) feature integration guide for more details.
</Callout>

<Callout>
  If you want to customize the authentication pages deeply. Look at the source code of the kit pages functions, all of their components are exported from the package.
</Callout>

## Auth Routes

Same thing, we created the following helper functions to generate the authentication routes:

| Function                              | Description                                                               |
| ------------------------------------- | ------------------------------------------------------------------------- |
| **createCallbackRoute**`(authConfig)` | Generates the callback route used at the end of sign in and sign up flows |
| **createConfirmRoute**`(authConfig)`  | Generates the confirm route for the MFA flow                              |

### Example

Here is what the `app/auth/callback/route.ts` file will look like:

```ts title="app/auth/callback/route.ts" showLineNumbers {4}
import { createCallbackRoute } from '@kit/auth/routes/callback';
import { authConfig } from '~/config/auth.config';

export const GET = createCallbackRoute(authConfig);
```

Now do the same for the other route:

* `app/auth/confirm/route.ts`

<Callout variant="info">
  The `createCallbackRoute` and `createConfirmRoute` functions will return a function that can be used as a route handler.
</Callout>

## Setup your authentication providers

You still need to set your environment variables and the supabase authentication providers.

Follow the [previous](/docs/web/features/authentication/setup) page to setup your authentication provider.

## What's Next

You've successfully integrated the core authentication system into your application. The integration guide has covered:

Now you users will be able to sign in and sign up to your application.

But you still need to get the user data and handle the user logout to have a fully working authentication system.

In the next pages, you will learn how to:

| Page                                                                                           | Description                                                       |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [User Access](/docs/web/features/authentication/retrieve-user)                                 | Learn how to retrieve, display user information and logout a user |
| [Password Management](/docs/web/features/authentication/user-settings#authentication-provider) | Change password functionality and security features               |
| [Session Management](/docs/web/features/authentication/user-settings#session-management)       | View and manage active user sessions                              |
| [MFA Security](/docs/web/features/authentication/user-settings#multi-factor-authentication)    | Enable two-factor authentication                                  |
| [Account Deletion](/docs/web/features/authentication/user-settings#user-deletion)              | Delete a user account                                             |


# web: Retrieve User
URL: /docs/web/features/authentication/retrieve-user
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/authentication/retrieve-user.mdx

Retrieve the current user in your application.
        
***

title: Retrieve User
description: Retrieve the current user in your application.
-----------------------------------------------------------

Once the user is logged in, you will have to get the user data in your application. For this you will have to use the `@kit/auth/user` endpoint that expose all the tools you need for post-authentication actions.

<Callout>
  In this page, the `user` will be a row of the `public.user` table, different from the supabase `auth.user` table.

  *The goal of the `@kit/auth` package is to avoid you the pain to deals with the supabase `auth.user` table.*
</Callout>

## Server

```ts showLineNumbers {2,12-14,19}
'server-only';

import { getDrizzleSupabaseClient } from '@kit/db';
import { getSupabaseServerClient } from '@kit/supabase-server';

async function () {
    const supabaseClient = getSupabaseServerClient();
    const db = await getDrizzleSupabaseClient(supabaseClient);

    const user = await db.user.get();
};

```

## Client

### User Provider

The first thing you will have to do is to wrap your application with the `UserProvider` component.

```tsx title="app/dashboard/layout.tsx" showLineNumbers {2,12-14,19}
import React from 'react';
import { UserProvider } from '@kit/auth/user';
import { redirect } from 'next/navigation';
import { getDBClient } from '~/lib/get-db-client';

export default async function YourPrivateEndpointLayout(
    props: React.PropsWithChildren
): Promise<React.JSX.Element> {
    const db = await getDBClient();
    const user = await db.user.get();

    if (!user) {
        return redirect('/auth/sign-in');
    }
    if (!user.completedOnboarding) {
        return redirect('/onboarding');
    }

    return <UserProvider user={user}>{props.children}</UserProvider>;
}
```

<Callout variant="info">
  Line 12 refers to the [onboarding](/docs/web/features/authentication/onboarding) feature.
</Callout>

<Callout>
  `getDBClient` is just a shortcut to get the `db` object.
</Callout>

### User Hook

Use the `useUser` hook to access the current authenticated user:

```tsx showLineNumbers {3,6}
'use client';

import { useUser } from '@kit/auth/user';

export function UserProfile() {
    const user = useUser();

    if (!user) {
        return <div>Please sign in</div>;
    }

    return (
        <div>
            <h1>Welcome, {user.name}</h1>
            <p>Email: {user.email}</p>
        </div>
    );
}
```

## Sign Out Button

Add a sign out button using the provided component:

```tsx showLineNumbers {3,10}
'use client';

import { SignOutButton } from '@kit/auth/ui/sign-out-button';
import { authConfig } from '~/config/auth.config';

export function Header() {
    return (
        <header>
            <nav>
                {/* Other nav items */}
                <SignOutButton redirectTo={authConfig.urls.signIn} />
            </nav>
        </header>
    );
}
```

`SignOutButtonProps`

<AutoTypeTable path="../../kit/www/features/auth/src/ui/sign-out-button.tsx" name="SignOutButtonProps" />

## Next Steps

In the next page, you will see how to display the authentication user settings.

| Page                                                                                        | Description                          |
| ------------------------------------------------------------------------------------------- | ------------------------------------ |
| [Session Management](/docs/web/features/authentication/user-settings#session-management)    | View and manage active user sessions |
| [MFA Security](/docs/web/features/authentication/user-settings#multi-factor-authentication) | Enable two-factor authentication     |
| [Account Deletion](/docs/web/features/authentication/user-settings#user-deletion)           | Delete a user account                |


# web: User Settings
URL: /docs/web/features/authentication/user-settings
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/authentication/user-settings.mdx

Display the authentication user settings UI.
        
***

title: User Settings
description: Display the authentication user settings UI.
---------------------------------------------------------

At this stage, you have a fully working authentication system. But we can enhance the user experience by offering users to manage the following settings:

* Authentication provider
* Session management
* Multi-factor authentication
* User deletion

## Authentication Provider

The `AuthProviderZone` component displays the current OAuth providers connected to the user account or shows a password update form if email/password authentication is used.

```tsx showLineNumbers {2,10,12}
'use client';

import { AuthProviderZone } from '@kit/auth/ui/auth-provider-zone';
import { authConfig } from '~/config/auth.config';

export function AuthenticationSettings() {
    return (
        <div className="space-y-6">
            <div>
                <h2 className="text-2xl font-bold">Authentication</h2>
                <p className="text-muted-foreground">
                    Manage your password or login provider
                </p>
            </div>

            <AuthProviderZone authConfig={authConfig} />
        </div>
    );
}
```

**Features:**

* Shows connected OAuth providers (Google, GitHub, etc.) with last sign-in dates
* Displays password update form for email/password users
* Responsive design that works on all screen sizes
* Proper loading states and error handling

## Session Management

<Callout>
  The sessions tracking is handled in the database via the `kit` schema set in the sql files.
</Callout>

The `SessionZoneComponent` allows users to view and manage their active sessions across all devices.

```tsx
'use client';

import { SessionZoneComponent } from '@kit/auth/ui/session-zone-component';
import { dashboardRoutes } from '~/config/routes';

export function SessionSettings() {
    return (
        <div className="space-y-6">
            <div>
                <h2 className="text-2xl font-bold">Session Management</h2>
                <p className="text-muted-foreground">
                    View and manage your active sessions
                </p>
            </div>

            <SessionZoneComponent
                redirectTo={dashboardRoutes.paths.auth.signIn}
            />
        </div>
    );
}
```

**Features:**

* Lists all active sessions with device information
* Shows IP addresses with geolocation data
* Identifies the current session
* Allows revoking individual sessions or all other sessions
* Mobile-responsive design with touch-friendly controls
* Real-time location fetching with caching

### Setup

You have to install the `api/user-sessions` routes to your application to use the `SessionZoneComponent` component.

Copy paste the following code in your `app/api/user-sessions/[[...path]]/route.ts` file:

```tsx title="app/api/user-sessions/[[...path]]/route.ts" showLineNumbers
import { userSessionHandler } from '@kit/auth/user/sessions/routes';

export const GET = userSessionHandler;
export const POST = userSessionHandler;
export const DELETE = userSessionHandler;

```

## Multi-Factor Authentication

The `MultiFactorAuthList` component enables users to set up and manage multi-factor authentication (MFA) for their account.

```tsx
'use client';

import { MultiFactorAuthList } from '@kit/auth/ui/multi-factor-auth-list';

export function MFASettings() {
    return (
        <div className="space-y-6">
            <div>
                <h2 className="text-2xl font-bold">Multi-Factor Authentication</h2>
                <p className="text-muted-foreground">
                    Add an extra layer of security to your account
                </p>
            </div>

            <MultiFactorAuthList />
        </div>
    );
}
```

**Features:**

* Lists all configured MFA factors
* Allows setting up new MFA methods (TOTP, SMS, etc.)
* Shows factor status and creation dates
* Enables unenrolling from MFA factors
* Comprehensive setup dialogs for different factor types

## User Deletion

The `DangerZoneComponent` provides a clear interface for account deletion with proper confirmation dialogs.

```tsx
'use client';

import { DangerZoneComponent } from '@kit/auth/ui/danger-zone-component';

export function AccountDeletionSettings() {
    return (
        <div className="space-y-6">
            <div>
                <h2 className="text-2xl font-bold">Danger Zone</h2>
                <p className="text-muted-foreground">
                    Irreversible account actions
                </p>
            </div>

            <DangerZoneComponent />
        </div>
    );
}
```

**Features:**

* Clear warning about irreversible actions
* Confirmation dialogs to prevent accidental deletion
* Proper error handling and loading states
* Destructive styling to indicate danger

## Conclusion

Congratulations! You've successfully integrated the user settings UI into your application.

Your users are now able to :

* Create a new password
* View and manage their active sessions
* Add an extra layer of security to their account
* Delete their account

In the next page, you will learn how to protect you application against bots and spam using captcha.


# web: Billing
URL: /docs/web/features/billing
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/billing/index.mdx

Add subscription and payment capabilities to your application with multiple billing providers.
        
***

title: Billing
description: Add subscription and payment capabilities to your application with multiple billing providers.
package: "@kit/billing"
-----------------------

The `@kit/billing` package provides a unified interface for managing subscriptions, payments, and billing features in your application. It supports multiple billing providers while maintaining a consistent API.

## Core Features

* **Subscription Management**: Create and manage subscription plans
* **Payment Processing**: Handle payments securely
* **Customer Management**: Store and update customer billing information
* **Invoice Handling**: Generate and manage invoices
* **Usage Tracking**: Monitor subscription usage and limits
* **Multi-Provider Support**: Switch between providers without changing your code

## Available Providers

| Provider                                 | Description                                   |
| ---------------------------------------- | --------------------------------------------- |
| [Stripe](https://stripe.com)             | Industry-standard payment processing platform |
| [LemonSqueezy](https://lemonsqueezy.com) | Modern e-commerce and subscription platform   |

## Quick Setup with Dashboard App

The fastest way to get started is to use our pre-built dashboard application:

<Steps>
  <Step>Install the package</Step>

  ```bash showLineNumbers
  npm install '@kit/billing@workspace:*'
  ```

  <Step>Create a billing configuration file</Step>

  ```ts title="config/billing.config.ts" showLineNumbers
  import { parseBillingConfig } from '@kit/billing/config';

  export const billingConfig = parseBillingConfig({
      provider: 'stripe', // or 'lemon-squeezy'
      mode: 'test', // or 'live'
      currency: 'USD',
      numberAfterComma: 2,
      urls: {
          success: '/dashboard/billing',
          cancel: '/dashboard/billing',
      },
  });
  ```
</Steps>

## Features

* Pre-built billing pages
* Subscription management UI
* Customer portal
* Invoice history
* Usage tracking

## What's Next

| Page                                                      | Description                             |
| --------------------------------------------------------- | --------------------------------------- |
| [Integration](/docs/web/features/billing/integration)     | Step-by-step guide to integrate billing |
| [User Settings](/docs/web/features/billing/user-settings) | Add billing dashboard for users         |
| [Pricing](/docs/web/features/billing/pricing)             | Display pricing plans                   |


# web: Integration
URL: /docs/web/features/billing/integration
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/billing/integration.mdx

How to implement the billing feature in an existing application.
        
***

title: Integration
description: How to implement the billing feature in an existing application.
links:
'Stripe Docs': "[https://stripe.com/docs](https://stripe.com/docs)"
'LemonSqueezy Docs': "[https://docs.lemonsqueezy.com](https://docs.lemonsqueezy.com)"
-------------------------------------------------------------------------------------

This guide explains how to implement the billing feature in a new/existing application using the `@kit/billing` package.

## Installation

First, install the billing package:

```bash showLineNumbers
npm install '@kit/billing@workspace:*'
```

## Configuration File

Create the billing configuration in `config/billing.config.ts`:

```ts title="config/billing.config.ts" showLineNumbers
import { parseBillingConfig } from '@kit/billing/config';

/**
 * Your billing config allow you to define how you want to bill your users.
 *
 * To set your products, first create them on the billing provider's dashboard.
 * Then, copy the product ID and price ID from the billing provider's dashboard and paste them into the `products` array.
 */
export const billingConfig = parseBillingConfig({
    provider: 'stripe', // or 'lemon-squeezy'
    checkoutUI: 'embedded',
    attachedTable: 'user',
    products: [
        {
            id: 'prod_SnZo9gjf64pu8V', // ex of stripe product id
            features: ['Feature 1', 'Feature 2', 'Feature 3'],
        },
        {
            id: 'prod_SoMQHe5KvYYTXd', // ex of stripe product id
            popular: true,
            features: ['Feature 1', 'Feature 2', 'Feature 3', 'Feature 4', 'Feature 5'],
        },
        {
            id: 'prod_SoMReYpTHqroXz', // ex of stripe product id
            features: [
                '1000 credits',
                'Create as much folder that you want in your workspace',
                'Use the AI to generate content',
                '7 days free trial',
                'Full support at any time',
            ],
        },
    ],
});
```

<Callout>
  If you are looking for a Lemon Squeezy example, look the the config folder of the dashboard app.
</Callout>

`BillingConfig`

<AutoTypeTable path="../../kit/billing/types/src/create-billing-schema.ts" name="BillingConfig" />

## Environment Variables

Add the required environment variables based on your chosen provider:

### Stripe

```bash
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
```

### LemonSqueezy

```bash
LEMON_SQUEEZY_API_KEY=...
LEMON_SQUEEZY_WEBHOOK_SECRET=...
NEXT_PUBLIC_LEMON_SQUEEZY_STORE_ID=...
```

## Billing Pages

Create billing management pages using the provided components. The dashboard app uses these components in the settings section.

Check the [Billing Settings](/docs/web/features/billing/user-settings) and [Pricing](/docs/web/features/billing/pricing) pages for more details.

## Server Actions

The billing package provides server actions for common operations. Import and use them in your route handlers or server components:

```tsx
import {
    createCheckoutSession,
    createBillingPortalSessionUrl,
    updateBillingCustomer,
} from '@kit/billing/actions';
```

### Examples

#### Create Checkout Session

```ts
const session = await createCheckoutSession({
    config: billingConfig,
    priceId: 'price_1234567890',
    customerId: userId,
    successUrl: '/dashboard/billing',
    cancelUrl: '/pricing',
});
```

#### Create Customer Portal

```ts
const portalUrl = await createBillingPortalSessionUrl({
    config: billingConfig,
    customerId: userId,
    returnUrl: '/dashboard/billing',
});
```

<Callout variant="info">
  The `attachedTable: 'user'` in your config links billing records to the user table. The package automatically handles the relationship.
</Callout>

## What's Next

You've successfully integrated the core billing system. Now you can:

| Page                                                      | Description              |
| --------------------------------------------------------- | ------------------------ |
| [User Settings](/docs/web/features/billing/user-settings) | Add billing dashboard UI |
| [Pricing](/docs/web/features/billing/pricing)             | Display pricing plans    |


# web: Pricing Plans
URL: /docs/web/features/billing/pricing
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/billing/pricing.mdx

Display pricing plans that are synced with your billing provider configuration.
        
***

title: Pricing Plans
description: Display pricing plans that are synced with your billing provider configuration.
--------------------------------------------------------------------------------------------

<ComponentPreview name="pricing-plans-demo" description="Pricing plans showcase" align="start" />

The `PricingPlans` component allows you to display your subscription plans in a beautiful and responsive layout, automatically synced with your billing provider's configuration.

## Usage

```tsx showLineNumbers title="app/pricing/page.tsx" {7}
import { RecurringPricingImpl } from '@kit/billing/ui/pricing-plans';
import { billingConfig } from '~/config/billing.config';

export default async function PricingPage() {
    return (
        <div className="container py-8">
            <RecurringPricingImpl config={billingConfig} />
        </div>
    );
}
```

**Features:**

* Automatically fetches plans from your billing provider
* Responsive pricing table layout
* Highlights recommended plans
* Shows plan features and limits
* Handles currency formatting
* Supports monthly/yearly toggle
* Direct checkout integration

## Customization

The pricing plans component uses your billing configuration to determine:

* Currency display
* Price formatting
* Available plans
* Feature lists
* Checkout flow

You can customize these in your billing configuration file:

```ts showLineNumbers {3}
export const billingConfig = parseBillingConfig({
    provider: 'stripe', // or 'lemon-squeezy'
    checkoutUI: 'embedded',
    attachedTable: 'user',
    products: [
        // ...
    ],
});
```

<Callout>
  If you are looking for a Lemon Squeezy example, look the the config folder of the dashboard app.
</Callout>

## Server/Client Components

The component is split into server and client parts for optimal performance:

* `PricingPlans`: Server component that fetches pricing data
* `RecurringPricingImplClient`: Client component that handles interactivity

This architecture ensures fast page loads while maintaining a smooth user experience.


# web: User Settings
URL: /docs/web/features/billing/user-settings
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/billing/user-settings.mdx

Display the billing dashboard UI for users to manage their subscriptions and billing information.
        
***

title: User Settings
description: Display the billing dashboard UI for users to manage their subscriptions and billing information.
--------------------------------------------------------------------------------------------------------------

The `BillingPage` component provides a complete billing dashboard for users to manage their subscriptions, view invoices, and update billing information.

## Billing Dashboard

```tsx showLineNumbers
import { BillingPage } from '@kit/billing/ui/billing-page';
import { billingConfig } from '~/config/billing.config';

export default async function BillingSettings() {
    return <BillingPage config={billingConfig} />;
}
```

**Features:**

* Subscription management
* Customer information form
* Invoice history
* Test mode notice
* Responsive design

## Dashboard Sections

### 1. Subscriptions

The subscriptions section allows users to:

* View active subscriptions
* See subscription details and status
* Manage subscription plans
* Upgrade/downgrade subscriptions

### 2. Customer Information

The customer form enables users to:

* Update billing details
* Modify company information
* Change billing email
* Update address information

### 3. Invoices

The invoice table provides:

* List of all invoices
* Download options
* Payment status
* Invoice details

## Components

The billing dashboard is composed of several components that you can also use independently:

```tsx
import {
    BillingCustomerForm,
    BillingInvoiceTable,
    BillingSubscriptionSelector,
    SubscriptionPlanDetails,
} from '@kit/billing/ui';
```

### Example: Subscription Selector

```tsx
<BillingSubscriptionSelector config={billingConfig} products={products} />
```

### Example: Invoice Table

```tsx
<BillingInvoiceTable
    invoices={invoices}
    numberAfterComma={billingConfig.numberAfterComma ?? 2}
/>
```

### Example: Customer Form

```tsx
<BillingCustomerForm customer={customer} config={billingConfig} />
```

## Test Mode

When in test mode, the dashboard displays a notice to users indicating that they're working with test data. This helps prevent confusion between test and live environments.


# web: Fumadocs
URL: /docs/web/features/cms/fumadocs
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/cms/fumadocs.mdx

Implement your own documentation website with Fumadocs.
        
***

title: Fumadocs
description: Implement your own documentation website with Fumadocs.
links:
'Fumadocs': "[https://fumadocs.dev](https://fumadocs.dev)"
package: "@kit/fumadocs"
------------------------

We offer you the ability to implement your own documentation website with [Fumadocs](/docs/web/features/cms/fumadocs).

The `marketing` applicatin comes with a working implementation of Fumadocs.

## How to integrate in another application

* Follow the [Fumadocs documentation](https://fumadocs.dev/docs/getting-started/quick-start) to integrate it in your application.
* Check of the fumadocs is integrated in the application if you want to reuse it in another application.

The `@kit/fumadocs` package provides you :

* a `defaultMdxOptions` function that handle the `shiki`, `rehype-pretty-code` and `remark-mdx-files` plugins for you (from `@kit/fumadocs/mdx-options`).
* all the mdx components that you need to use with the `@kit/fumadocs/mdx-components` endpoint.
* an llm function to simplify llm processing (from `@kit/fumadocs/llm`).
* a bunch of components to use with the `@kit/fumadocs/ui` endpoint.

## Components

### DocsSidebar

The DocsSidebar component provides a collapsible navigation sidebar for documentation websites built with Fumadocs. It displays a hierarchical tree of pages and folders, allowing users to navigate through your documentation structure.

<ComponentPreview name="docs-sidebar-demo" description="A documentation sidebar with navigation tree" />

`DocsLayoutProps`

<AutoTypeTable path="../../kit/cms/fumadocs/src/components/docs-sidebar.tsx" name="DocsLayoutProps" />

### DocsBottomNavigation

The DocsBottomNavigation component displays previous and next navigation links at the bottom of documentation pages. It helps users navigate sequentially through your documentation content.

<ComponentPreview name="docs-bottom-navigation-demo" description="Previous and next page navigation" />

`DocsBottomNavigationProps`

<AutoTypeTable path="../../kit/cms/fumadocs/src/components/docs-bottom-navigation.tsx" name="DocsBottomNavigationProps" />


# web: CMS
URL: /docs/web/features/cms
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/cms/index.mdx

Integrate your content management system with your application.
        
***

title: CMS
description: Integrate your content management system with your application.
links:
'Notion': "[https://www.notion.com](https://www.notion.com)"
'Fumadocs': "[https://fumadocs.dev/](https://fumadocs.dev/)"
------------------------------------------------------------

We offer two CMS integrations options:

| CMS                                         | Description                                                                   |
| ------------------------------------------- | ----------------------------------------------------------------------------- |
| [Notion](/docs/web/features/cms/notion)     | A powerful tool for creating and managing your content.                       |
| [Fumadocs](/docs/web/features/cms/fumadocs) | A flexible, performant documentation framework for developers based on react. |

## Which option should I choose?

### Notion

Notion is very easy to use and and to implement. It offers a lot of powerful features with AI assistance.

Pros:

* AI assistance
* Hosting for your content
* Hosting for your images
* Automatic synchronization with your application

<Callout variant="destructive">
  The main drawback is that the Notion API has a [rate limit](https://developers.notion.com/reference/request-limits), you may hit the limit for hight traffic sites. You may need to notion paid plan to avoid this.
</Callout>

If the rate limit is a problem for you, you can use Fumadocs instead.

### Fumadocs

Fumadocs is sold as a documentation framework, but it can be easily used as a CMS for handling a blog or any other content without any additional configuration.

Pros:

* No server http requests on your website
* Edit your mdx files straight in your codebase
* Fumadocs is open source and free to use
* [Generous documentation](https://fumadocs.dev/docs/ui) with a large community
* Provide more integration flexibility (we do not depend on external client API)

<Callout variant="info">
  This approach to not provide the same easy to edit experience as Notion.
</Callout>

| Notion                                                            | Fumadocs                                                                                                                                              |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Open the notion app<br /> - Edit your pages<br /> - It's done ! | - Open your code editor<br /> - Edit your mdx files<br /> - Commit & push your changes to your repository<br /> - Deploy your changes to your website |

<div className="grid gap-4 sm:grid-cols-2 sm:gap-6 mt-8">
  <LinkedCard href="/docs/web/features/cms/fumadocs">
    <svg viewBox="0 0 180 180" role="img" xmlns="http://www.w3.org/2000/svg" className="h-10 w-10" fill="currentColor">
      <circle cx="90" cy="90" r="89" fill="url(#fumadocs-iconGradient)" stroke="white" strokeWidth="1" />

      <defs>
        <linearGradient id="fumadocs-iconGradient" gradientTransform="rotate(45)">
          <stop offset="45%" stopColor="black" />

          <stop offset="100%" stopColor="white" />
        </linearGradient>
      </defs>
    </svg>

    <p className="mt-2 font-medium">Fumadocs</p>
  </LinkedCard>

  <LinkedCard href="/docs/web/features/cms/notion">
    <svg role="img" stroke="currentColor" xmlns="http://www.w3.org/2000/svg" className="h-10 w-10" fill="none" strokeWidth="0" viewBox="0 0 15 15">
      <path d="M3.25781 3.11684C3.67771 3.45796 3.83523 3.43193 4.62369 3.37933L12.0571 2.93299C12.2147 2.93299 12.0836 2.77571 12.0311 2.74957L10.7965 1.85711C10.56 1.67347 10.2448 1.46315 9.64083 1.51576L2.44308 2.04074C2.18059 2.06677 2.12815 2.19801 2.2327 2.30322L3.25781 3.11684ZM3.7041 4.84917V12.6704C3.7041 13.0907 3.91415 13.248 4.38693 13.222L12.5562 12.7493C13.0292 12.7233 13.0819 12.4341 13.0819 12.0927V4.32397C13.0819 3.98306 12.9508 3.79921 12.6612 3.82545L4.12422 4.32397C3.80918 4.35044 3.7041 4.50803 3.7041 4.84917ZM11.7688 5.26872C11.8212 5.50518 11.7688 5.74142 11.5319 5.76799L11.1383 5.84641V11.6205C10.7965 11.8042 10.4814 11.9092 10.2188 11.9092C9.79835 11.9092 9.69305 11.7779 9.37812 11.3844L6.80345 7.34249V11.2532L7.61816 11.437C7.61816 11.437 7.61816 11.9092 6.96086 11.9092L5.14879 12.0143C5.09615 11.9092 5.14879 11.647 5.33259 11.5944L5.80546 11.4634V6.29276L5.1489 6.24015C5.09625 6.00369 5.22739 5.66278 5.5954 5.63631L7.53935 5.50528L10.2188 9.5998V5.97765L9.53564 5.89924C9.4832 5.61018 9.69305 5.40028 9.95576 5.37425L11.7688 5.26872ZM1.83874 1.33212L9.32557 0.780787C10.245 0.701932 10.4815 0.754753 11.0594 1.17452L13.4492 2.85424C13.8436 3.14309 13.975 3.22173 13.975 3.53661V12.7493C13.975 13.3266 13.7647 13.6681 13.0293 13.7203L4.33492 14.2454C3.78291 14.2717 3.52019 14.193 3.23111 13.8253L1.47116 11.5419C1.1558 11.1216 1.02466 10.8071 1.02466 10.4392V2.25041C1.02466 1.77825 1.23504 1.38441 1.83874 1.33212Z" fill="currentColor" />
    </svg>

    <p className="mt-2 font-medium">Notion</p>
  </LinkedCard>
</div>


# web: Emails
URL: /docs/web/features/emails
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/emails/index.mdx

All you need to know to setup your SMTP server.
        
***

title: Emails
description: All you need to know to setup your SMTP server.
------------------------------------------------------------

To be able to send emails to your users, you will need an **SMTP server**. In this page, we will see how to setup yours.

<Callout>
  This feature is implemented with the `@kit/emailer` package.
</Callout>

## Setup

<Callout variant="info" icon="Info" title="To know">
  We assume that you will use the same SMTP server for all your applications.

  *For that reason, we do not use an email config object approach.*
</Callout>

You need to have a domain name to set your SMTP server.

<Steps>
  <Step>The first thing to to is choose which SMTP provider you will use.</Step>

  Click on one of the available providers to see how to setup the associated env variable :

  * [Nodemailer](/docs/web/features/emails/providers#nodemailer)
  * [Postmark](/docs/web/features/emails/providers#postmark)
  * [Resend](/docs/web/features/emails/providers#resend)
  * [SendGrid](/docs/web/features/emails/providers#sendgrid)

  <Step>Set the following environment variables :</Step>

  ```dotenv showLineNumbers noCollapse
  EMAIL_FROM="Your Organization Name <sender-address@your-domain.com>"
  SUPPORT_EMAIL="support@your-domain.com"
  ```

  <Step>Now go to : `@kit/emailer/src/index.ts` and uncomment the provider you want to use only.</Step>

  ```typescript
  export { default as EmailProvider } from './nodemailer';
  // export { default as EmailProvider } from './postmark';
  // export { default as EmailProvider } from './resend';
  // export { default as EmailProvider } from './sendgrid';
  ```
</Steps>

## Supabase

**When you deploy your project, you must provide your SMTP server details to Supabase.**

<Callout variant="info">
  **No needs to do it in local environment** (not supported yet). Supabase provide an "in bucket" port for showing what would be sent in email. Go to [http://localhost:54324/](http://localhost:54324/) to see the sent emails.
</Callout>

The complete process is described in this [Supabase documentation page](https://supabase.com/docs/guides/auth/auth-smtp).

But all you need to do is :

<Steps>
  <Step>Go to your [Supabase dashboard](https://supabase.com/dashboard).</Step>

  <Step>Go to : `Your project` > `Authentication` > `Emails`.</Step>

  <Step>Click on the `SMTP Settings` tab.</Step>

  <Step>Enable `Enable Custom SMTP` and fill the form with your SMTP server details.</Step>
</Steps>

## Usage

<Steps>
  <Step>Make sure that the `@kit/emailer` and `@kit/email-templates` packages are installed.</Step>

  ```bash
  npm install '@kit/emailer@workspace:*' '@kit/email-templates@workspace:*'
  ```

  <Step>Now you can use the `EmailProvider` class to send emails.</Step>

  ```typescript
  // import your template
  import { renderUserDeleteEmail } from '@kit/email-templates';
  import { EmailProvider } from '@kit/emailer';

  async function sendEmail() {
    const { html, subject } = await renderUserDeleteEmail({
      var1: 'value1',
      var2: 'value2',
      // ...
    });
    
    return EmailProvider.sendEmail({
        to: userEmail, // the email address of the recipient
        from: fromEmail, // the email address of the sender
        subject,
        html,
    });
  }
  ```
</Steps>

## Environment variables

```dotenv showLineNumbers noCollapse
# ============================================
# 📧 EMAIL PROVIDERS
# ============================================

# Email sender configuration
EMAIL_FROM="Your Organization Name <sender@your-domain.com>"
SUPPORT_EMAIL="support@your-domain.com"

# Alternative providers
EMAIL_NODEMAILER_URL=""
EMAIL_POSTMARK_SERVER_TOKEN=""    # Get from: Postmark > API Tokens
EMAIL_RESEND_API_KEY=""           # Get from: Resend > API Keys
EMAIL_SENDGRID_API_KEY=""         # Get from: SendGrid > Settings > API Keys
```


# web: Emails Providers
URL: /docs/web/features/emails/providers
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/emails/providers.mdx

Setup the SMTP provider you want to use.
        
***

title: Emails Providers
description: Setup the SMTP provider you want to use.
links:
'Nodemailer': "[https://nodemailer.com/](https://nodemailer.com/)"
'Postmark': "[https://postmarkapp.com/](https://postmarkapp.com/)"
'Resend': "[https://resend.com/](https://resend.com/)"
'SendGrid': "[https://sendgrid.com/](https://sendgrid.com/)"
------------------------------------------------------------

In this page, we will see how to setup the environment variables that you need for the chosen SMTP provider.

Here are the available providers :

* [Nodemailer](#nodemailer)
* [Postmark](#postmark)
* [Resend](#resend)
* [SendGrid](#sendgrid)

## Nodemailer

Nodemailer is a popular Node.js library for sending emails via SMTP. Great for self-hosted or custom SMTP setups.

Required environment variables : `EMAIL_NODEMAILER_URL`

<Callout>
  This solution is the most developer-friendly because it is an [open-source project](https://github.com/nodemailer/nodemailer).

  *Other solutions are quite expensive but quicker to setup with many built-in features.*
</Callout>

It is our favorite solution for development environments.

### Gmail SMTP example

<Callout variant="info">
  This solution is **free** and **quick** to setup. The perfect choice when you start a new project on your own.
</Callout>

You will need to have a gmail address.

<Steps>
  <Step>As said [in](https://support.google.com/accounts/answer/185833) you will need to [create a google application password](https://myaccount.google.com/apppasswords)</Step>

  <Callout>
    To create a google application password, you must enable the 2-Step Verification.
  </Callout>

  <Step>Your `EMAIL_NODEMAILER_URL` env variable should look like this :</Step>

  ```dotenv showLineNumbers noCollapse
  # SMTP Provider (Gmail example)
  EMAIL_NODEMAILER_URL=smtp://[YOUR_EMAIL_ADDRESS@gmail.com]:[YOUR_GOOGLE_APPLICATION_PASSWORD]@smtp.gmail.com:465
  ```

  Where :

  * `[YOUR_EMAIL_ADDRESS@gmail.com]` is your email address.
  * `[YOUR_GOOGLE_APPLICATION_PASSWORD]` is your google application password.

  You also need to set the `EMAIL_FROM` and `SUPPORT_EMAIL` env variables like this :

  ```dotenv showLineNumbers noCollapse
  EMAIL_FROM="Your Organization Name <your-domain.smtp@gmail.com>"
  SUPPORT_EMAIL="your-domain.smtp@gmail.com"
  ```
</Steps>

## Postmark

Postmark is a reliable transactional email service. Offers fast delivery and excellent deliverability for production use.

Required environment variables : `EMAIL_POSTMARK_SERVER_TOKEN`

To get your Postmark server token, sign in to your Postmark account, navigate to the [API Tokens](https://account.postmarkapp.com/api_tokens) page, and create a new server token.

## Resend

Resend is a developer-friendly email API that uses AWS SES under the hood, simplifying email setup while maintaining reliability.

Required environment variables : `EMAIL_RESEND_API_KEY`

To get your Resend API key, sign in to your Resend account, go to the [API Keys](https://resend.com/api-keys) section, and create a new API key.

## SendGrid

SendGrid is a scalable cloud-based email service with advanced features for both transactional and marketing emails.

Required environment variables : `EMAIL_SENDGRID_API_KEY`

To get your SendGrid API key, sign in to your SendGrid account, navigate to [Settings > API Keys](https://app.sendgrid.com/settings/api_keys), and create a new API key.


# web: Email Templates
URL: /docs/web/features/emails/templates
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/emails/templates.mdx

Premade templates for emails to make your brand more professional.
        
***

title: Email Templates
description: Premade templates for emails to make your brand more professional.
links:
'React email': "[https://react.email/](https://react.email/)"
-------------------------------------------------------------

<Callout>
  This feature is implemented with the `@kit/email-templates` package.
</Callout>

## Usage

<Steps>
  <Step>Make sure the package is installed.</Step>

  ```bash
  npm install '@kit/email-templates@workspace:*'
  ```

  <Step>Render the template that you want.</Step>

  ```typescript
  import { renderWelcomeEmail } from '@kit/email-templates';

  const { html, subject } = await renderWelcomeEmail({
      appConfig: appConfig,
      name: 'John Doe',
  });
  ```

  <Step>Send the email.</Step>

  Check the [email index documentation](/docs/web/features/emails) to see how to send the email.
</Steps>

## Supabase templates

As said in the [supabase documentation](https://supabase.com/docs/guides/auth/auth-email-templates), supabase use the following templates for authentication.

| Template             | Description                                           |
| -------------------- | ----------------------------------------------------- |
| Confirm signup       | Email sent to the user to confirm their signup.       |
| Invite user          | Email sent to the user to invite them to the project. |
| Magic Link           | Email sent to the user to sign in to the project.     |
| Change Email Address | Email sent to the user to confirm their email change. |
| Reset Password       | Email sent to the user to reset their password.       |

## Email structure

All email templates follow a common structure:

* **Header component** at the top of each email, containing the application logo and branding
* **Footer component** at the bottom of each email, containing legal information and unsubscribe links

This consistent structure ensures a professional appearance across all your email communications.

<Callout>
  In the templates, we use the `AppConfig` object to get the application logo and branding.
</Callout>

## Tailwind configuration

Located in the `kit/email/email-templates/tailwind.email.config.ts` file.

`TailwindConfig`

<AutoTypeTable path="../../kit/email/email-templates/tailwind.email.config.ts" name="TailwindConfig" />

### Font configuration

Located in the `kit/email/email-templates/tailwind.email.config.ts` file.

The config font object allows you to load fonts to use in your emails.

`FontConfig`

<AutoTypeTable path="../../kit/email/email-templates/tailwind.email.config.ts" name="FontConfig" />

## Email templates

### Welcome Email

Used to welcome new users to your application. Use `renderWelcomeEmail` to render this template.

<EmailTemplatePreview name="welcome-email" className="h-[680px]" />

`WelcomeEmailProps`

<AutoTypeTable path="../../kit/email/email-templates/src/templates/welcome-email.tsx" name="WelcomeEmailProps" />

### Confirm Email Address

Used to verify a user's email address during registration. Use `renderConfirmEmailAddressEmail` to render this template.

<EmailTemplatePreview name="confirm-email-address-email" className="h-[660px]" />

`ConfirmEmailAddressEmailProps`

<AutoTypeTable path="../../kit/email/email-templates/src/templates/confirm-email-address-email.tsx" name="ConfirmEmailAddressEmailProps" />

### Invite User

Used to invite users to join an organization. Use `renderInviteUserEmail` to render this template.

<EmailTemplatePreview name="invite-user" className="h-[550px]" />

`InviteUserEmailProps`

<AutoTypeTable path="../../kit/email/email-templates/src/templates/invite-user-email.tsx" name="InviteUserEmailProps" />

### Password Reset Email

Used to send password reset links to users. Use `renderResetPasswordEmail` to render this template.

<EmailTemplatePreview name="password-reset-email" className="h-[570px]" />

`ResetPasswordEmailProps`

<AutoTypeTable path="../../kit/email/email-templates/src/templates/reset-password-email.tsx" name="ResetPasswordEmailProps" />

### Confirm Changed Email Address

Used to confirm when a user wants to change their email address. Use `renderConfirmChangeEmailAddressEmail` to render this template.

<EmailTemplatePreview name="confirm-changed-email-address" className="h-[620px]" />

`ConfirmChangeEmailAddressEmailProps`

<AutoTypeTable path="../../kit/email/email-templates/src/templates/confirm-change-email-address-email.tsx" name="ConfirmChangeEmailAddressEmailProps" />

### Revoked Invitation Email

Used to notify users when their invitation to an organization has been revoked. Use `renderRevokedInvitationEmail` to render this template.

<EmailTemplatePreview name="revoked-invite-user" className="h-[490px]" />

`RevokedInvitationEmailProps`

<AutoTypeTable path="../../kit/email/email-templates/src/templates/revoked-invitation-email.tsx" name="RevokedInvitationEmailProps" />

### User Delete Email

Used to confirm user account deletion requests. Use `renderUserDeleteEmail` to render this template.

<EmailTemplatePreview name="user-delete-email" className="h-[580px]" />

`UserDeleteEmailProps`

<AutoTypeTable path="../../kit/email/email-templates/src/templates/user-delete-email.tsx" name="UserDeleteEmailProps" />


# web: Keybindings
URL: /docs/web/features/keybindings
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/keybindings/index.mdx

A type-safe keybindings system for React applications.
        
***

title: Keybindings
description: A type-safe keybindings system for React applications.
package: '@kit/keybindings'
---------------------------

<ComponentPreview name="keybindings-demo" description="A keybindings component" align="center" />

<Callout>
  For cross OS compatibility, `⌘` and `ctrl` are equivalent.
</Callout>

## Installation

```bash showLineNumbers
npm install '@kit/keybindings@workspace:*'
```

## Quick Start

<Steps>
  <Step>Define your keybindings config.</Step>

  ```ts title="config/keybindings.config.ts" showLineNumbers
  import { parseKeybindingsConfig } from '@kit/keybindings/config';
  import { dashboardRoutes } from '@kit/shared/config';

  export const keybindingsModel = parseKeybindingsConfig({
      // Navigation
      'navigation.home': {
          name: 'Go to Home',
          description: 'Navigate to home page',
          defaultShortcut: 'ctrl+h',
          context: 'global',
          url: dashboardRoutes.paths.dashboard.slug.index,
      },
      'navigation.settings': {
          name: 'Go to Settings',
          description: 'Navigate to settings page',
          defaultShortcut: 'ctrl+j',
          context: 'global',
          url: dashboardRoutes.paths.dashboard.slug.settings.index,
      },
      // UI
      'ui.toggleTheme': {
          name: 'Toggle Theme',
          description: 'Switch between light and dark theme',
          defaultShortcut: 'ctrl+shift+l',
          context: 'global',
      },
      'ui.toggleSidebar': {
          name: 'Toggle Sidebar',
          description: 'Show/hide sidebar',
          defaultShortcut: 'ctrl+b',
          context: 'global',
      },
  });

  ```

  <Callout variant="destructive">
    Avoid system shortcuts (Cmd+Q, Cmd+W, etc.)
  </Callout>

  <Step>Wrap your app with the `KeybindingsProvider`.</Step>

  ```tsx title="components/providers/app-provider.tsx" showLineNumbers {12,13,15}
  'use client';

  import { LocalStorageKeybindingsStorage } from '@kit/keybindings/storage/local-storage';
  import { KeybindingsProvider } from '@kit/keybindings/ui';
  import { keybindingsModel } from '~/config/keybindings.config';
  import { KeybindingHandlers } from '../keybinding-handlers';

  const keybindingsStorage = new LocalStorageKeybindingsStorage();

  export function AppProvider({ children }: { children: React.ReactNode }) {
    return (
      <KeybindingsProvider model={keybindingsModel} storage={keybindingsStorage}>
          <KeybindingHandlers />
          {children}
      </KeybindingsProvider>
    );
  }
  ```

  <Step>Implement the keybinding actions.</Step>

  Now you have the implement the keybinding actions.

  <Callout>
    Do not implement the actions beginning with `navigation.`. **Those actions serve as navigation helpers**.

    When the `url` property is set, they are automatically implemented in the `KeybindingsProvider`.
  </Callout>

  ```tsx title="components/keybinding-handlers.tsx" showLineNumbers {9,14}
  'use client';

  import { useKeybinding } from '@kit/keybindings/ui';
  import { useTheme } from 'next-themes';

  export function KeybindingsHandlers() {
      const { theme, setTheme } = useTheme();

      useKeybinding('ui.toggleTheme', () => {
          const newTheme = theme === 'dark' ? 'light' : 'dark';
          setTheme(newTheme);
      });

      useKeybinding('ui.toggleSidebar', () => {
          const sidebarToggle = document.querySelector(
              '[data-sidebar-toggle], [data-sidebar="trigger"], .sidebar-toggle'
          ) as HTMLButtonElement;
          if (sidebarToggle) {
              sidebarToggle.click();
          }
      });

      return null;
  }

  ```

  **Congratulations! Now you can start using your keybindings.**
</Steps>

## Display Keybindings

Use the `KeybindingDisplay` component to display the keybindings.

```tsx title="app/somewhere.tsx" showLineNumbers {13,18}
'use client';

import { KeybindingDisplay, KeybindingsProvider } from '@kit/keybindings/ui';
import { Muted } from '@kit/ui/text';
import { keybindingsModel } from '~/config/keybindings.config';

export default function YourApp() {
    return (
        <KeybindingsProvider model={keybindingsModel}>
            <div className="flex flex-col gap-2 items-center">
                <Muted>
                    Press <span className="capitalize text-black dark:text-white">
                        <KeybindingDisplay actionSlug="ui.toggleTheme" />
                    </span> to toggle theme
                </Muted>
                <Muted>
                    Press <span className="capitalize text-black dark:text-white">
                        <KeybindingDisplay actionSlug="ui.alert" />
                    </span> to alert
                </Muted>
            </div>
        </KeybindingsProvider>
    );
}

```

<Callout icon="Sparkles" title="Tip">
  Use it in your navigation/menu components to display the keybindings.
</Callout>

## User customizations

Use the `KeybindingsTable` component to let users customize shortcuts.

```tsx title="app/somewhere.tsx" showLineNumbers {10}
'use client';

import { keybindingsModel } from '~/config/keybindings.config';
import { KeybindingsProvider, KeybindingsTable } from '@kit/keybindings/ui';

export default function YourApp() {
    return (
        <KeybindingsProvider model={keybindingsModel}>
            {/* ... */}
            <KeybindingsTable />
            {/* ... */}
        </KeybindingsProvider>
    );
}

```

## Typescript support

`@kit/keybindings` provides a type inference for the keybindings actions.

<Image src="/docs/web/keybindings-typescript-autocompletion.png" alt="Keybindings typescript autocompletion" width="600" height="460" size="md" />

Follow this steps to enable the typescript support in a `@app/your-app` application :

<Steps>
  <Step>Create a `@types` folder at the root of the package and create a `keybindings.d.ts` file inside it.</Step>

  <Files>
    <Folder name="@types" defaultOpen>
      <File name="keybindings.d.ts" />
    </Folder>

    <File name="package.json" />

    <File name="tsconfig.json" />
  </Files>

  <Step>Copy paste the following code into the `@types/keybindings.d.ts` file.</Step>

  ```ts title="types/keybindings.d.ts" showLineNumbers
  import '@kit/keybindings/ui';

  import {
      KeybindingDisplay as KeybindingDisplayBase,
      useKeybinding as useKeybindingBase,
      useShortcut as useShortcutBase,
  } from '@kit/keybindings/ui/without-context';
  import { keybindingsModel } from '../config/keybindings.config';

  declare module '@kit/keybindings/ui' {
      declare const useKeybinding = (...params: Parameters<typeof useKeybindingBase<typeof keybindingsModel>>) =>
          useKeybindingBase<typeof keybindingsModel>(...params);

      declare const useShortcut = (...params: Parameters<typeof useShortcutBase<typeof keybindingsModel>>) =>
          useShortcutBase<typeof keybindingsModel>(...params);

      declare const KeybindingDisplay = (
          props: React.ComponentProps<typeof KeybindingDisplayBase<typeof keybindingsModel>>
      ) => KeybindingDisplayBase<typeof keybindingsModel>(props);
  }

  ```

  <Step>Add the following `typeRoots` attribute to the `tsconfig.json` file.</Step>

  ```json title="tsconfig.json" showLineNumbers {4}
  {
      "extends": "@kit/tsconfig/base.json",
      "compilerOptions": {
          "typeRoots": ["./node_modules/@types", "./@types"],
          // ...
      },
  }

  ```
</Steps>

## API Reference

### Components

* `KeybindingDisplay` - Component to display shortcuts

`KeybindingDisplayProps`

<AutoTypeTable path="../../kit/keybindings/src/ui/keybinding-display.tsx" name="KeybindingDisplayProps" />

* `KeybindingsProvider` - Context provider for keybindings

`KeybindingsProviderProps`

<AutoTypeTable path="../../kit/keybindings/src/ui/context.tsx" name="KeybindingsProviderProps" />

* `KeybindingsTable` - Settings table for editing keybindings

`KeybindingsTableProps`

<AutoTypeTable path="../../kit/keybindings/src/ui/keybindings-table.tsx" name="KeybindingsTableProps" />

### Hooks

* `useKeybinding(actionId, callback, options?)` - Register shortcut handler
* `useKeybindings()` - Access keybindings context
* `useShortcut(actionId)` - Get current shortcut for action


# web: Keybindings Storage
URL: /docs/web/features/keybindings/storage
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/keybindings/storage.mdx

Guide users through keybindings storage options.
        
***

title: Keybindings Storage
description: Guide users through keybindings storage options.
-------------------------------------------------------------

## Local Storage (default)

By default, keybindings are stored in local storage. No need to configure anything.

<Callout variant="info">
  Local storage is not persistent across devices and is reset when the user clears the browser data.
</Callout>

## Database Storage

If you want to store keybindings in the database, you can use the `KeybindingsStorageProvider` in combination with the [@kit/settings package](/docs/web/features/settings).

### Setup

<Steps>
  <Step>Copy paste the following code under `/api/keybindings/[[...path]]/route.ts`.</Step>

  ```tsx title="app/api/keybindings/[[...path]]/route.ts" showLineNumbers
  import { createKeybindingsHandler } from '@kit/keybindings/storage/settings-storage/routes';
  import { settingsModel } from '~/config/settings.config';

  export const GET = createKeybindingsHandler(settingsModel);
  export const POST = createKeybindingsHandler(settingsModel);
  export const DELETE = createKeybindingsHandler(settingsModel);

  ```

  This will set up the API routes for the keybindings storage.

  <Step>Create a new `keybindingsStorage` instance and pass it to the `KeybindingsProvider`.</Step>

  ```tsx showLineNumbers {5}
  import { KeybindingsProvider } from '@kit/keybindings/ui';
  import { keybindingsModel } from '~/config/keybindings.config';
  import { DatabaseKeybindingsStorage } from '@kit/keybindings/storage/settings-storage/handler';

  const keybindingsStorage = new DatabaseKeybindingsStorage();

  export function DashboardProvider({ children }: { children: React.ReactNode }) {
      return (
          <KeybindingsProvider model={keybindingsModel} storage={keybindingsStorage}>
              {children}
          </KeybindingsProvider>
      );
  }

  ```

  <Step>Add the `KEYBINDINGS_SETTING_NAME` to the `settingsModel`.</Step>

  ```tsx title="config/settings.config.tsx" showLineNumbers {11,14}
  import {
      KEYBINDINGS_SETTING_NAME,
      KEYBINDINGS_SETTINGS_SCHEMA,
  } from '@kit/keybindings/storage/settings-storage/settings';
  import { settingsModel } from '~/config/settings.config';

  export const settingsModel = createSettingModel(
      'your-settings-id',
      getDBClient,
      {
          // Your existing settings...
          [KEYBINDINGS_SETTING_NAME]: {
              schema: KEYBINDINGS_SETTINGS_SCHEMA,
              storage: 'user_settings', // we are using the user_settings storage provider
          },
          // Your existing settings...
      },
      {}, // ui config
  );
  ```
</Steps>

Now keybindings will be stored in the user\_settings table.

## API Reference

`KeybindingsStorage`

<AutoTypeTable path="../../kit/keybindings/src/types.ts" name="KeybindingsStorage" />


# 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/index.mdx

Add an onboarding process after registration to collect more data on your new users and to perform specific actions.
        
***

title: Onboarding
description: Add an onboarding process after registration to collect more data on your new users and to perform specific actions.
---------------------------------------------------------------------------------------------------------------------------------

In this page, we will see :

* how to setup your database for authentication

<Callout>
  This feature is implemented in the `@kit/onboarding` package.
</Callout>

<Callout variant="info">
  The onboarding process is built on the top of the [Stepper](/docs/ui/components/stepper) component.
</Callout>

In the kit, only the `apps/dashboard` application implement the onboarding feature.

## Redirection

After registration, the user is redirected to the `/dashboard` endpoint. You are using the `/dashboard/layout.tsx` file to redirect the user to the onboarding page if the user is not onboarded.

```tsx title="your-app/app/dashboard/layout.tsx" showLineNumbers {14}
// imports ...

export default async function OrganizationsLayout(
    props: React.PropsWithChildren
): Promise<React.JSX.Element> {
    const db = await getDBClient();
    const user = await db.user.get();

    if (!user) {
        return redirect(dashboardRoutes.paths.auth.signIn);
    }
    if (!user.completedOnboarding) {
        // Redirect to the onboarding page
        return redirect(dashboardRoutes.paths.onboarding.index);
    }

    return <UserProvider user={user}>{props.children}</UserProvider>;
}
```

<Callout>
  We are using an `completedOnboarding` column in the `user` table to check if the user has completed the onboarding process.
</Callout>

This simple procedure allows us to make sure that all users are onboarded before accessing the dashboard.

## Onboarding page

### Installation

```bash
npm install '@kit/onboarding@workspace:*'
```

### Usage

We gonna put the onboarding page in a `your-app/app/onboarding/` folder.

```tsx title="your-app/app/onboarding/page.tsx" showLineNumbers {17-21}
// imports ...
import { UserOnboarding } from '@kit/onboarding';
import { redirect } from 'next/navigation';

export default async function OnboardingFullPage(): Promise<React.JSX.Element> {
    const db = await getDBClient();
    const user = await db.user.require();

    if (user.completedOnboarding) {
        // Redirect to the dashboard, if the user has already completed the onboarding process
        return redirect(dashboardRoutes.paths.dashboard.index);
    }

    return (
        <div className="relative min-h-screen">
            {/* Logout button, logo ... */}
            <UserOnboarding
                activeSteps={['profile', 'theme']}
                metadata={{ user: user }}
                redirectUrl={dashboardRoutes.paths.dashboard.index}
            />
        </div>
    );
}
```

We are using the `UserOnboarding` component to display the onboarding process.

Details of the props `UserOnboardingProps` :

<AutoTypeTable path="../../kit/www/features/onboarding/src/components/user-onboarding.tsx" name="UserOnboardingProps" />

## Add new steps

Adding new onboarding steps involves several components working together. Here's how to extend the onboarding flow:

<Steps>
  <Step>
    ### 1. Define the Step Schema
  </Step>

  First, create a Zod schema for your new step in `kit/www/features/onboarding/src/onboarding.schema.ts`:

  ```ts title="kit/www/features/onboarding/src/onboarding.schema.ts" showLineNumbers {2-5,15}
  // Add your new step schema
  export const yourNewStepSchema = z.object({
      field1: z.string().min(1, 'Field 1 is required'),
      field2: z.number().min(0).max(100),
  });

  // Update the UserOnboardingStep type to include your new step
  export type UserOnboardingStep = 'profile' | 'theme' | 'yourNewStep';

  // Update the main schema to include your step data
  export const completeUserOnboardingSchema = z.object({
      activeSteps: z.array(z.enum(['profile', 'theme', 'yourNewStep'])),
      profileStep: profileOnboardingSchema.optional(),
      themeStep: themeOnboardingSchema.optional(),
      yourNewStep: yourNewStepSchema.optional(), // Add your step here
  });
  ```

  <Step>
    ### 2. Create the Step Component
  </Step>

  Create a new component for your step in `kit/www/features/onboarding/src/components/`:

  ```tsx title="kit/www/features/onboarding/src/components/onboarding-your-new-step.tsx" showLineNumbers
  'use client';

  import { cn } from '@kit/shared';
  import { FormControl, FormField, FormItem, FormLabel, FormMessage } from '@kit/ui/form';
  import { Input } from '@kit/ui/input';
  import { StepperNext } from '@kit/ui/stepper';
  import React from 'react';
  import { useFormContext } from 'react-hook-form';
  import { type CompleteUserOnboardingSchema } from '../onboarding.schema';
  import { OnboardingUserStepProps } from './user-onboarding';

  export type OnboardingYourNewStepProps = Pick<React.HtmlHTMLAttributes<HTMLDivElement>, 'className'> & OnboardingUserStepProps;

  export function OnboardingYourNewStep({
      className,
      loading,
  }: OnboardingYourNewStepProps): React.JSX.Element {
      const methods = useFormContext<CompleteUserOnboardingSchema>();

      return (
          <div className={cn('flex flex-col gap-4', className)}>
              <h1 className="text-xl leading-none font-semibold tracking-tight lg:text-2xl">
                  Your New Step Title
              </h1>
              <p className="text-muted-foreground text-sm lg:text-base">
                  Description of what this step does.
              </p>

              <div className="grid gap-x-8 gap-y-4">
                  <FormField
                      control={methods.control}
                      name="yourNewStep.field1"
                      render={({ field }) => (
                          <FormItem>
                              <FormLabel required>Field 1</FormLabel>
                              <FormControl>
                                  <Input
                                      type="text"
                                      required
                                      disabled={loading}
                                      {...field}
                                  />
                              </FormControl>
                              <FormMessage />
                          </FormItem>
                      )}
                  />

                  <FormField
                      control={methods.control}
                      name="yourNewStep.field2"
                      render={({ field }) => (
                          <FormItem>
                              <FormLabel required>Field 2</FormLabel>
                              <FormControl>
                                  <Input
                                      type="number"
                                      min="0"
                                      max="100"
                                      required
                                      disabled={loading}
                                      {...field}
                                      onChange={(e) => field.onChange(parseInt(e.target.value, 10))}
                                  />
                              </FormControl>
                              <FormMessage />
                          </FormItem>
                      )}
                  />
              </div>

              <div className="mt-12 flex justify-end">
                  <StepperNext loading={loading} />
              </div>
          </div>
      );
  }
  ```

  <Step>
    ### 3. Register the Step
  </Step>

  Update the `USER_ONBOARDING_STEP` configuration in `kit/www/features/onboarding/src/components/user-onboarding.tsx`:

  ```tsx title="kit/www/features/onboarding/src/components/user-onboarding.tsx" showLineNumbers {16-20}
  // Import your new component
  import { OnboardingYourNewStep } from './onboarding-your-new-step';

  export const USER_ONBOARDING_STEP: Record<UserOnboardingStep, OnboardingStepConfig> = {
      profile: {
          name: 'Profile',
          description: 'Set up your profile information',
          component: OnboardingProfileStep,
      },
      theme: {
          name: 'Theme',
          description: 'Choose your preferred theme',
          component: OnboardingThemeStep,
      },
      // Add your step to the configuration
      yourNewStep: {
          name: 'Your New Step',
          description: 'Description of your new step',
          component: OnboardingYourNewStep,
      },
  };
  ```

  <Step>
    ### 4. Update the Server Action
  </Step>

  Modify the server action in `kit/www/features/onboarding/src/onboarding.action.ts` to handle your new step data:

  ```tsx title="kit/www/features/onboarding/src/onboarding.action.ts" showLineNumbers {21-23}
  export const completeUserOnboarding = authActionClient
      .metadata({
          actionName: 'completeUserOnboarding',
      })
      .schema(
          z.object({
              values: completeUserOnboardingSchema,
              redirectUrl: z.string(),
          })
      )
      .action(async ({ ctx: { db }, parsedInput: { values, redirectUrl } }) => {
          try {
              const currentUser = await db.user.require();

              await db.rls.transaction(async (tx) => {
                  if (values.activeSteps.includes('profile') && values.profileStep) {
                      // Update profile data...
                  }

                  // Handle your new step data
                  if (values.activeSteps.includes('yourNewStep') && values.yourNewStep) {
                      // Process your new step data here...
                  }
              });

              // Handle theme step if needed...

              revalidatePath(redirectUrl);

          return {
              redirectUrl,
          };
      } catch (error) {
          console.error('Error completing onboarding:', error);
          return {
              serverError: 'Failed to complete onboarding',
          };
      }
  });
  ```

  <Step>
    ### 5. Update the Usage
  </Step>

  Finally, update your onboarding page to include the new step:

  ```tsx title="your-app/app/onboarding/page.tsx" showLineNumbers {2}
  <UserOnboarding
      activeSteps={['profile', 'theme', 'yourNewStep']}
      metadata={{ user: user }}
      redirectUrl={dashboardRoutes.paths.dashboard.index}
  />
  ```
</Steps>

## Key Points

* **Modular Design**: Each step is self-contained with its own component, schema, and processing logic
* **Type Safety**: Use TypeScript interfaces and Zod schemas to ensure data integrity
* **Form Integration**: Steps automatically integrate with the form system using `useFormContext`
* **Server Processing**: Handle step-specific logic in the server action within the transaction
* **Flexibility**: You can add, remove, or reorder steps by modifying the `activeSteps` array


# web: Organization Onboarding
URL: /docs/web/features/onboarding/organization
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/onboarding/organization.mdx

Guide users through organization setup, team creation, and member invitations after registration.
        
***

title: Organization Onboarding
description: Guide users through organization setup, team creation, and member invitations after registration.
--------------------------------------------------------------------------------------------------------------

<Callout>
  The organization onboarding feature extends the user onboarding with organization-specific steps. It's implemented in the `@kit/org-onboarding` package and handles the complete organization setup flow.
</Callout>

## Overview

Organization onboarding combines **user onboarding** (profile + theme) with **organization steps**:

* Organization creation (name, slug, logo)
* Team member invitations
* Pending invitation handling

## Available Steps

| Step                  | Description             | Component                     |
| --------------------- | ----------------------- | ----------------------------- |
| `profile`             | User profile setup      | `OnboardingProfileStep`       |
| `theme`               | Theme selection         | `OnboardingThemeStep`         |
| `organization`        | Organization creation   | `OrgOnboardingStep`           |
| `organization-invite` | Team member invitations | `OrgOnboardingInvitationStep` |
| `pending-invitations` | Handle pending invites  | `null` (auto-handled)         |

## Quick Setup

<Steps>
  <Step>Install the package</Step>

  ```bash
  npm install '@kit/org-onboarding@workspace:*'
  ```

  <Step>Create the onboarding page</Step>

  ```tsx title="your-app/app/onboarding/page.tsx" showLineNumbers {1,13,18-23}
  import { OrganizationOnboarding } from '@kit/org-onboarding';
  import { dashboardRoutes } from '@kit/shared/config';
  // ... other imports

  export default async function OnboardingFullPage(): Promise<React.JSX.Element> {
      const db = await getDBClient();
      const user = await db.user.require();

      // Check if user already has organization memberships
      const memberships = await db.organization.getUserMemberships();
      if (memberships.length > 0) {
          // redirect to a user only sub-onboarding page
          return redirect(dashboardRoutes.paths.onboarding.user);
      }

      return (
          <div className="relative min-h-screen bg-background">
              <OrganizationOnboarding
                  activeSteps={['profile', 'theme', 'organization', 'organization-invite']}
                  metadata={{ user: user }}
                  rootUrl={dashboardRoutes.url}
                  redirectUrl={dashboardRoutes.paths.dashboard.index}
              />
          </div>
      );
  }
  ```
</Steps>

## Key Features

### **Smart Redirection**

* Users with existing memberships → User onboarding
* New users → Full organization onboarding
* Pending invitations → Appropriate handling

### **Organization Creation**

* Name, slug, and logo setup
* Slug validation (alphanumeric + hyphens/underscores)
* Logo upload with cropping

### **Team Invitations**

* Invite up to 5 team members
* Email validation
* Role assignment
* Automatic invitation emails

### **Form Integration**

* Extends user onboarding schema
* Transactional data processing
* Automatic user completion status

## Component Props

<AutoTypeTable path="../../kit/organization-features/org-onboarding/src/components/organization-onboarding.tsx" name="OrganizationOnboardingProps" defaultOpen={['metadata']} />

## When to Use

Use organization onboarding when you want users to:

* Set up their organization immediately after registration
* Invite team members during onboarding
* Create a complete workspace setup experience

For simpler flows, use [User Onboarding](/docs/web/features/onboarding) instead.

## Architecture

The organization onboarding builds on top of user onboarding by:

1. Extending `USER_ONBOARDING_STEP` with organization steps
2. Adding organization-specific schemas
3. Providing dedicated server actions for organization data
4. Handling complex membership and invitation logic

This modular approach keeps the code maintainable while providing a rich onboarding experience.


# web: Translations
URL: /docs/web/features/translations
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/translations/index.mdx

Boost accessibility and reach a wider audience by translating your app into multiple languages.
        
***

title: Translations
description: Boost accessibility and reach a wider audience by translating your app into multiple languages.
links:
'i18next': "[https://www.i18next.com](https://www.i18next.com)"
'react-i18next': "[https://react.i18next.com](https://react.i18next.com)"
-------------------------------------------------------------------------

<Callout>
  This feature is implemented in the `@kit/i18n` package.
</Callout>

This feature is implemented in all the applications of the kit. **By default, no setup is needed.**

The following steps describe how to implement translations inside a new application.

## Setup

<Steps>
  <Step>
    ### 1. Installation
  </Step>

  ```bash
  npm install '@kit/i18n@workspace:*'
  ```

  <Step>
    ### 2. Configuration file
  </Step>

  Create a new file `config/i18n.config.ts` with the following content:

  ```ts title="config/i18n.config.ts" showLineNumbers {1,9-14}
  import { parseI18nConfig } from '@kit/i18n/config';
  import { DEFAULT_LANG, SUPPORTED_LANGS } from '@kit/i18n/defined-languages';

  async function i18nResolver(language: string, namespace: string) {
      const data = await import(`../public/locales/${language}/${namespace}.json`);
      return data as Record<string, string>;
  }

  export const i18nConfig = parseI18nConfig({
      defaultLanguage: DEFAULT_LANG,
      languages: SUPPORTED_LANGS,
      namespaces: ['common', 'homepage', 'blog', 'documentation'],
      resolver: i18nResolver,
  });

  ```

  `I18nConfig`

  <AutoTypeTable path="../../kit/i18n/src/config.ts" name="I18nConfig" />

  <Step>
    ### 3. Proxy
  </Step>

  ```ts title="proxy.ts" showLineNumbers {1,7}
  import { i18nProxy } from '@kit/i18n/proxy';
  import { NextResponse, type NextRequest } from 'next/server';
  import { i18nConfig } from './config/i18n.config';

  export async function proxy(request: NextRequest): Promise<NextResponse<unknown>> {
      const response = NextResponse.next();
      return await i18nProxy(request, response, i18nConfig);
  }

  export const config = {
      matcher: ['/((?!_next/static|_next/image|images|locales|assets|api/*).*)'],
  };
  ```

  <Step>
    ### 4. Server instance
  </Step>

  ```ts title="lib/i18n.server.ts" showLineNumbers {2,5}
  import { cache } from 'react';
  import { createI18nServerInstance } from '@kit/i18n/server';
  import { i18nConfig } from '~/config/i18n.config';

  export const getServerI18n = cache(() => createI18nServerInstance(i18nConfig));

  ```

  <Callout>
    `getServerI18n` returns an **i18n** instance that you can use server-side. See the [server-side section](/docs/web/features/translations/usage#server-side-translations) for more details.
  </Callout>

  <Step>
    ### 5. Add a provider
  </Step>

  ```ts title="apps/layout.ts" showLineNumbers {3-5,9,14}
  import React from 'react';

  import { getServerI18n } from '~/lib/i18n.server';
  import { I18nProvider } from '@kit/i18n/provider';
  import { i18nConfig } from '~/config/i18n.config';

  export default async function RootLayout({ children }: React.PropsWithChildren): Promise<React.JSX.Element> {
      // load the language from the server
      const { language } = await getServerI18n();
      
      return (
          <html lang={language}>
              <body>
                  <I18nProvider config={i18nConfig} lang={language}>
                      {children}
                  </I18nProvider>
              </body>
          </html>
      );
  }

  ```
</Steps>

## Package translations

We support monorepo package translations.

It exists two ways to manage translations for packages inside a monorepo :

* 1. Use a different i18n instance in each packages.
* 2. Share package translations with the main application i18n instance.

It exists different pros and cons for each approach.

| Approach           | Pros                                     | Cons                                                                                                                                   |
| ------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| New i18n instance  | - No setup in the consuming application. | - Hard to **initialize** and **synchronize** all i18n instances.<br /> - The package i18n instance must be used for each translations. |
| Share translations | - No extra setup in the package.         | - We must install package translations in the application via the configuration file.                                                  |

**For those reasons, we are using the second approach.**

### Translations installation

All the packages exposing a `/i18n` endpoints own translations.

Here is an example with the `@kit/auth` package.

By convention:

* `/i18n` provide the namespace name.
* `/i18n/locales` provide the translations files.

```ts title="config/i18n.config.ts" showLineNumbers {9,21}
import { I18N_AUTH_NAMESPACES } from '@kit/auth/i18n';
import { parseI18nConfig } from '@kit/i18n/config';
import { DEFAULT_LANG, SUPPORTED_LANGS } from '@kit/i18n/defined-languages';

async function i18nResolver(language: string, namespace: string) {
    if (I18N_AUTH_NAMESPACES.includes(namespace as 'auth')) {
        const data = await import(
            // relative path to the package translations
            `../../../kit/www/features/auth/src/i18n/locales/${language}/${namespace}.json`
        );

        return data as Record<string, string>;
    }
    const data = await import(`../public/locales/${language}/${namespace}.json`);
    return data as Record<string, string>;
}

export const i18nConfig = parseI18nConfig({
    defaultLanguage: DEFAULT_LANG,
    languages: SUPPORTED_LANGS,
    namespaces: ['common', ...I18N_AUTH_NAMESPACES],
    resolver: i18nResolver,
});

```

## Add new languages

Let's say you want to add the language **fr** (french).

<Steps>
  <Step>Update the `SUPPORTED_LANGS` constant.</Step>

  You have to update the languages array in the config files.

  To do this, update the `SUPPORTED_LANGS` constant inside the `@kit/i18n` package.

  ```ts title="i18n/src/i18n/defined-languages.ts" showLineNumbers {9}
  export const SUPPORTED_LANGS = ['en', 'fr'] as const;
  ```

  <Step>Add json translation files inside all the `locales` folders.</Step>

  Translate :

  * your application json files.
  * the json translation files from the packages used by your application.

  <Callout>
    We advise you to use an AI agent to translate your application.
  </Callout>
</Steps>

## Typescript support

i18next provide a type inference for the translations. Check the [i18next typescript documentation](https://www.i18next.com/overview/typescript) for more details.

<Image src="/docs/web/translation-i18next-typescript-autocompletion.png" alt="i18next typescript autocompletion" width="600" height="400" size="md" />

Follow this steps to enable the typescript support in a `@kit/dummy` package :

<Steps>
  <Step>Create a `@types` folder at the root of the package and create a `i18n.d.ts` file inside it.</Step>

  <Files>
    <Folder name="@types" defaultOpen>
      <File name="i18n.d.ts" />
    </Folder>

    <Folder name="src" />

    <File name="package.json" />

    <File name="tsconfig.json" />
  </Files>

  <Step>Copy paste the following code into the `@types/i18n.d.ts` file.</Step>

  ```ts title="@types/i18n.d.ts" showLineNumbers {3,9}
  import "i18next";

  import enExample from '../src/i18n/locales/en/example.json'

  declare module "i18next" {
    interface CustomTypeOptions {
      defaultNS: "example";
      resources: {
          example: typeof enExample;
          // ... other namespaces
      };
    }
  }
  ```

  <Step>Add the following `typeRoots` attribute to the `tsconfig.json` file.</Step>

  ```json title="tsconfig.json" showLineNumbers {4}
  {
      "extends": "@kit/tsconfig/base.json",
      "compilerOptions": {
          "typeRoots": ["./node_modules/@types", "./@types"],
          // ...
      },
  }

  ```
</Steps>

## What's next ?

* [Client-side translations](/docs/web/features/translations/usage#usetranslation-hook)
* [Server-side translations](/docs/web/features/translations/usage#server-side-translations)
* [Language selector](/docs/web/features/translations/language-selector)


# web: Language Selector
URL: /docs/web/features/translations/language-selector
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/translations/language-selector.mdx

Allow users to switch between languages.
        
***

title: Language Selector
description: Allow users to switch between languages.
-----------------------------------------------------

<Callout>
  This component is accessible with the `@kit/i18n/ui` package.
</Callout>

<ComponentPreview name="language-selector-demo" description="Interactive language selector with flag icons" align="center" />

## Features

* **Multiple display modes**: Choose between dropdown and square flag-only variants
* **Automatic language detection**: Uses the current i18n instance from **react-i18next**
* **Flag icons**: Displays country flags for each language
* **Customizable rendering**: Support for custom item and trigger rendering
* **Accessible**: Built on top of Radix UI primitives for full accessibility

## Anatomy

```tsx showLineNumbers
import { LanguageSelector, LanguageSelectorBase } from '@kit/i18n/language-selector';
```

```tsx showLineNumbers
<LanguageSelector>
    <LanguageSelectorTrigger />
    <LanguageSelectorContent>
        <LanguageSelectorItems />
    </LanguageSelectorContent>
</LanguageSelector>
```

## Base component

If you don't need heavy customization, you can use the `LanguageSelectorBase` component.

<ComponentPreview name="language-base-selector-demo" description="Base language selector" align="center" />

```tsx showLineNumbers
<LanguageSelectorBase />
```

## API Reference

### Root

`LanguageSelectorRootProps`

<AutoTypeTable path="../../kit/i18n/src/ui/language-selector.tsx" name="LanguageSelectorRootProps" />

### Flag

`LanguageSelectorFlagProps`

<AutoTypeTable path="../../kit/i18n/src/ui/language-selector.tsx" name="LanguageSelectorFlagProps" />

### Trigger

`LanguageSelectorTriggerProps`

<AutoTypeTable path="../../kit/i18n/src/ui/language-selector.tsx" name="LanguageSelectorTriggerProps" />

### Items

`LanguageSelectorItemsProps`

<AutoTypeTable path="../../kit/i18n/src/ui/language-selector.tsx" name="LanguageSelectorItemsProps" />

### Base

`LanguageSelectorBaseProps`

<AutoTypeTable path="../../kit/i18n/src/ui/language-selector.tsx" name="LanguageSelectorBaseProps" />


# web: Translation Usage
URL: /docs/web/features/translations/usage
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/translations/usage.mdx

Learn how to use the translations in your application.
        
***

title: Translation Usage
description: Learn how to use the translations in your application.
links:
'useTranslation hook': "[https://react.i18next.com/latest/usetranslation-hook](https://react.i18next.com/latest/usetranslation-hook)"
'Trans component': "[https://react.i18next.com/latest/trans-component](https://react.i18next.com/latest/trans-component)"
'Interpolation': "[https://www.i18next.com/translation-function/interpolation](https://www.i18next.com/translation-function/interpolation)"
'Best practices': "[https://www.i18next.com/principles/best-practices#implications-of-interpolation-for-localization](https://www.i18next.com/principles/best-practices#implications-of-interpolation-for-localization)"
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## useTranslation hook

As mentioned in the [react i18next documentation](https://react.i18next.com/latest/usetranslation-hook),
the preferred way to translate a string is to use the `useTranslation` hook from react-i18next.

```tsx
'use client';

import { useTranslation } from 'react-i18next';

export function MyComponent() {
  const { t, i18n: {language: locale} } = useTranslation('common');
  // the locale var contains the active language code   
  
  return <Button aria-label={{t('homeTabLabel')}}>
    <Trans i18nKey="auth.signUpTitle" ns="dashboard" >
  </Button>;
}
```

<Callout>
  Even if `useTranslation` is a hook and can be used in client side only, **translations are server side compatible.**

  *By default translations are loaded client side, you won't see any translations until the page is loaded.*

  But we solved that issue by loading translations server side.
</Callout>

## Server-side translations

When you need translations server side, you can use the `getServerI18n` function set in the `~/lib/i18n.server.ts` file ([see previous page](/docs/web/features/translations#server-instance)).

```tsx showLineNumbers {1,4,12}
import { getServerI18n } from '~/lib/i18n.server';

export async function generateMetadata() {
  const { t, language } = await getServerI18n();

  return {
    title: t('marketing:contact'),
  };
}

export function ContactPage() {
  const { t } = await getServerI18n();
  
  return <h1>{t('marketing:homeTabLabel')}</h1>;
}

```

## How to use data in translations

```json title="locales/en/translation-file.json" showLineNumbers
{
  "key": "{{what}} is {{how}}",
  "keyWithDataModel": "I am {{author.name}}"
}
```

```ts showLineNumbers
// ...
t('key', { what: 'i18next', how: 'great' });

const author = { 
    name: 'Jan',
    github: 'jamuhl'
};
t('keyWithDataModel', { author });
// ...
```

<Callout>
  Check the official i18next documentation for more information about [interpolation](https://www.i18next.com/translation-function/interpolation).
</Callout>

## How use custom tags

```json title="locales/en/translation-file.json" showLineNumbers
{
  "key": "This is my <span>emphasized text</span> here",
}
```

```ts showLineNumbers
// ...
t.rich('key', {
    span: (chunks) => <span className="font-semibold">{chunks}</span>,
})
// ...
```

## Constant translation

When you need to use a translation in a constant, transform it to a function that accepts the translation function.

Before:

```ts showLineNumbers
const ITEMS = [
  {
    name: 'Home',
    icon: HomeIcon,
  },
  {
    name: 'Settings',
    icon: SettingsIcon,
  },
  {
    name: 'Profile',
    icon: UserIcon,
  },
]
```

After:

```ts showLineNumbers {1}
const getItems = (t: ReturnType<typeof useTranslation<'homepage'>>['t']) => {
  return [
    {
      name: t('navigation.home'),
      icon: HomeIcon,
    },
    {
      name: t('navigation.settings'),
      icon: SettingsIcon,
    },
    {
      name: t('navigation.profile'),
      icon: UserIcon,
    },
  ]
}
```


# web: Metrics Card
URL: /docs/web/ui/analytic/metrics-card
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/ui/analytic/metrics-card.mdx

A composable metrics card component for displaying analytics data with charts, values, and trends.
        
***

title: Metrics Card
description: A composable metrics card component for displaying analytics data with charts, values, and trends.
links:
'shadcn/ui Chart': "[https://ui.shadcn.com/docs/components/chart](https://ui.shadcn.com/docs/components/chart)"
'shadcn/ui Card': "[https://ui.shadcn.com/docs/components/card](https://ui.shadcn.com/docs/components/card)"
'Recharts': "[https://recharts.org/en-US/](https://recharts.org/en-US/)"
------------------------------------------------------------------------

## Features

* Radix component architecture for maximum composability
* Multiple aggregation methods (sum, average, last, first, min, max)
* Advanced value formatting (number, currency, percentage, compact)
* Built-in chart visualization with Recharts
* Automatic trend calculation with visual indicators
* Two layout variants (default and wide-chart)
* Locale-aware number formatting
* Fully customizable styling

## Installation

<Steps>
  <Step>Install the following dependencies:</Step>

  ```bash
  npm install recharts class-variance-authority
  ```

  <Step>Make sure that the following shadcn/ui components are present in your project:</Step>

  * [Card](https://ui.shadcn.com/docs/components/card)
  * [Chart](https://ui.shadcn.com/docs/components/chart)
  * [Tooltip](https://ui.shadcn.com/docs/components/tooltip)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="metrics-card" title="components/analytics/metrics-card.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

### Anatomy

```tsx showLineNumbers
import {
  MetricsCard,
  MetricsCardHeader,
  MetricsCardTitle,
  MetricsCardDescription,
  MetricsCardAction,
  MetricsCardContent,
  MetricsCardValue,
  MetricsCardChart,
  MetricsCardChange,
} from '@kit/content-type/analytics/metrics-card';
```

### Basic Example

```tsx showLineNumbers
<MetricsCard
  data={[
    { date: '2024-01', revenue: 1200 },
    { date: '2024-02', revenue: 1800 },
    { date: '2024-03', revenue: 2400 },
  ]}
  dataKey="revenue"
>
  <MetricsCardHeader icon={Icon.dollarSign}>
    <MetricsCardTitle>Total Revenue</MetricsCardTitle>
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold">
      <MetricsCardValue format="currency" currency="USD" decimals={2} />
    </div>
    <MetricsCardChange />
  </MetricsCardContent>
</MetricsCard>
```

### With Chart

```tsx showLineNumbers
<MetricsCard
  data={[
    { date: '2024-01', users: 150 },
    { date: '2024-02', users: 230 },
    { date: '2024-03', users: 340 },
    { date: '2024-04', users: 420 },
  ]}
  dataKey="users"
>
  <MetricsCardHeader icon={Icon.users}>
    <MetricsCardTitle>Active Users</MetricsCardTitle>
    <MetricsCardAction tooltipInfo="Total number of active users" />
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold">
      <MetricsCardValue method="last" />
    </div>
    <div className="flex items-center justify-between">
      <MetricsCardChange />
      <MetricsCardChart
        height={39}
        color="#3b82f6"
        config={{
          users: { label: 'Users', color: '#3b82f6' },
        }}
      />
    </div>
  </MetricsCardContent>
</MetricsCard>
```

### Wide Chart Variant

```tsx showLineNumbers
<MetricsCard
  data={data}
  dataKey="sales"
  variant="wide-chart"
>
  <MetricsCardHeader icon={Icon.trendingUp}>
    <MetricsCardTitle>Sales Overview</MetricsCardTitle>
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="flex items-center justify-between mb-4">
      <div className="text-3xl font-bold">
        <MetricsCardValue format="currency" currency="EUR" />
      </div>
      <MetricsCardChange />
    </div>
    <MetricsCardChart
      height={120}
      color="#10b981"
      config={{
        sales: { label: 'Sales', color: '#10b981' },
      }}
    />
  </MetricsCardContent>
</MetricsCard>
```

## Component Architecture

The MetricsCard follows the Radix component pattern, providing a composable API through context:

* **MetricsCard**: Root component that provides context (data, dataKey, variant)
* **MetricsCardHeader**: Container for title and actions
* **MetricsCardTitle**: Display the metric title
* **MetricsCardDescription**: Optional description text
* **MetricsCardAction**: Info tooltip icon
* **MetricsCardContent**: Main content container with variant-based styling
* **MetricsCardValue**: Displays aggregated and formatted values
* **MetricsCardChart**: Renders a line chart visualization
* **MetricsCardChange**: Shows percentage change with trend indicators

## Aggregation Methods

The `MetricsCardValue` component supports multiple aggregation methods via the `method` prop:

| Method    | Description            | Use Case                           |
| --------- | ---------------------- | ---------------------------------- |
| `sum`     | Sum of all values      | Total revenue, total orders        |
| `average` | Average of all values  | Average order value, avg. rating   |
| `last`    | Last value in dataset  | Current active users, latest price |
| `first`   | First value in dataset | Starting value, baseline           |
| `min`     | Minimum value          | Lowest price, min. stock           |
| `max`     | Maximum value          | Peak traffic, max. capacity        |

```tsx showLineNumbers
// Sum all values (default)
<MetricsCardValue method="sum" />

// Show average
<MetricsCardValue method="average" decimals={2} />

// Display last value
<MetricsCardValue method="last" />
```

## Value Formatting

The `MetricsCardValue` component provides comprehensive formatting options:

### Format Types

| Format       | Description                     | Example Output |
| ------------ | ------------------------------- | -------------- |
| `number`     | Standard number with separators | `1 234 567`    |
| `currency`   | Locale-aware currency           | `$1,234.56`    |
| `percentage` | Percentage format               | `45.67%`       |
| `compact`    | Compact notation                | `1.2M`, `3.4K` |
| `custom`     | Simple decimal                  | `1234.56`      |

### Number Format

```tsx showLineNumbers
// Default: space separator
<MetricsCardValue format="number" />
// Output: 1 234 567

// Comma separator
<MetricsCardValue format="number" separator="," />
// Output: 1,234,567

// With decimals
<MetricsCardValue format="number" decimals={2} />
// Output: 1 234 567.89
```

### Currency Format

```tsx showLineNumbers
// USD (default)
<MetricsCardValue format="currency" currency="USD" decimals={2} />
// Output: $1,234.56

// Euro with French locale
<MetricsCardValue
  format="currency"
  currency="EUR"
  locale="fr-FR"
  decimals={2}
/>
// Output: 1 234,56 €

// British Pound
<MetricsCardValue format="currency" currency="GBP" decimals={2} />
// Output: £1,234.56
```

### Percentage Format

```tsx showLineNumbers
// Assumes data contains decimal values (0.4567 becomes 45.67%)
<MetricsCardValue format="percentage" decimals={2} />
// Output: 45.67%
```

### Compact Format

```tsx showLineNumbers
// Ideal for large numbers
<MetricsCardValue format="compact" decimals={1} />
// 1234567 → 1.2M
// 1234 → 1.2K
// 1234567890 → 1.2B
```

### Custom Formatting

```tsx showLineNumbers
// Prefix and suffix
<MetricsCardValue prefix="~" suffix=" units" />
// Output: ~1234 units

// Custom formatter function
<MetricsCardValue
  formatter={(value) => `${value.toLocaleString()} items sold`}
/>
// Output: 1,234 items sold

// Custom value override
<MetricsCardValue customValue={42} format="number" />
// Output: 42
```

## Chart Configuration

The `MetricsCardChart` component uses Recharts and shadcn/ui Chart:

```tsx showLineNumbers
<MetricsCardChart
  height={39}              // Chart height in pixels
  color="#3b82f6"          // Line color
  config={{                // Chart configuration
    revenue: {
      label: 'Revenue',
      color: '#3b82f6',
    },
  }}
/>
```

### Chart Features

* Automatic scaling with 10% padding
* Hidden axes for clean appearance
* Linear interpolation
* Responsive width
* Gradient support (built-in)
* Accessibility layer enabled

## Trend Indicators

The `MetricsCardChange` component automatically calculates percentage change between the last two data points:

```tsx showLineNumbers
<MetricsCardChange />
```

**Features:**

* Automatic color coding (green for increase, red for decrease)
* Trend icons (↑ for increase, ↓ for decrease)
* Percentage calculation
* Handles edge cases (division by zero, insufficient data)
* Variant-aware text sizing

## Variants

### Default Variant

Optimized for compact metric displays with optional small charts:

```tsx showLineNumbers
<MetricsCard data={data} dataKey="value" variant="default">
  {/* Content uses flexbox layout with vertical justification */}
</MetricsCard>
```

### Wide Chart Variant

Better for prominent chart visualizations:

```tsx showLineNumbers
<MetricsCard data={data} dataKey="value" variant="wide-chart">
  {/* Content uses standard layout for larger charts */}
</MetricsCard>
```

## Examples

### E-commerce Revenue Card

```tsx showLineNumbers
<MetricsCard
  data={revenueData}
  dataKey="revenue"
>
  <MetricsCardHeader icon={Icon.dollarSign}>
    <MetricsCardTitle>Monthly Revenue</MetricsCardTitle>
    <MetricsCardAction tooltipInfo="Total revenue for the current month" />
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold">
      <MetricsCardValue
        method="sum"
        format="currency"
        currency="USD"
        decimals={2}
      />
    </div>
    <div className="flex items-center justify-between">
      <MetricsCardChange />
      <MetricsCardChart
        height={39}
        color="#10b981"
        config={{
          revenue: { label: 'Revenue', color: '#10b981' },
        }}
      />
    </div>
  </MetricsCardContent>
</MetricsCard>
```

### User Growth Percentage

```tsx showLineNumbers
<MetricsCard
  data={growthData}
  dataKey="growthRate"
>
  <MetricsCardHeader icon={Icon.trendingUp}>
    <MetricsCardTitle>Growth Rate</MetricsCardTitle>
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold text-emerald-600">
      <MetricsCardValue
        method="average"
        format="percentage"
        decimals={1}
      />
    </div>
    <MetricsCardChange />
  </MetricsCardContent>
</MetricsCard>
```

### Conversion Rate with Description

```tsx showLineNumbers
<MetricsCard
  data={conversionData}
  dataKey="rate"
>
  <MetricsCardHeader icon={Icon.target}>
    <div>
      <MetricsCardTitle>Conversion Rate</MetricsCardTitle>
      <MetricsCardDescription>
        Last 30 days
      </MetricsCardDescription>
    </div>
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold">
      <MetricsCardValue
        method="average"
        format="percentage"
        decimals={2}
      />
    </div>
    <MetricsCardChange />
  </MetricsCardContent>
</MetricsCard>
```

## API Reference

<AutoTypeTable path="../../kit/content-type/src/components/analytics/metrics-card.tsx" name="MetricsCardProps" />

<AutoTypeTable path="../../kit/content-type/src/components/analytics/metrics-card.tsx" name="MetricsCardHeaderProps" />

<AutoTypeTable path="../../kit/content-type/src/components/analytics/metrics-card.tsx" name="MetricsCardTitleProps" />

<AutoTypeTable path="../../kit/content-type/src/components/analytics/metrics-card.tsx" name="MetricsCardDescriptionProps" />

<AutoTypeTable path="../../kit/content-type/src/components/analytics/metrics-card.tsx" name="MetricsCardActionProps" />

<AutoTypeTable path="../../kit/content-type/src/components/analytics/metrics-card.tsx" name="MetricsCardContentProps" />

<AutoTypeTable path="../../kit/content-type/src/components/analytics/metrics-card.tsx" name="MetricsCardValueProps" />

<AutoTypeTable path="../../kit/content-type/src/components/analytics/metrics-card.tsx" name="MetricsCardChartProps" />

<AutoTypeTable path="../../kit/content-type/src/components/analytics/metrics-card.tsx" name="MetricsCardVariationProps" />


# web: Content Table
URL: /docs/web/ui/content-type/content-table
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/ui/content-type/content-table.mdx

A content table component to display a table of content.
        
***

title: Content Table
description: A content table component to display a table of content.
links:
'shadcn/ui Data Table': "[https://ui.shadcn.com/docs/components/data-table](https://ui.shadcn.com/docs/components/data-table)"
'tanstack/react-table': "[https://tanstack.com/table/v8/docs/framework/react/overview](https://tanstack.com/table/v8/docs/framework/react/overview)"
----------------------------------------------------------------------------------------------------------------------------------------------------

to implement


# web: AskAI
URL: /docs/web/features/cms/components/ask-ai
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/cms/components/ask-ai.mdx

Enable users to ask AI questions about your content with integrated LLM endpoints.
        
***

title: AskAI
description: Enable users to ask AI questions about your content with integrated LLM endpoints.
package: "@kit/cms"
-------------------

<ComponentPreview name="ask-ai-demo" description="An AI assistant button for content interaction" align="center" />

## Overview

The AskAI component provides a seamless way for users to interact with AI assistants about your content. It creates contextual prompts and opens conversations in popular AI platforms like ChatGPT, Grok, and others, using your LLM endpoints for accurate, content-aware responses.

## How It Works

<Callout>
  This component requires you to have an LLM endpoint set up to work. See the [LLM Endpoints documentation](/docs/web/features/cms/notion/llms) for details.
</Callout>

The AskAI component generates intelligent prompts that include:

* **Context about your company/product**
* **Direct links to your documentation**
* **Instructions for the AI to provide helpful assistance**

When clicked, it opens a dropdown menu with options to continue the conversation in various AI platforms.

<Steps>
  <Step>Install the required dependencies:</Step>

  The AskAI component uses Radix UI components for the dropdown interface.

  ```bash
  npm install @radix-ui/react-dropdown-menu @radix-ui/react-popover
  ```

  <Step>Make sure that the following shadcn/ui components are present in your project:</Step>

  * [Dropdown Menu](https://ui.shadcn.com/docs/components/dropdown-menu)
  * [Popover](https://ui.shadcn.com/docs/components/popover)
  * [Button](https://ui.shadcn.com/docs/components/button)
  * [Separator](https://ui.shadcn.com/docs/components/separator)
  * [Tooltip](https://ui.shadcn.com/docs/components/tooltip)

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="ask-ai" title="components/ui/ask-ai.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Integrated LLM endpoints

| Endpoint         | Description                                                        |
| ---------------- | ------------------------------------------------------------------ |
| View as Markdown | Direct link to your LLM endpoint                                   |
| ChatGPT          | OpenAI's conversational AI                                         |
| Grok             | xAI's helpful and maximally truthful AI                            |
| Claude           | Anthropic's constitutional AI (do not support pre-filling prompts) |
| v0               | Vercel's AI-powered design tool                                    |
| Scira AI         | Advanced AI assistant                                              |
| t3               | t3.chat's AI assistant (do not support pre-filling prompts)        |

## Usage

```tsx showLineNumbers
import { AskAi } from '@kit/cms/ui/ask-ai';
```

```tsx showLineNumbers
<AskAi
    url={'/path/to/your/md/endpoint'}
    companyName="Your Blog"
/>
```

## API Reference

`AskAiProps`

<AutoTypeTable path="../../kit/cms/core/src/components/ask-ai.tsx" name="AskAiProps" />


# web: Scroll to Top
URL: /docs/web/features/cms/components/scroll-to-top
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/cms/components/scroll-to-top.mdx

Enable users to quickly navigate back to the top of long pages with a smooth scroll-to-top button.
        
***

title: Scroll to Top
description: Enable users to quickly navigate back to the top of long pages with a smooth scroll-to-top button.
package: "@kit/cms"
-------------------

<Callout>
  The ScrollToTop component automatically shows/hides based on scroll position and provides smooth scrolling back to the top.
</Callout>

A floating scroll-to-top button that appears when users scroll down a page, helping them quickly return to the top with smooth scrolling animation.

## Installation

<Steps>
  <Step>Install the required dependencies:</Step>

  The ScrollToTop component requires the kit packages for UI components.

  ```bash
  npm install '@kit/cms@workspace:*'
  ```

  <Step>Make sure that the following kit packages are present in your project:</Step>

  The ScrollToTop component uses internal kit packages that should already be available in your project:

  * [@kit/ui/button](https://github.com/fuma-nama/fumadocs) - Button component
  * [@kit/ui/icon](https://github.com/fuma-nama/fumadocs) - Icon components
  * [@kit/shared](https://github.com/fuma-nama/fumadocs) - Utility functions

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="scroll-to-top-button" title="components/ui/scroll-to-top-button.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { ScrollToTopButton } from '@kit/cms/ui/scroll-to-top-button';
```

```tsx showLineNumbers
// Place at the bottom of your page or layout
<div className="fixed bottom-0 right-0 p-4">
    <ScrollToTopButton />
</div>
```

## Features

* **Auto-show/hide**: Appears when scrolled more than 300px from top
* **Smooth scrolling**: Animates smoothly back to the top
* **Accessible**: Proper ARIA labels and keyboard navigation
* **Responsive**: Works on all screen sizes
* **Performance optimized**: Efficient scroll event handling

<ComponentPreview name="scroll-to-top-demo" description="A scroll-to-top button that appears on long pages" align="center" variant="content" />

## API Reference

`ScrollToTopButtonProps`

<AutoTypeTable path="../../kit/cms/core/src/components/scroll-to-top-button.tsx" name="ScrollToTopButtonProps" />


# web: Table of Contents
URL: /docs/web/features/cms/components/toc
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/cms/components/toc.mdx

Enable users to navigate through your content with an interactive table of contents and progress indicator.
        
***

title: Table of Contents
description: Enable users to navigate through your content with an interactive table of contents and progress indicator.
package: "@kit/cms"
-------------------

<ComponentPreview name="toc-demo" description="An interactive table of contents with progress indicator" align="center" />

<Callout>
  The UI of this component is inspired from the Fumadocs TOC component.
</Callout>

An interactive table of contents with progress tracking and active section highlighting. Automatically detects headings and provides smooth navigation for long-form content.

## Installation

<Steps>
  <Step>Install the required dependencies:</Step>

  The TOC component requires the Fumadocs core package for the TableOfContents type.

  ```bash
  npm install '@kit/cms@workspace:*'
  ```

  <Step>Make sure that the following kit packages are present in your project:</Step>

  The TOC component uses internal kit packages that should already be available in your project:

  * [@kit/ui/icon](https://github.com/fuma-nama/fumadocs) - Icon components
  * [@kit/shared](https://github.com/fuma-nama/fumadocs) - Utility functions

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="toc" title="components/ui/toc.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## Usage

```tsx showLineNumbers
import { type TableOfContents, Toc, TocContent, TocNav, TocProgressIndicator, TocTitle } from '@kit/cms/ui/toc';
```

```tsx showLineNumbers
<Toc toc={sampleToc} variant="indented" referenceTop={57} single={false}>
    <div className="flex flex-col gap-2 p-4 pt-0 text-sm">
        <TocTitle title="Table of Contents" />
        <TocContent>
            <TocProgressIndicator />
            <TocNav />
        </TocContent>
    </div>
</Toc>
```

## Features

* **Visual progress indicator** with indented or straight variants
* **Active section tracking** - single or multiple mode
* **Responsive design** for all screen sizes
* **Smooth scroll updates** with requestAnimationFrame optimization

## Toc Data

To be able to use this component with your fumadocs and your notion content, you use the same type as the Fumadocs TOC component. The notion client take care to return a compatible `toc` object.

The fumadocs type is exported from the `@kit/cms/ui/toc` package.

```ts
import { type TableOfContents } from '@kit/cms/ui/toc';
```

## API Reference

### Root

`TocProps`

<AutoTypeTable path="../../kit/cms/core/src/components/toc.tsx" name="TocProps" />

### Title

`TocTitleProps`

<AutoTypeTable path="../../kit/cms/core/src/components/toc.tsx" name="TocTitleProps" />

### Content

`TocContentProps`

<AutoTypeTable path="../../kit/cms/core/src/components/toc.tsx" name="TocContentProps" />

### Progress Indicator

`TocProgressIndicatorProps`

<AutoTypeTable path="../../kit/cms/core/src/components/toc.tsx" name="TocProgressIndicatorProps" />

### Nav

`TocNavProps`

<AutoTypeTable path="../../kit/cms/core/src/components/toc.tsx" name="TocNavProps" />

### SimpleToc

Use this components to avoid the pain of handling all the previous components.

```tsx
<SimpleToc
    toc={toc}
    variant="indented"
    referenceTop={100}
    single={false}
/>
```


# web: Notion
URL: /docs/web/features/cms/notion
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/cms/notion/index.mdx

Learn how to use Notion as Content Management System in your application.
        
***

title: Notion
description: Learn how to use Notion as Content Management System in your application.
links:
'Notion': "[https://www.notion.com](https://www.notion.com)"
'Notion API': "[https://developers.notion.com/reference](https://developers.notion.com/reference)"
package: "@kit/notion"
----------------------

In this guide, we gonna implement a blog using Notion as a content management system.

<Callout>
  The `@kit/notion` package contains a type-safe client built using zod to validate the data. Our client is built on top of the `notionhq/client` package which is the official Notion client.
</Callout>

## Create a notion database

The easiest way is to import our database template.

<Steps>
  <Step>Download the database template.</Step>

  <DownloadButton href="/docs/notion/database-templates/Blog.csv" filename="Blog.csv" className="mx-auto">
    Blog Template
  </DownloadButton>

  <Callout>
    We recommend you to use our template to make it work with the already existing ui. But you can customize it to your needs.
  </Callout>

  <Step>Import it in your Notion workspace.</Step>

  <Video src="/docs/notion/import-blog-database.mp4" title="Importing the blog database template in Notion" className="ml-0" captionClassName="text-left" controls />
</Steps>

## Set your Notion Connection to expose your data

<Steps>
  <Step>Add a new integration.</Step>

  In the browser, go to [https://www.notion.so/profile/integrations](https://www.notion.so/profile/integrations) and add a "New integration".

  <Callout>
    You can let the `type` to `Public` is not required, you can let it `Internal`.
  </Callout>

  <Step>Configure your integration settings.</Step>

  In "Configuration" tab > Capabilities we gonna need :

  * Select "Read content" only (remove the other capabilities)
  * Select "No user information" (in the "User capabilities" section)

  <Step>Set the `NOTION_INTEGRATION_SECRET` environment variable.</Step>

  Show the **"Internal Integration Secret"** field and copy the value.

  Use the copied value to set the `NOTION_INTEGRATION_SECRET` environment variable.

  ```dotenv
  NOTION_INTEGRATION_SECRET=your-integration-secret
  ```
</Steps>

## Set your config file

Create a `config/cms.config.ts` file in your application and set the `NOTION_INTEGRATION_SECRET` environment variable.

```ts showLineNumbers title="config/cms.config.ts"
'server-only';

import { parseNotionConfig } from '@kit/notion/config';
import { envs } from '~/envs';

export const notionConfig = parseNotionConfig({
    auth: envs().NOTION_INTEGRATION_SECRET,
    contentTypes: { // edit this object to fit your needs
        // your content types here ...
    },
});

```

<AutoTypeTable path="../../kit/cms/notion/src/config.ts" name="NotionConfig" />

## Add a new content type

<Steps>
  <Step>
    ### Connect you database
  </Step>

  Connect you database to your previously created integration

  <Video src="/docs/notion/connect-database-to-integration.mp4" title="Connecting your database to your previously created integration" className="ml-0" captionClassName="text-left" controls />

  <Step>
    ### Get your database source id
  </Step>

  <Video src="/docs/notion/get-your-database-source-id.mp4" title="Getting your database source id" className="ml-0" captionClassName="text-left" controls />

  Set the `NOTION_POSTS_DB_ID` environment variable.

  ```dotenv
  NOTION_POSTS_DB_ID=your-database-source-id
  ```

  <Step>
    ### Set your notion definition in the config file
  </Step>

  To let the `@kit/notion` package to know the nature of your database, you need to add it in the `contentTypes` object.

  ```ts showLineNumbers title="config/cms.config.ts" {9-20}
  'server-only';

  import { parseNotionConfig } from '@kit/notion/config';
  import { envs } from '~/envs';

  export const notionConfig = parseNotionConfig({
      auth: envs().NOTION_INTEGRATION_SECRET,
      contentTypes: {
          posts: {
              id: envs().NOTION_POSTS_DB_ID,
              def: {
                  categories: 'multi_select',
                  language: 'select',
                  description: 'rich_text',
                  slug: 'rich_text',
                  image: 'files',
                  status: 'status',
                  title: 'title',
              },
          },
      },
  });

  ```

  Use the following tool to get your notion definition.

  <ComponentPreview name="notion-schema-fetcher" description="A component to fetch the schema of a Notion database" align="center" />

  <Callout variant="info">
    Once your defintion is fetched, you can refresh your "Internal Integration Secret" if you want to have an easy mind.
  </Callout>
</Steps>

## Content type definition requirements

Some properties are using internally in the notion client from the `@kit/notion` package. For that reason, some properties are required and some optional allow you to implement some specific features.

### Required fields

Here is the list of the required fields for a content type definition:

* `title`: `title`
* `slug`: `rich_text` (your slug do not must contains spaces)

### Optional field

* `status`: `status` (allow you to have a `draft`/`published` feature -> the pages will be loaded only if the status is `published`)

<Callout>
  If you are implement a roadmap, definition requiements may be different. Check the [roadmap definition requirements](/docs/web/features/roadmap#content-type-definition-requirements) section.
</Callout>

## Translations

You can easily manage your translations with the `@kit/notion` package.

<Steps>
  <Step>Use the `language` property in your notion database (alredy present our the database template)</Step>

  <Step>Filter your notion content items with the active i18n language</Step>

  ```tsx showLineNumbers title="app/blog/page.tsx" {9}
  'use server';

  async function BlogPage(props: BlogPageProps): Promise<React.JSX.Element> {
      const { t, resolvedLanguage: language } = await getServerI18n();

      const blogPosts = await notionClient.getContentItems({
          contentType: 'posts',
          filter: {
              language,
          },
          sort: {
              by: ['createdTime'],
              direction: 'desc',
          },
          pagination: {
              limit,
              offset,
          },
          content: false,
      });

      return (
          <>
          {/* your page content here */}
          </>
      );
  }

  ```
</Steps>

## Environment variables

```dotenv showLineNumbers title=".env"
NOTION_INTEGRATION_SECRET=your-integration-secret

# your database source id ...
NOTION_POSTS_DB_ID=your-database-source-id
```


# web: LLMs
URL: /docs/web/features/cms/notion/llms
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/cms/notion/llms.mdx

Learn how to expose content for AI models.
        
***

title: LLMs
description: Learn how to expose content for AI models.
links:
'Notion': "[https://www.notion.com](https://www.notion.com)"
'Notion API': "[https://developers.notion.com/reference](https://developers.notion.com/reference)"
package: "@kit/notion"
----------------------

## Overview

Exposing API endpoints for AI models to reference your website content is crucial for building intelligent features like chatbots, search assistants, and content recommendations. These endpoints provide clean, structured access to your content in formats optimized for large language models (LLMs), enabling AI-powered interactions with your documentation, blog posts, and other web content.

## How LLM Endpoints Work

LLM endpoints transform your content into AI-readable formats, typically markdown or plain text optimized for LLM processing. Here's how they work:

### Content Export Endpoints

**Quick Setup**: Create `llm.md` endpoints to export pages as AI-ready markdown.

```typescript showLineNumbers title="/blog/[slug]/llm.md/route.ts"
import { createMarkdownExportHandler } from '@kit/notion/api';

export const GET = createMarkdownExportHandler(notionConfig, 'posts');
```

**What it does:**

* Takes **slug** from URL → fetches content → converts to **markdown** → returns **clean text**

## Benefits for AI Integration

These endpoints enable powerful AI features:

* **Context-aware chatbots** that reference your specific documentation
* **Smart search** that understands content relationships
* **Content recommendations** based on user queries
* **Automated content summarization**
* **Cross-referencing** between related pages

## AskAI Component Integration

This LLM endpoint infrastructure enables the implementation of AI-powered components like the AskAI feature. The AskAI component uses these endpoints to:

1. **Fetch relevant content** based on user queries
2. **Provide contextual answers** using your documentation
3. **Maintain consistency** with your content structure
4. **Offer interactive help** directly in your documentation pages

The AskAI component will be covered in detail in the next documentation section.


# web: Search
URL: /docs/web/features/cms/notion/search
Source:  https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/web/features/cms/notion/search.mdx

Add powerful search functionality to your Notion-powered applications.
        
***

title: Search
description: Add powerful search functionality to your Notion-powered applications.
links:
'Notion': "[https://www.notion.com](https://www.notion.com)"
'Notion API': "[https://developers.notion.com/reference](https://developers.notion.com/reference)"
package: "@kit/notion"
----------------------

<ComponentPreview name="notion-search-dialog-demo" description="A powerful search dialog for Notion content" align="center" />

The Notion Search feature provides a comprehensive search interface that allows users to find content across your Notion-powered blog posts, documentation, or other content types. It combines a sleek UI with powerful backend search capabilities.

## Installation

<Steps>
  <Step>Install the required dependencies:</Step>

  ```bash
  npm install '@kit/notion@workspace:*'
  ```

  <Step>Copy and paste the following code into your project.</Step>

  <ComponentSource name="search-dialog" title="components/ui/search-dialog.tsx" />

  <Step>Update the import paths to match your project setup.</Step>
</Steps>

## How It Works

### Backend API

The search functionality is powered by a REST API endpoint that queries your Notion content:

```typescript showLineNumbers title="/api/notion/search/route.ts" {4}
import { createNotionSearchHandler } from '@kit/notion/api';
import { notionConfig } from '~/config/cms.config';

export const POST = createNotionSearchHandler(notionConfig);
```

### Frontend Component

The `SearchDialog` component provides the user interface, handling search queries, displaying results, and navigation.

```tsx showLineNumbers title="app/blog/[slug]/page.tsx"
import { SearchDialog } from '@kit/notion/ui/search-dialog';
import { notionConfig } from '~/config/cms.config';

export function BlogPage() {
    return (
        <div className="container mx-auto py-8">
            <SearchDialog
                config={notionConfig}
                contentType="posts"
                placeholder="Search blog posts..."
            />
        </div>
    );
}
```

## Features

### Intelligent Search

* **Real-time search** with 300ms debouncing for optimal performance
* **Multi-field matching** across titles, descriptions, and content
* **Relevance scoring** with visual indicators (High/Medium/Low)
* **Match highlighting** shows exactly where matches occur

### User Experience

* **Keyboard shortcuts** - Press `⌘B` (Mac) or `Ctrl+B` (Windows/Linux) to open search
* **Responsive design** works on all screen sizes
* **Loading states** provide feedback during search
* **Empty states** guide users when no results are found

### Result Presentation

* **Rich previews** with titles, descriptions, and match locations
* **Score badges** indicate result relevance
* **Field indicators** show which fields contained matches
* **Performance metrics** display search processing time

## API Reference

`SearchDialogProps`

<AutoTypeTable path="../../kit/cms/notion/src/components/search-dialog.tsx" name="SearchDialogProps" />