### Iconx CLI Project Setup Examples

Source: https://www.saas-js.com/docs/iconx/reference/cli

Demonstrates common project setup patterns using the Iconx CLI, including initialization and adding sets of commonly used icons.

```bash
# Initialize new project
iconx init

# Add common icons
iconx add --set lucide home user settings mail search
```

--------------------------------

### Install Project Dependencies with pnpm

Source: https://www.saas-js.com/docs/starter-kits/nextjs/installation/clone-repository

Installs all project dependencies using the pnpm package manager. Ensure you have pnpm installed; refer to its official installation guide if needed. This command is essential for running the application.

```bash
pnpm
```

--------------------------------

### Start Local Database

Source: https://www.saas-js.com/docs/starter-kits/nextjs/installation/run-application

Starts the local database using Docker Compose. This command assumes Docker is installed and configured on your system.

```shell
docker-compose up
```

--------------------------------

### Run iconx Commands Directly with npx

Source: https://www.saas-js.com/docs/iconx/getting-started/installation

Executes iconx commands such as initializing configuration or adding icons without a prior installation. This is useful for quick setup or testing.

```shell
# Initialize configuration
npx iconx init

# Add icons
npx iconx add --set lucide home user settings
```

--------------------------------

### Start Storybook Server (pnpm)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Starts the Storybook server using pnpm. Storybook is used for developing and showcasing UI components in isolation.

```bash
pnpm storybook
```

--------------------------------

### Quick Start: Initialize Drizzle CRUD and Create Operations

Source: https://www.saas-js.com/docs/drizzle-crud

This snippet demonstrates the basic setup for Drizzle CRUD. It involves defining a Drizzle schema, initializing the database connection, and creating CRUD operations for a 'users' table with specified configurations for search, filtering, and soft deletes. It also shows examples of creating a new user and listing users with search and pagination.

```typescript
import { drizzleCrud } from 'drizzle-crud'
import { zod } from 'drizzle-crud/zod'
import { boolean, pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core'
import { drizzle } from 'drizzle-orm/postgres-js'

// Define your schema
const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull(),
  isActive: boolean('is_active').default(true),
  deletedAt: timestamp('deleted_at'),
  createdAt: timestamp('created_at').defaultNow(),
})

// Initialize database and CRUD factory
const db = drizzle(/* your database connection */)
const createCrud = drizzleCrud(db, {
  validation: zod(),
})

// Create CRUD operations for each table
const userCrud = createCrud(users, {
  searchFields: ['name', 'email'],
  allowedFilters: ['isActive'],
  softDelete: { field: 'deletedAt' },
})

// Use the generated CRUD operations
const newUser = await userCrud.create({
  name: 'John Doe',
  email: 'john@example.com',
})

const usersList = await userCrud.list({
  search: 'john',
  filters: { isActive: true },
  page: 1,
  limit: 10,
})
```

--------------------------------

### Get Current User - Client and Server Components

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/api-procedures/auth

Demonstrates how to fetch the current logged-in user and their associated workspaces using client and server components. This procedure is protected and requires authentication.

```javascript
// Client components
const { data } = api.auth.me.useQuery()

// Server components
const data = await api.auth.me()
```

--------------------------------

### Start Development Server (pnpm)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Starts the development server for the web application using pnpm. This command is used during the development phase to preview changes.

```bash
pnpm dev:web
```

--------------------------------

### Iconx CLI Working with Multiple Icon Sets Examples

Source: https://www.saas-js.com/docs/iconx/reference/cli

Shows examples of how to add icons from different icon sets for various purposes, such as general UI, specific components, or brand logos.

```bash
# Lucide icons for general UI
iconx add --set lucide home user settings

# Heroicons for specific components
iconx add --set heroicons academic-cap beaker

# Font Awesome for brand icons
iconx add --set fa-brands github twitter linkedin
```

--------------------------------

### Installation

Source: https://www.saas-js.com/docs/slingshot

Instructions for installing the Slingshot library and its React components.

```APIDOC
## Installation

To install the Slingshot library and its React components, run the following command:

```bash
npm install @saas-js/slingshot @saas-js/slingshot-react
```
```

--------------------------------

### Complete Iconx Configuration Example

Source: https://www.saas-js.com/docs/iconx/reference/configuration

This example demonstrates a comprehensive icons.json configuration, including schema, output directory, default icon set, icon size, index generation, and a set of icon name aliases.

```json
{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "./src/components/icons",
  "defaultIconSet": "lucide",
  "iconSize": "20px",
  "generateIndex": true,
  "aliases": {
    "house": "home",
    "cog": "settings",
    "user-circle": "profile",
    "envelope": "mail",
    "magnifying-glass": "search"
  }
}
```

--------------------------------

### Setup Git Remotes for Saas UI Project

Source: https://www.saas-js.com/docs/starter-kits/nextjs/installation/clone-repository

Configures Git remotes for the cloned Saas UI repository. It renames the default 'origin' to 'upstream' and provides instructions to add your own repository as the 'origin'. This setup is crucial for managing contributions and pulling updates.

```bash
git remote rename origin upstream
git remote add origin git@github.com:your-username/your-repository.git
```

--------------------------------

### Basic Usage Example (Next.js)

Source: https://www.saas-js.com/docs/slingshot

Example demonstrating how to use the FileUpload component in a Next.js application.

```APIDOC
## Example (Next.js)

### page.tsx
```tsx
import { FileUpload } from '@/components/file-upload'

export default function Page() {
  return (
    <FileUpload
      profile="avatar"
      maxFiles={1}
      baseUrl="/api/slingshot"
      uploadOnAccept
      meta={{ userId: '123' }}
    />
  )
}
```

### components/file-upload.tsx
```tsx
import { FileUpload as FileUploadPrimitive } from '@saas-js/slingshot-react'

import { Button } from '@/components/button'
import { Progress } from '@/components/progress'

export const FileUpload = (props: Omit<FileUpload.RootProps, 'children'>) => {
  return (
    <FileUploadPrimitive.Root {...props}>
      <FileUploadPrimitive.Context>
        {(api) => {
          const files = api.slingshot.getFiles()

          return (
            <>
              <FileUploadPrimitive.Dropzone>
                <FileUploadPrimitive.Label>Drag your file(s) here</FileUploadPrimitive.Label>
                <FileUploadPrimitive.Trigger asChild>
                  <Button>Choose file(s)</Button>
                </FileUploadPrimitive.Trigger>
              </FileUploadPrimitive.Dropzone>

              <FileUploadPrimitive.ItemGroup>
                {files.map((file) => {
                  return (
                    <FileUploadPrimitive.Item
                      key={file.name}
                      file={file.data}>
                      <FileUploadPrimitive.ItemPreview type="image/*">
                        <FileUploadPrimitive.ItemPreviewImage />
                      </FileUploadPrimitive.ItemPreview>
                      <FileUploadPrimitive.ItemName />
                      <FileUploadPrimitive.ItemSizeText />

                      <div>
                        {file.progress &&
                          file.status !== 'done' && (
                            <Progress
                              value={file.progress}
                              type="circular"
                              colorPalette="green"
                            />
                          )}
                        {file.status === 'done' ? 'Done' : null}
                      </div>

                      <FileUploadPrimitive.ItemDeleteTrigger>✕</FileUploadPrimitive.ItemDeleteTrigger>
                    </FileUploadPrimitive.Item>
                  )
                })}
              </FileUploadPrimitive.ItemGroup>

              <FileUploadPrimitive.HiddenInput />
            </>
          )
        }}
      </FileUploadPrimitive.Context>
    </FileUploadPrimitive.Root>
  )
}
```

### api/slingshot/avatar/[action]/route.ts
```ts
import { createSlingshotServer } from '@saas-js/slingshot'
import { s3 } from '@saas-js/slingshot-adapter-s3'
import { handle } from '@saas-js/slingshot/next'

const slingshot = createSlingshotServer({
  profile: 'avatar',
  maxSizeBytes: 1024 * 1024 * 5, // 5MB
  allowedFileTypes: 'image/*',
  authorize: ({ req, file, meta }) => {
    console.log('authorizing', req.headers.get('Authorization'), file, meta)
  },
  key: ({ file, meta }) => {
    return `users/${meta?.userId}/avatar`
  },
  adapter: s3({
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    },
    region: process.env.AWS_REGION,
    bucket: process.env.AWS_BUCKET,
  }),
})

export const POST = handle(slingshot)
```
```

--------------------------------

### Update Contact - Client and Server Components

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/api-procedures/contacts

Provides examples for updating an existing contact. It demonstrates the use of `useMutation` for client-side updates and direct async calls for server-side updates. The specific fields for updating are not detailed in the provided snippet.

```javascript
// Client components
const { data } = api.contacts.update.useMutation()

// Server components
const data = await api.contacts.update()
```

--------------------------------

### Get Contact by ID - Client and Server Components

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/api-procedures/contacts

Demonstrates how to fetch a contact by their ID on both client and server-side using the TanStack Start kit's API. It shows the use of `useQuery` for client components and direct async calls for server components. Both methods require `id` and `workspaceId` as input.

```javascript
// Client components
const { data } = api.contacts.byId.useQuery({
  id: '',
  workspaceId: '',
})

// Server components
const data = await api.contacts.byId({
  id: '',
  workspaceId: '',
})
```

--------------------------------

### Install Better Auth React Query

Source: https://www.saas-js.com/docs/better-auth-react-query

Instructions for installing the better-auth-react-query package using npm, yarn, or pnpm. Ensure you have the required versions of @tanstack/react-query and better-auth installed.

```bash
npm install better-auth-react-query
# or
yarn add better-auth-react-query
# or
pnpm add better-auth-react-query
```

--------------------------------

### Prefetching Data with useSuspenseQuery Hook

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/api/calling-procedures

Illustrates the use of `useSuspenseQuery` for prefetching data in client components, ensuring data is always defined and simplifying conditional rendering. It's recommended to call this as early as possible, for instance, in page or layout routes. This example shows prefetching workspace data.

```typescript
// for example in a page or layout route
import { Outlet, createFileRoute, notFound } from '@tanstack/react-router'

import { WorkspaceNotFound } from '#features/workspaces/workspace.not-found'

export const Route = createFileRoute('/_app/$workspace')({
  beforeLoad: async ({ params, context }) => {
    const workspace = await context.trpc.workspaces.bySlug.ensureData({
      slug: params?.workspace,
    })

    if (!workspace) {
      throw notFound()
    }

    return { workspace }
  },
  notFoundComponent: WorkspaceNotFound,
  component: RouteComponent,
})

function RouteComponent() {
  return <Outlet />
}
```

```typescript
import { api } from '#lib/trpc/react'

export function WorkspacePage(props: { slug: string }) {
  const [data] = api.workspaces.bySlug.useSuspenseQuery({
    slug: props.slug,
  })

  return <div>{data.name}</div>
}
```

--------------------------------

### Using Different Config Files with Iconx CLI

Source: https://www.saas-js.com/docs/iconx/reference/configuration

These command examples demonstrate how to specify different configuration files for development and production when adding icons using the Iconx CLI.

```bash
# Development
icons add --config icons.dev.json home user

# Production
icons add --config icons.prod.json home user
```

--------------------------------

### Iconx CLI Feature-based Icon Addition Examples

Source: https://www.saas-js.com/docs/iconx/reference/cli

Illustrates how to add icons relevant to specific features like authentication, navigation, or general actions.

```bash
# Authentication icons
iconx add --set lucide log-in log-out user-plus user-minus

# Navigation icons
iconx add --set lucide home dashboard settings help

# Action icons
iconx add --set lucide plus minus edit trash save
```

--------------------------------

### Start Iconx MCP Server

Source: https://www.saas-js.com/docs/iconx/reference/cli

Starts the MCP (Model Context Protocol) server, which enables AI-assisted icon management features such as icon search, automated addition, and configuration management.

```bash
iconx mcp
```

--------------------------------

### Auth Router API

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/api-procedures/auth

Provides procedures for authentication, including fetching the current user and their associated workspaces.

```APIDOC
## GET /api/auth/me

### Description
Returns the current logged-in user and the workspaces they have access to.

### Method
GET

### Endpoint
/api/auth/me

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (object) - An object containing user information and their workspaces.
  - **user** (object) - User details.
  - **workspaces** (array) - List of workspaces the user has access to.

#### Response Example
```json
{
  "user": {
    "id": "user-123",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "workspaces": [
    {
      "id": "workspace-abc",
      "name": "My SaaS Project"
    }
  ]
}
```
```

--------------------------------

### Initialize Iconx Configuration

Source: https://www.saas-js.com/docs/iconx

Initializes the configuration file for Iconx. This command sets up the necessary files to start using Iconx in your project.

```bash
npx iconx init
```

--------------------------------

### Environment Variable Example (.env)

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/configuration/environment-variables

An example `.env` file demonstrating common environment variables used in the TanStack Router starter kit, including application URL, default plan ID, email settings, database connection, authentication secrets, and Stripe keys. These variables are crucial for configuring the application's behavior and integrations.

```env
# The public URL of the application
APP_URL=http://localhost:3000

# Default plan id for new accounts.
# Plans are configured in `packages/config/billing.config.ts`.
DEFAULT_PLAN_ID=free@1

# Email
# The email address that will be used to send emails from the application.
# This domain must be verified in your email provider.
EMAIL_FROM="hello@saas-ui.dev"

# Resend (default email provider)
# You can find this value in your Resend project settings.
RESEND_API_KEY=

# Database
# Uses a local docker instance by default.
DATABASE_URL=postgres://admin:admin@localhost:5432/dev

# Better Auth
AUTH_SECRET=

# Stripe (default payment provider)
# You can find these values in your Stripe dashboard, under developer settings.
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

```

--------------------------------

### Navigation Menu Example with Icons

Source: https://www.saas-js.com/docs/iconx/getting-started/basic-usage

A React component example demonstrating a sidebar navigation menu using generated icon components. Icons are imported from a central location and used alongside text links to provide visual cues for navigation items.

```jsx
import {
  HomeIcon,
  LogOutIcon,
  SettingsIcon,
  UserIcon,
} from './components/icons'

function Sidebar() {
  return (
    <aside className="w-64 bg-gray-100">
      <nav className="p-4 space-y-2">
        <a
          href="/dashboard"
          className="flex items-center gap-3 p-2 rounded hover:bg-gray-200"
        >
          <HomeIcon size="20px" />
          Dashboard
        </a>
        <a
          href="/profile"
          className="flex items-center gap-3 p-2 rounded hover:bg-gray-200"
        >
          <UserIcon size="20px" />
          Profile
        </a>
        <a
          href="/settings"
          className="flex items-center gap-3 p-2 rounded hover:bg-gray-200"
        >
          <SettingsIcon size="20px" />
          Settings
        </a>
        <button className="flex items-center gap-3 p-2 rounded hover:bg-gray-200 w-full text-left">
          <LogOutIcon size="20px" />
          Logout
        </button>
      </nav>
    </aside>
  )
}
```

--------------------------------

### Common Usage Patterns

Source: https://www.saas-js.com/docs/iconx/reference/cli

Illustrates common ways to use the Iconx CLI for project setup, feature-based icon addition, and working with multiple icon sets.

```APIDOC
## Common Usage Patterns

### Project Setup

```
# Initialize new project
iconx init

# Add common icons
iconx add --set lucide home user settings mail search
```

### Feature-based Icon Addition

```
# Authentication icons
iconx add --set lucide log-in log-out user-plus user-minus

# Navigation icons
iconx add --set lucide home dashboard settings help

# Action icons
iconx add --set lucide plus minus edit trash save
```

### Working with Multiple Icon Sets

```
# Lucide icons for general UI
iconx add --set lucide home user settings

# Heroicons for specific components
iconx add --set heroicons academic-cap beaker

# Font Awesome for brand icons
iconx add --set fa-brands github twitter linkedin
```
```

--------------------------------

### Install Montserrat Font - CLI

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/theming/fonts

Installs the variable version of the Montserrat font using pnpm. This method is preferred for reducing download size compared to including specific font versions.

```bash
cd apps/web && pnpm add @fontsource-variable/montserrat
```

--------------------------------

### Basic Drizzle CRUD Setup with TypeScript and Zod

Source: https://www.saas-js.com/docs/drizzle-crud/getting-started/installation

Demonstrates the basic setup for Drizzle CRUD in a TypeScript project. It imports necessary modules, initializes the Drizzle ORM database connection, and creates a CRUD factory with optional Zod validation. Requires Drizzle ORM and Zod v4.

```typescript
import { drizzleCrud } from 'drizzle-crud'
import { zod } from 'drizzle-crud/zod'
import { drizzle } from 'drizzle-orm/postgres-js'

// Initialize your database connection
const db = drizzle(/* your database connection */)

// Create the CRUD factory
const createCrud = drizzleCrud(db, {
  validation: zod(), // Optional: Add validation
})
```

--------------------------------

### Initialize Environment Variables

Source: https://www.saas-js.com/docs/starter-kits/nextjs/installation/run-application

Generates a new `.env` file and creates a symlink to `apps/web/.env` for environment configuration. Alternatively, you can copy `.env.example` to `.env` and manually fill in the values.

```shell
pnpm init:env
cp .env.example .env
# MacOS/Linux
ln -s apps/web/.env .env

# Windows
mklink apps/web/.env .env
```

--------------------------------

### Install Drizzle CRUD with pnpm

Source: https://www.saas-js.com/docs/drizzle-crud/getting-started/installation

Installs the Drizzle CRUD package using the pnpm package manager. Ensure you have Node.js and pnpm installed.

```bash
pnpm add drizzle-crud
```

--------------------------------

### Install Drizzle CRUD with yarn

Source: https://www.saas-js.com/docs/drizzle-crud/getting-started/installation

Installs the Drizzle CRUD package using the yarn package manager. Ensure you have Node.js and yarn installed.

```bash
yarn add drizzle-crud
```

--------------------------------

### Install Drizzle CRUD with npm

Source: https://www.saas-js.com/docs/drizzle-crud/getting-started/installation

Installs the Drizzle CRUD package using the npm package manager. Ensure you have Node.js and npm installed.

```bash
npm install drizzle-crud
```

--------------------------------

### Open Database Studio (pnpm)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Opens the database studio to interact with the database using pnpm. This provides a GUI for database management.

```bash
pnpm db:studio
```

--------------------------------

### Database Migrations and Seeding

Source: https://www.saas-js.com/docs/starter-kits/nextjs/installation/run-application

Generates initial database migration files and applies them to the database. Optionally, seeds the database with test data.

```shell
pnpm db:generate
pnpm db:migrate

# Optional seeding
pnpm db:seed
```

--------------------------------

### Start Drizzle Studio CLI Command

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/database/studio

This command starts the Drizzle Studio application, allowing you to explore and modify your database. Ensure you have Yarn installed and the project dependencies are set up.

```shell
yarn db:studio
```

--------------------------------

### Clone Saas UI Git Repository

Source: https://www.saas-js.com/docs/starter-kits/nextjs/installation/clone-repository

Clones the Saas UI Pro Next.js starter kit repository to your local machine. This command specifically clones the 'v3' branch and omits commit history to keep the repository lean. It's a prerequisite for setting up your project.

```bash
git clone --single-branch --branch=v3 git@github.com:saas-js/saas-ui-pro-nextjs-starter-kit.git my-project
```

--------------------------------

### Use Better Auth Mutations with React Query

Source: https://www.saas-js.com/docs/better-auth-react-query

Demonstrates how to use Better Auth methods (other than 'get' or 'list') as TanStack Query mutations. It includes an example of a sign-in form using `useMutation` and `mutationOptions()`.

```typescript
import { useMutation } from '@tanstack/react-query';

function SignInForm() {
  const signIn = useMutation(auth.signIn.email.mutationOptions());

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);

    signIn.mutate({
      email: formData.get('email') as string,
      password: formData.get('password') as string,
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" />
      <input name="password" type="password" />
      <button type="submit" disabled={signIn.isPending}>
        Sign In
      </button>
    </form>
  );
}
```

--------------------------------

### Multi-Tenant Drizzle CRUD Setup

Source: https://www.saas-js.com/docs/drizzle-crud/advanced/access-control

A comprehensive example for a multi-tenant SaaS application, demonstrating schema definition with tenant isolation, actor definitions, and Drizzle CRUD configuration with role-based scope filters for workspace and author access.

```typescript
// Schema with tenant isolation
const documents = pgTable('documents', {
  id: serial('id').primaryKey(),
  title: text('title').notNull(),
  content: text('content'),
  authorId: text('author_id').notNull(),
  workspaceId: text('workspace_id').notNull(),
  isPublic: boolean('is_public').default(false),
  deletedAt: timestamp('deleted_at'),
})

// Actor definition
interface UserActor extends Actor {
  type: 'user'
  properties: {
    userId: string
    workspaceId: string
    role: 'owner' | 'admin' | 'member' | 'viewer'
  }
}

// CRUD with access control
const documentsCrud = createCrud(documents, {
  scopeFilters: {
    // Workspace isolation - always applied
    workspaceId: (value, actor: UserActor) =>
      eq(documents.workspaceId, actor.properties.workspaceId),

    // Author access - only see own documents unless admin+
    authorId: (value, actor: UserActor) => {
      const { role } = actor.properties
      if (role === 'owner' || role === 'admin') {
        return undefined // Can see all documents
      }
      return eq(documents.authorId, actor.properties.userId)
    },

    // Public documents - viewers can only see public ones
    isPublic: (value, actor: UserActor) => {
      if (actor.properties.role === 'viewer') {
        return eq(documents.isPublic, true)
      }
      return undefined // Others can see all
    },
  },
})

// Usage
const memberActor: UserActor = {
  type: 'user',
  properties: {
    userId: 'user-123',
    workspaceId: 'workspace-456',
    role: 'member',
  },
}

// This will only return documents from workspace-456
// that were created by user-123
const myDocuments = await documentsCrud.list({}, {
  actor: memberActor,
  scope: {
    workspaceId: 'workspace-456',
    authorId: 'user-123',
  },
})
```

--------------------------------

### Build Production Web App (pnpm)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Builds the production-ready web application using pnpm. This command generates optimized assets for deployment.

```bash
pnpm build:web
```

--------------------------------

### Get Workspace by Slug (SaaS-JS Workspaces Router)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/api-procedures/workspaces

Procedure to retrieve workspace details, including subscription, members, and tags, based on its slug. Requires member access. Examples show client-side query and server-side invocation.

```javascript
// Client components
const { data } = useQuery(trpc.workspaces.get.queryOptions({ slug: 'my-workspace' }))

// Server components
const data = await caller.workspaces.get({ slug: 'my-workspace' })
```

--------------------------------

### Get current user using Auth router

Source: https://www.saas-js.com/docs/starter-kits/nextjs/api-procedures/auth

Retrieves the currently logged-in user and their associated workspaces. This procedure is protected and requires authentication. Examples are provided for both client-side (using `useQuery`) and server-side (using `caller`) contexts.

```typescript
// Client components
const { data } = useQuery(trpc.auth.me.queryOptions())

// Server components
const data = await caller.auth.me()
```

--------------------------------

### Generate Database Migrations (pnpm)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Generates new database migration files using pnpm. This is a preparatory step before applying migrations.

```bash
pnpm db:generate
```

--------------------------------

### Get Notifications Inbox - Client and Server Components

Source: https://www.saas-js.com/docs/starter-kits/nextjs/api-procedures/notifications

This procedure retrieves all notifications for the current user. It demonstrates usage in both client components using `useQuery` and server components with `await caller`. No specific dependencies are mentioned beyond the tRPC setup.

```typescript
const { data } = useQuery(trpc.notifications.inbox.queryOptions())
```

```typescript
const data = await caller.notifications.inbox()
```

--------------------------------

### Client-side Mutation with useMutation Hook

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/api/calling-procedures

Shows how to perform mutations, such as updating a user profile, using the `useMutation` hook. It includes an example of invalidating and refetching cached data upon mutation settlement using `utils.users.invalidate()`. This hook is essential for data modification operations on the client.

```typescript
import { api } from '#lib/trpc/react'

export default function ProfilePage() {
  const { user } = useAuth()

  const utils = api.useUtils()

  const mutation = api.users.updateProfile.useMutation({
    onSettled: () => {
      // Invalidate the user cache, so the updated user is refetched
      utils.users.invalidate()
    },
  })

  return (
    <button
      onClick={() => {
        mutation.mutate({
          name: 'John Doe',
        })
      }}
    >
      Save
    </button>
  )
}
```

--------------------------------

### Write Code Formatting

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Applies code formatting to the project files. This command automatically adjusts code style according to defined rules.

```bash
format:write
```

--------------------------------

### Run Database Migrations (pnpm)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Applies pending database migrations to the database using pnpm. This command updates the database schema.

```bash
pnpm db:migrate
```

--------------------------------

### Seed Database with Test Data (pnpm)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Seeds the database with test data using pnpm. This is useful for development and testing purposes.

```bash
pnpm db:seed
```

--------------------------------

### Install iconx Package with Package Managers

Source: https://www.saas-js.com/docs/iconx/getting-started/installation

Installs the iconx package using common package managers like npm, yarn, pnpm, and bun. Ensure you have the respective package manager installed on your system.

```shell
# Using npm
npm install iconx

# Using yarn
yarn add iconx

# Using pnpm
pnpm add iconx

# Using bun
bun add iconx
```

--------------------------------

### Run Linter

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Runs the linter on the project code. The linter helps identify potential errors and code quality issues.

```bash
lint
```

--------------------------------

### Mount Slingshot Handlers for Upload Requests (Next.js Example)

Source: https://www.saas-js.com/docs/slingshot/getting-started/installation

Explains how to mount Slingshot handlers to manage upload requests. It requires creating a new route in your framework that starts with `/api/slingshot/` followed by the profile name, e.g., `/api/slingshot/avatar`. The Slingshot server is built on Hono and supports frameworks compatible with standard Request and Response objects.

```typescript
# Next.js
# Create a new route, for example, pages/api/slingshot/[profile].ts
# Then, export the Slingshot server handler:
# export { handler as GET, handler as POST } from "@saas-js/slingshot";
# This setup assumes your slingshot server is correctly configured in lib/slingshot/avatar.ts
```

--------------------------------

### Using Project-Specific Icon Sets with Iconx CLI

Source: https://www.saas-js.com/docs/iconx/reference/configuration

These command examples show how to add icons using the default icon set and how to specify a different icon set (e.g., 'fa-brands') for specific icons.

```bash
# UI icons (using default lucide)
icons add home user settings

# Brand icons (using fa-brands)
icons add --set fa-brands github twitter linkedin
```

--------------------------------

### Install Slingshot Package

Source: https://www.saas-js.com/docs/slingshot/getting-started/installation

Installs the necessary Slingshot packages using npm. This is the first step to integrate Slingshot into your project.

```bash
npm install @saas-js/slingshot @saas-js/slingshot-react
```

--------------------------------

### Build Storybook for Production (pnpm)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Builds the Storybook for production deployment using pnpm. This command generates static Storybook files.

```bash
pnpm build:storybook
```

--------------------------------

### Tips and Best Practices

Source: https://www.saas-js.com/docs/iconx/reference/cli

Provides recommendations for using the Iconx CLI effectively, including consistent icon set usage, batch addition, aliases, and output directory organization.

```APIDOC
## Tips and Best Practices

### 1. Use Consistent Icon Sets

```
# Good: Stick to one primary icon set
iconx add --set lucide home user settings mail

# Avoid: Mixing different styles
iconx add --set lucide home
iconx add --set heroicons user  # Different style
```

### 2. Batch Icon Addition

```
# Good: Add related icons together
iconx add --set lucide home user settings mail search edit trash plus minus

# Less efficient: Add icons one by one
iconx add --set lucide home
iconx add --set lucide user
iconx add --set lucide settings
```

### 3. Use Aliases for Better Names

Set up aliases in your `icons.json`:

```json
{
  "aliases": {
    "house": "home",
    "cog": "settings",
    "envelope": "mail"
  }
}
```

Then use the original names:

```
iconx add house cog envelope
```

### 4. Organize Output Directory

```
# Feature-based organization
iconx add --set lucide --outdir ./src/icons/navigation home dashboard
iconx add --set lucide --outdir ./src/icons/actions plus minus edit trash
```
```

--------------------------------

### Create Contact - Client and Server Components

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/api-procedures/contacts

Shows the procedure for creating a new contact within a workspace. The client-side implementation uses `useMutation` to trigger the creation, while the server-side uses a direct async call. No specific input parameters are shown for the mutation itself.

```javascript
// Client components
const { data } = api.contacts.create.useMutation()

// Server components
const data = await api.contacts.create()
```

--------------------------------

### Example Environment Variables

Source: https://www.saas-js.com/docs/starter-kits/nextjs/configuration/environment-variables

A list of common environment variables used in the Saas UI Next.js starter kit, including application URL, database credentials, email settings, and API keys for services like Resend and Stripe.

```env
# The public URL of the application
APP_URL=http://localhost:3000

# Default plan id for new accounts.
# Plans are configured in `packages/config/billing.config.ts`.
DEFAULT_PLAN_ID=free@1

# Email
# The email address that will be used to send emails from the application.
# This domain must be verified in your email provider.
EMAIL_FROM="hello@saas-ui.dev"

# Resend (default email provider)
# You can find this value in your Resend project settings.
RESEND_API_KEY=

# Database
# Uses a local docker instance by default.
DATABASE_URL=postgres://admin:admin@localhost:5432/dev

# Better Auth
AUTH_SECRET=

# Stripe (default payment provider)
# You can find these values in your Stripe dashboard, under developer settings.
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
```

--------------------------------

### Sync Billing Configuration (pnpm)

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Syncs the billing configuration into the database using pnpm. This command is related to the project's billing features.

```bash
pnpm billing:sync
```

--------------------------------

### Install Montserrat using Font Source

Source: https://www.saas-js.com/docs/starter-kits/nextjs/theming/fonts

This snippet shows how to install the Montserrat font using the @fontsource-variable/montserrat package and import it into your root layout. It's a method to easily add variable fonts to your project.

```bash
cd apps/web && pnpm install @fontsource-variable/montserrat
```

--------------------------------

### Push Database Schema Changes (Prototyping)

Source: https://www.saas-js.com/docs/starter-kits/tanstack-start/database/migrations

This command directly pushes schema changes to the database, useful for rapid local development prototyping. **Caution**: Do not use this on production databases unless your provider manages migrations, like Neon.

```bash
yarn db:push
```

--------------------------------

### Check Code Formatting

Source: https://www.saas-js.com/docs/starter-kits/nextjs/commands

Checks the code formatting across the project. This command verifies adherence to code style guidelines without making changes.

```bash
format:check
```

--------------------------------

### Filter Example: Users by Role in Specific Departments with OR in Drizzle CRUD

Source: https://www.saas-js.com/docs/drizzle-crud/advanced/filtering

An example of filtering users by a specific department and having one of several roles within that department using a combination of a direct filter and an OR condition.

```javascript
const engineeringTeam = await userCrud.list({
  filters: {
    department: 'engineering',
    OR: [
      { role: 'developer' },
      { role: 'senior-developer' },
      { role: 'tech-lead' },
    ],
  },
})
```

--------------------------------

### Filter Example: Active Users Created This Year in Drizzle CRUD

Source: https://www.saas-js.com/docs/drizzle-crud/advanced/filtering

A practical example demonstrating how to filter for active users created within the current year using 'isActive' and a date range filter on 'createdAt'.

```javascript
const activeUsers = await userCrud.list({
  filters: {
    isActive: true,
    createdAt: {
      gte: new Date('2024-01-01'),
    },
  },
})
```

--------------------------------

### Configure Slingshot Storage Adapter (AWS S3 Example)

Source: https://www.saas-js.com/docs/slingshot/getting-started/installation

Demonstrates how to configure an adapter to connect Slingshot to a storage provider. This example shows adding an AWS S3 adapter to the slingshot profile configuration file (`lib/slingshot/avatar.ts`).

```typescript
# Assuming you have @saas-js/storage-aws-s3 installed
# import { S3Adapter } from '@saas-js/storage-aws-s3'
# import { createSlingshotServer } from '@saas-js/slingshot'

# export const slingshot = createSlingshotServer({
#   profile: 'avatar',
#   maxSizeBytes: 1024 * 1024 * 5, // 5MB
#   allowedFileTypes: 'image/*',
#   key: ({ file }) => {
#     return `avatars/${file.name}`
#   },
#   adapter: S3Adapter({
#     bucket: process.env.AWS_S3_BUCKET as string,
#     region: process.env.AWS_S3_REGION as string,
#     credentials: {
#       accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
#       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
#     },
#   }),
# })
```

--------------------------------

### Icon Buttons Example

Source: https://www.saas-js.com/docs/iconx/getting-started/basic-usage

A React component example showcasing how to create icon buttons using generated icon components. These buttons are typically used for actions like adding, editing, or deleting items, and are styled with background colors and hover effects.

```jsx
import { EditIcon, PlusIcon, TrashIcon } from './components/icons'

function ActionButtons() {
  return (
    <div className="flex gap-2">
      <button className="p-2 bg-blue-500 text-white rounded hover:bg-blue-600">
        <PlusIcon size="16px" />
      </button>
      <button className="p-2 bg-gray-500 text-white rounded hover:bg-gray-600">
        <EditIcon size="16px" />
      </button>
      <button className="p-2 bg-red-500 text-white rounded hover:bg-red-600">
        <TrashIcon size="16px" />
      </button>
    </div>
  )
}
```

--------------------------------

### Consistent Naming with Iconx (CLI)

Source: https://www.saas-js.com/docs/iconx/getting-started/basic-usage

Maintain consistent icon naming across different icon sets for better maintainability. This example shows how to add icons with consistent names, highlighting the importance of using the same naming convention (e.g., 'home', 'user') even if underlying icon names differ slightly between sets.

```bash
# Good: Use consistent icon names across sets
npx iconx add --set lucide home user settings
npx iconx add --set heroicons home user cog  # 'cog' instead of 'settings'
```

--------------------------------

### Status Indicators with Icons Example

Source: https://www.saas-js.com/docs/iconx/getting-started/basic-usage

A React component example for displaying status messages with corresponding icons. It dynamically selects an icon and color based on the status type (success, error, warning), providing a clear visual indication of the message's context.

```jsx
import {
  AlertCircleIcon,
  CheckCircleIcon,
  XCircleIcon,
} from './components/icons'

function StatusMessage({ type, message }) {
  const configs = {
    success: { icon: CheckCircleIcon, color: 'text-green-500' },
    error: { icon: XCircleIcon, color: 'text-red-500' },
    warning: { icon: AlertCircleIcon, color: 'text-yellow-500' },
  }

  const { icon: Icon, color } = configs[type]

  return (
    <div className="flex items-center gap-2">
      <Icon size="20px" className={color} />
      <span>{message}</span>
    </div>
  )
}
```

--------------------------------

### Initialize Iconx Configuration

Source: https://www.saas-js.com/docs/iconx/getting-started/basic-usage

Initializes your project with a configuration file named `icons.json`. This file stores default settings for Iconx. The default configuration includes output directory, default icon set, icon size, and aliases.

```bash
icons init
```

--------------------------------

### Keep Transactions Short (Good vs. Avoid)

Source: https://www.saas-js.com/docs/drizzle-crud/advanced/transactions

Illustrates the importance of keeping database transactions brief. The 'Good' example shows a short transaction involving user creation and audit logging. The 'Avoid' example highlights a common pitfall: performing long-running, external operations (like sending emails or generating reports) within a transaction, which can block resources and lead to performance issues.

```javascript
// Good: Short transaction
const quickTransaction = async () => {
  return await db.transaction(async (tx) => {
    const user = await userCrud.create(userData, { db: tx })
    await auditCrud.create(auditData, { db: tx })
    return user
  })
}

// Avoid: Long-running transaction
const longTransaction = async () => {
  return await db.transaction(async (tx) => {
    const user = await userCrud.create(userData, { db: tx })
    
    // Don't do heavy processing in transactions
    await sendEmailsToAllUsers() // This takes too long
    await generateReports() // This takes too long
    
    return user
  })
}
```