### Run Shelf.nu App Setup and Development Commands

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/supabase-setup.md

Execute these commands to set up and start your Shelf.nu web application for development. The app will be accessible at http://localhost:3000 or https://localhost:3000.

```bash
pnpm webapp:setup
pnpm webapp:dev
```

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

### Setup Prisma Client and Migrations

Source: https://github.com/shelf-nu/shelf.nu/blob/main/README.md

Generates the Prisma client and applies database migrations. This command is essential after installing dependencies and configuring the .env file.

```bash
pnpm webapp:setup
```

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

### Start Documentation Site

Source: https://github.com/shelf-nu/shelf.nu/blob/main/README.md

Starts the development server for the documentation site.

```bash
pnpm docs:dev
```

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

### Clone, Install, and Set Up Local HTTPS

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

Commands to clone the repository, install dependencies, and set up local HTTPS for development. Ensure mkcert is installed for local HTTPS certificate generation.

```bash
git clone https://github.com/Shelf-nu/shelf.nu.git
cd shelf.nu
pnpm install

mkcert -install
mkdir apps/webapp/.cert
mkcert -key-file apps/webapp/.cert/key.pem -cert-file apps/webapp/.cert/cert.pem localhost 127.0.0.1 ::1
```

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

### Start Production Server Locally

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Start the production server locally using the `webapp:start` script. This command loads environment variables from the root `.env` file.

```bash
pnpm webapp:start
```

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

### Copy Environment Example and Initialize Database

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

Instructions to copy the example environment file and initialize the database, which includes generating the Prisma client and deploying migrations.

```bash
cp .env.example .env
pnpm webapp:setup
```

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

### Clone Repository and Install Dependencies

Source: https://github.com/shelf-nu/shelf.nu/blob/main/README.md

Clones the Shelf.nu repository and installs project dependencies using pnpm. This is the initial setup for running the project locally.

```bash
git clone https://github.com/Shelf-nu/shelf.nu.git
cd shelf.nu
pnpm install
cp .env.example .env
```

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

### Start Development Server

Source: https://github.com/shelf-nu/shelf.nu/blob/main/README.md

Use this command to start the local development server. It runs with HTTPS enabled by default using local certificates.

```bash
pnpm webapp:dev
```

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

### Install Project Dependencies

Source: https://github.com/shelf-nu/shelf.nu/blob/main/README.md

Installs all necessary project dependencies using pnpm. Ensure Node.js and pnpm are installed and configured.

```bash
pnpm install
```

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

### Database Management Commands

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Use these commands for initial database setup, creating and deploying migrations, and resetting the database.

```bash
pnpm webapp:setup               # Initial database setup
```

```bash
pnpm db:prepare-migration # Create new migration
```

```bash
pnpm db:deploy-migration  # Apply migrations and regenerate client
```

```bash
pnpm db:reset            # Reset database (careful!)
```

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

### Start Production Server Locally (Webapp Directory)

Source: https://github.com/shelf-nu/shelf.nu/blob/main/CLAUDE.md

Used by Docker/Fly for starting the production server within the webapp's directory. It relies on environment variables provided by the platform.

```bash
pnpm run start
```

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

### Start Development Server and Run Validations

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

Commands to start the development server for the web application and run quality checks. The development server typically runs on https://localhost:3000.

```bash
pnpm webapp:dev
pnpm webapp:validate
```

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

### Self-hosted SSO Configuration

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

This section outlines the configuration for enabling SAML 2.0 SSO in self-hosted Shelf.nu instances via Supabase. It references Supabase documentation for detailed setup and provides an example attribute mapping file.

```bash
# Self-hosted: enable SAML SSO in Supabase
# See: https://supabase.com/docs/guides/auth/enterprise-sso/auth-sso-saml

# Attribute mapping file for IdP setup
# File: ./sso/attributes.json (in project root)
```

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

### Install Fly CLI (Windows)

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/deployment.md

Installs the Fly.io CLI on Windows systems using PowerShell.

```powershell
powershell -Command "iwr https://fly.io/install.ps1 -useb | iex"
```

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

### Install mkcert for Local SSL

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Instructions for installing mkcert on macOS, Ubuntu/Debian, and Windows. mkcert is used to generate local SSL certificates for HTTPS development.

```bash
# macOS
brew install mkcert

# Ubuntu/Debian
sudo apt install libnss3-tools
wget -O mkcert https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64
chmod +x mkcert
sudo mv mkcert /usr/local/bin/

# Windows (using Chocolatey)
choco install mkcert
```

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

### Environment Variables for Configuration

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/app-configuration.md

Example of how to set environment variables in a `.env` file to override default configuration settings in Shelf.nu.

```bash
# .env file
SEND_ONBOARDING_EMAIL=true
ENABLE_PREMIUM_FEATURES=false
FREE_TRIAL_DAYS=14
DISABLE_SIGNUP=false
DISABLE_SSO=false
COLLECT_BUSINESS_INTEL=true
# SHOW_HOW_DID_YOU_FIND_US=true  # Deprecated, use COLLECT_BUSINESS_INTEL instead
```

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

### Vitest Configuration Example

Source: https://github.com/shelf-nu/shelf.nu/blob/main/AGENTS.md

Example of how path aliases are configured in `vitest.config.ts` for easier imports. These aliases map to specific directories within the monorepo.

```typescript
import { createUser } from "@factories"; // → apps/webapp/test/factories/index.ts
import { createRemixMocks } from "@mocks/remix"; // → apps/webapp/test/mocks/remix.tsx
```

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

### Install Fly CLI (macOS/Linux)

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/deployment.md

Installs the Fly.io CLI on macOS and Linux systems using a curl script.

```bash
curl -L https://fly.io/install.sh | sh
```

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

### Fly.io Deployment: Basic Commands

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

This snippet covers essential commands for deploying and managing a Shelf.nu application on Fly.io, including installing the CLI, authentication, creating apps, deploying, and monitoring logs.

```bash
# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Authenticate
fly auth login

# Create apps
fly apps create shelf-webapp
fly apps create shelf-webapp-staging   # optional

# Deploy
fly deploy

# Monitor
fly logs -f           # follow logs
fly status            # app health
fly scale count 2     # run 2 instances
fly scale vm performance-1x
```

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

### Install and Run End-to-End Tests with Playwright

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Install necessary browser binaries for Playwright and then run end-to-end tests in development mode. E2E tests reside in the `tests/e2e/` directory.

```bash
pnpm --filter @shelf/webapp test:e2e:install  # Install browsers (first time)
pnpm --filter @shelf/webapp test:e2e:dev      # Run tests in development
```

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

### Supabase Storage Bucket Setup

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

Defines required storage buckets for Shelf and their access policies. Ensure correct public/private settings and policy expressions for security.

```bash
# Required storage buckets (create in Supabase Dashboard → Storage → Buckets)
# profile-pictures  → Public: YES
# assets            → Public: NO
# kits              → Public: NO
# files             → Public: YES

# All buckets need this INSERT/UPDATE/DELETE policy expression:
# (bucket_id = '<bucket-name>'::text) AND (false)
# Target roles: authenticated, anon
```

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

### Verify Fly CLI Installation

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/deployment.md

Checks if the Fly.io CLI is installed correctly by displaying its version.

```bash
fly version
```

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

### Complete .env File Configuration

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/supabase-setup.md

This is an example of a complete .env file for the Shelf.nu project, including database connections, Supabase API keys, session secrets, and optional integrations.

```env
# Database connections
DATABASE_URL="postgres://postgres.xxxxx:[YOUR-PASSWORD]@xxx.pooler.supabase.com:6543/postgres?pgbouncer=true"
DIRECT_URL="postgres://postgres.xxxxx:[YOUR-PASSWORD]@xxx.supabase.com:5432/postgres"

# Supabase API
SUPABASE_URL="https://your-project-ref.supabase.co"
SUPABASE_ANON_PUBLIC="your-anon-public-key"
SUPABASE_SERVICE_ROLE="your-service-role-key"

# App configuration
SESSION_SECRET="your-super-secret-session-key"
SERVER_URL="https://localhost:3000"  # With SSL (recommended)
# SERVER_URL="http://localhost:3000"  # Without SSL
FINGERPRINT="a-custom-host-fingerprint"

# Features (optional - set to false to disable premium features)
ENABLE_PREMIUM_FEATURES="false"

# Email configuration (required for auth emails)
SMTP_HOST="smtp.yourhost.com"
SMTP_PORT=465
SMTP_USER="you@example.com"
SMTP_PWD="yourSMTPpassword"
SMTP_FROM="You from Shelf.nu <you@example.com>"

# Map integration (optional)
MAPTILER_TOKEN="your-maptiler-token"
GEOCODING_USER_AGENT="Your App Name (https://yoursite.com)"

# Security
INVITE_TOKEN_SECRET="your-invite-token-secret"

# Analytics (optional)
MICROSOFT_CLARITY_ID="your-clarity-id"

```

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

### File and Function Documentation Example

Source: https://github.com/shelf-nu/shelf.nu/blob/main/CLAUDE.md

Illustrates comprehensive documentation practices including file-level JSDoc comments explaining purpose and relationships, and function-level JSDoc for parameters, return values, and potential errors.

```typescript
/**
 * User Note Service
 *
 * Handles CRUD operations for admin notes on user profiles.
 * Notes are workspace-scoped: a note in Workspace A is invisible in Workspace B.
 *
 * @see {@link file://./../../routes/_layout+/settings.team.users.$userId.note.tsx}
 */

/** Arguments for creating a user note */
type CreateUserNoteArgs = { ... };

/**
 * Creates a new note on a user's profile within a specific workspace.
 *
 * @param args - The note content, target user, organization, and optional author
 * @returns The created UserNote record
 * @throws {ShelfError} If the database operation fails
 */
export async function createUserNote(args: CreateUserNoteArgs) { ... }
```

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

### Complete Form Validation Example

Source: https://github.com/shelf-nu/shelf.nu/blob/main/CLAUDE.md

A full example demonstrating Zod schema definition, React component implementation using `useZorm`, and display of both server-side and client-side validation errors.

```typescript
// Schema definition
export const myFormSchema = z.object({
  name: z.string().min(1, "Name is required"),
  email: z.string().email("Invalid email"),
  date: z.coerce.date().min(new Date(), "Date must be in the future"),
});

// Component
export default function MyForm() {
  const zo = useZorm("MyForm", myFormSchema);

  const actionData = useActionData<DataOrErrorResponse>();
  const validationErrors = getValidationErrors<typeof myFormSchema>(
    actionData?.error
  );

  return (
    <Form method="POST">
      <Input
        name={zo.fields.name()}
        error={validationErrors?.name?.message || zo.errors.name()?.message}
        label="Name"
      />
      <Input
        name={zo.fields.email()}
        error={validationErrors?.email?.message || zo.errors.email()?.message}
        label="Email"
      />
      <Input
        type="datetime-local"
        name={zo.fields.date()}
        error={validationErrors?.date?.message || zo.errors.date()?.message}
        label="Date"
      />
      <Button type="submit">Submit</Button>
    </Form>
  );
}
```

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

### Run Unit and E2E Tests

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

Commands for running unit tests and end-to-end (E2E) tests for the web application. E2E tests may require an initial setup command.

```bash
pnpm webapp:test -- --run
pnpm --filter @shelf/webapp test:e2e:install   # first time only
pnpm --filter @shelf/webapp test:e2e:dev
```

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

### Get Application Information with Fly.io

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/deployment.md

Retrieve general information about your Fly.io application, including its configuration and status.

```bash
# App information
fly info
```

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

### Natural Sorting Example

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/advanced-index/natural-sorting-explanation.md

Demonstrates the correct, human-friendly ordering achieved through natural sorting, where numbers are interpreted numerically.

```text
Scanner 1
Scanner 2
Scanner 3
Scanner 4
Scanner 10
Scanner 11
```

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

### Database Query Example

Source: https://github.com/shelf-nu/shelf.nu/blob/main/CLAUDE.md

This pattern demonstrates a common database query using Prisma. Consider standardizing select fields, common where conditions, and performance optimization patterns.

```typescript
const data = await prisma.user.findMany({
    select: { id: true, email: true },
    where: { status: "ACTIVE" },
  });
```

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

### Environment Variables for Shelf.nu

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

Example `.env` file content for the monorepo root, detailing required and optional environment variables for database connection, Supabase API, email services, feature flags, and integrations.

```dotenv
# .env (monorepo root)

# Database (from Supabase → Connect → ORM → Prisma)
DATABASE_URL="postgres://postgres.xxxxx:[PASSWORD]@xxx.pooler.supabase.com:6543/postgres?pgbouncer=true"
DIRECT_URL="postgres://postgres.xxxxx:[PASSWORD]@xxx.supabase.com:5432/postgres"

# Supabase API
SUPABASE_URL="https://your-project-ref.supabase.co"
SUPABASE_ANON_PUBLIC="your-anon-public-key"
SUPABASE_SERVICE_ROLE="your-service-role-key"

# App
SESSION_SECRET="$(openssl rand -hex 32)"
FINGERPRINT="$(openssl rand -hex 32)"
INVITE_TOKEN_SECRET="$(openssl rand -hex 32)"
SERVER_URL="https://localhost:3000"

# Email (required for OTP auth)
SMTP_HOST="smtp.resend.com"
SMTP_PORT=587
SMTP_USER="resend"
SMTP_PWD="your-resend-api-key"
SMTP_FROM="Shelf.nu <noreply@yourdomain.com>"

# Feature flags
ENABLE_PREMIUM_FEATURES="false"
DISABLE_SIGNUP="false"
DISABLE_SSO="false"
FREE_TRIAL_DAYS=7
SEND_ONBOARDING_EMAIL="false"
COLLECT_BUSINESS_INTEL="false"

# Optional integrations
MAPTILER_TOKEN="your-maptiler-token"
GEOCODING_USER_AGENT="My Company Assets (https://assets.mycompany.com)"
URL_SHORTENER="eam.sh"           # short domain for QR codes (no protocol, no trailing slash)

# Analytics (all optional)
CLOUDFLARE_WEB_ANALYTICS_TOKEN="your-token"
MICROSOFT_CLARITY_ID="your-clarity-id"
CRISP_WEBSITE_ID="your-crisp-website-id"
SENTRY_DSN="https://your-key@sentry.io/your-project-id"
SENTRY_ORG="your-org"
SENTRY_PROJECT="your-project"

# Stripe (only when ENABLE_PREMIUM_FEATURES=true)
STRIPE_SECRET_KEY="sk_live_..."
STRIPE_PUBLIC_KEY="pk_live_..."
STRIPE_WEBHOOK_ENDPOINT_SECRET="whsec_..."

```

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

### Factory Usage Example

Source: https://github.com/shelf-nu/shelf.nu/blob/main/AGENTS.md

Demonstrates how to use a factory to build test data. The `build` method allows for overriding specific fields, ensuring flexibility in test data generation.

```typescript
import { userFactory } from "@factories/userFactory";

const testUser = userFactory.build({ role: "admin" });
```

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

### Build Shelf Desktop App for Windows

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/webapp/desktop-app/README.md

Run this command to build the desktop application for Windows.

```bash
npm run build:windows
```

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

### Create and Apply Database Migrations

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Commands to prepare a new database migration and then deploy it to apply changes.

```bash
pnpm db:prepare-migration
```

```bash
pnpm db:deploy-migration
```

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

### Install pnpm and Activate Version

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Install pnpm using corepack and activate a specific version. This is a prerequisite for managing monorepo dependencies.

```bash
corepack enable && corepack prepare pnpm@9.15.4 --activate
```

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

### Prepare and Deploy Database Migrations

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Commands to prepare a new database migration, review the generated SQL, and then apply it to your database.

```bash
# Prepare migration
pnpm db:prepare-migration

# Apply migration
pnpm db:deploy-migration
```

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

### Build Shelf Desktop App for macOS

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/webapp/desktop-app/README.md

Run this command to build the desktop application for macOS.

```bash
npm run build:mac
```

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

### Open Prisma Studio for Database Browsing

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Use this command to open a web interface for browsing and managing your database content during local development.

```bash
pnpm --filter @shelf/webapp exec prisma studio
```

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

### createAvailabilityLabels Factory Usage

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/scanner-drawer-development.md

Example of using the `createAvailabilityLabels` factory function with `assetLabelPresets.booking` to generate status labels.

```typescript
const labels = createAvailabilityLabels(assetLabelPresets.booking);
```

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

### Scale Application for Performance Issues

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/deployment.md

Address performance bottlenecks by scaling up your application's VM size or increasing the number of instances.

```bash
# Scale up your app
fly scale vm performance-1x

# Add more instances
fly scale count 2
```

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

### Screen Reader Commands for macOS VoiceOver

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/accessibility.md

Basic commands to start VoiceOver and navigate using keyboard shortcuts.

```bash
# Start VoiceOver
Cmd+F5

# Navigate
Ctrl+Option+Arrow keys
```

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

### Enable Onboarding Email Configuration

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/shelf.config.ts.md

Configures the `sendOnboardingEmail` flag. Set to `true` to enable sending onboarding emails to new users.

```typescript
//remix.config.ts
// Default
sendOnboardingEmail: true;
```

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

### Barcode Normalization and Validation Usage Examples

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/barcode-types-development-guide.md

Illustrates how to use the `normalizeBarcodeValue` and `validateBarcodeValue` functions before storing or validating barcode data.

```typescript
// Before storing in database
const normalizedValue = normalizeBarcodeValue(
  BarcodeType.YourNewType,
  userInput
);

// Before validation
const normalizedValue = normalizeBarcodeValue(type, value);
const validationError = validateBarcodeValue(type, normalizedValue);
```

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

### Prisma Studio Launch

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

Opens the Prisma Studio visual database browser for the specified package. Useful for inspecting and manipulating database data.

```bash
# Open visual database browser
pnpm --filter @shelf/webapp exec prisma studio
```

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

### Room Equipment Natural Sorting

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/advanced-index/natural-sorting-explanation.md

Provides an example of natural sorting applied to room equipment, handling both numbers and alphanumeric identifiers.

```text
OR Equipment 1
OR Equipment 2
OR Equipment 10
OR Equipment A1
OR Equipment A2
OR Equipment A10
```

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

### Build Docs for Production

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Build the VitePress documentation site for production. This command generates static assets for deployment.

```bash
pnpm docs:build
```

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

### Development Environment Variables

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

These variables are typically used for local development. Adjust them based on your SSL setup and database connection details.

```bash
# Development server (adjust based on SSL setup)
SERVER_URL="https://localhost:3000"  # With SSL
# SERVER_URL="http://localhost:3000"  # Without SSL

# Database (from Supabase)
DATABASE_URL="your-supabase-connection-string"
DIRECT_URL="your-supabase-direct-connection"

# Disable premium features for local development
ENABLE_PREMIUM_FEATURES="false"

# Session security
SESSION_SECRET="your-local-session-secret"
```

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

### Prisma Database Migration Preparation

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

Creates a new database migration file based on schema changes. This command is interactive and prompts for a migration name.

```bash
# Create a new migration (interactive, prompts for migration name)
pnpm db:prepare-migration
```

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

### Create PostgreSQL Trigger Function

Source: https://context7.com/shelf-nu/shelf.nu/llms.txt

Defines a PostgreSQL function that will be executed by a trigger. This example shows how to insert a record into a related table after an insert.

```sql
-- CreateFunction
CREATE OR REPLACE FUNCTION your_trigger_function()
RETURNS TRIGGER AS '
BEGIN
    -- Note: Use double single quotes ('''') to escape single quotes
    INSERT INTO "YourRelatedTable" (id, "userId")
    VALUES (generate_cuid(), NEW.id);
    RETURN NEW;
END;
' LANGUAGE plpgsql;
```

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

### Run Shelf.nu with Docker

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/docker.md

Use this command to run the shelf.nu Docker image. Ensure all environment variables are correctly set, especially database and Supabase credentials.

```bash
docker run -d \
  --name "shelf" \
  -e "DATABASE_URL=postgres://USER:PASSWORD@HOST:6543/DB_NAME?pgbouncer=true" \
  -e "DIRECT_URL=postgres://USER:PASSWORD@HOST:5432/DB_NAME" \
  -e 'SUPABASE_ANON_PUBLIC=your-anon-public-key' \
  -e 'SUPABASE_SERVICE_ROLE=your-service-role-key' \
  -e 'SUPABASE_URL=https://your-instance-name.supabase.co' \
  -e 'SESSION_SECRET=super-duper-s3cret' \
  -e 'SERVER_URL=http://localhost:3000' \
  -e 'MAPTILER_TOKEN=your-maptiler-token' \
  -e 'SMTP_HOST=mail.example.com' \
  -e 'SMTP_PORT=465' \
  -e 'SMTP_USER=some-email@example.com' \
  -e 'SMTP_FROM="Your Name from shelf.nu" <your-email@shelf.nu>' \
  -e 'SMTP_PWD=super-safe-passw0rd' \
  -e 'INVITE_TOKEN_SECRET=another-super-duper-s3cret' \
  -p 3000:8080 \
  --restart unless-stopped \
  ghcr.io/shelf-nu/shelf.nu:latest
```

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

### Example CSV Template with New Barcode Type

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/barcode-types-development-guide.md

Illustrates the CSV format including the new barcode type column for asset import.

```csv
title,description,barcode_Code128,barcode_Code39,barcode_DataMatrix,barcode_YourNewType
"Example Asset","Example description","","","",""
```

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

### Configure Supabase API Keys

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/supabase-setup.md

Add your Supabase project's URL and API keys to your .env file for client-side and server-side authentication.

```bash
SUPABASE_URL="https://your-project-ref.supabase.co"
SUPABASE_ANON_PUBLIC="your-anon-public-key"
SUPABASE_SERVICE_ROLE="your-service-role-key"
```

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

### Multi-Field Sorting Example

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/advanced-index/advanced-sorting-guide.md

Demonstrates multi-field sorting by Category, then Value, then Name. This is useful for grouping similar items and then ordering them by importance or value.

```text
Imaging Equipment (Category)
  └─ CT Scanner ($500,000)
  └─ MRI Scanner ($1,000,000)
  └─ X-Ray Machine ($200,000)

Patient Monitors (Category)
  └─ Advanced Monitor ($5,000)
  └─ Basic Monitor ($1,000)
  └─ Cardiac Monitor ($3,000)

Surgical Equipment (Category)
  └─ Anesthesia Machine ($50,000)
  └─ Basic Surgical Kit ($1,000)
  └─ Laser System ($75,000)
```

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

### Optimistic UI and NProgress Exclusion

Source: https://github.com/shelf-nu/shelf.nu/blob/main/CLAUDE.md

Example of how to exclude fetcher keys from the global loading bar when implementing optimistic UI to avoid double loading indicators.

```typescript
import NProgress from 'nprogress';
import { useEffect } from 'react';
import { useFetcher } from '@remix-run/react';

const excludeFetchers = [
  // Add fetcher keys here that should not trigger NProgress
  // e.g., 'optimistic-update-key'
];

export function useNProgress() {
  const fetcher = useFetcher();

  useEffect(() => {
    if (
      fetcher.state === 'loading' &&
      !excludeFetchers.includes(fetcher.key as string)
    ) {
      NProgress.start();
    } else if (fetcher.state === 'idle') {
      NProgress.done();
    }

    return () => {
      NProgress.done();
    };
  }, [fetcher.state, fetcher.key]);
}

```

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

### Deploy Application Manually with Fly.io

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/deployment.md

Use the `fly deploy` command for initial manual deployments. Specify a different app name for staging environments.

```bash
# Deploy to production
fly deploy

# Deploy to staging (specify app)
fly deploy --app shelf-webapp-staging
```

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

### Traditional ASCII Sorting Example

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/advanced-index/natural-sorting-explanation.md

Illustrates the typical ASCII sorting behavior where numbers are treated as characters, leading to incorrect ordering (e.g., '10' before '2').

```text
Scanner 1
Scanner 10
Scanner 11
Scanner 2
Scanner 3
Scanner 4
```

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

### Production Build Command

Source: https://github.com/shelf-nu/shelf.nu/blob/main/README.md

Executes the production build process for the application.

```bash
pnpm webapp:build
```

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

### Getting Server-Side Validation Errors

Source: https://github.com/shelf-nu/shelf.nu/blob/main/CLAUDE.md

Retrieve and process server-side validation errors from action data. This is crucial for displaying errors when client-side validation fails or is bypassed.

```typescript
// Inside your component
const actionData = useActionData<DataOrErrorResponse>();

/** This handles server side errors in case client side validation fails */
const validationErrors = getValidationErrors<typeof yourZodSchema>(
  actionData?.error
);
```

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

### Getting Validation Error Message

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/handling-errors.md

Extract specific field error messages from `additionalData` using `getValidationErrors`. This is useful for displaying targeted validation feedback on forms.

```typescript
const nameError = getValidationErrors<typeof MySchema>(actionData?.error).name
  ?.message;
```

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

### Configure Supabase Database Connection Strings

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/supabase-setup.md

Set these environment variables in your .env file for database connection pooling and direct connections. Replace [YOUR-PASSWORD] with your actual Supabase database password.

```bash
# Connection pooling (for app runtime)
DATABASE_URL="postgres://postgres.xxxxx:[YOUR-PASSWORD]@xxx.pooler.supabase.com:6543/postgres?pgbouncer=true"

# Direct connection (for migrations)
DIRECT_URL="postgres://postgres.xxxxx:[YOUR-PASSWORD]@xxx.supabase.com:5432/postgres"
```

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

### Run Test Command

Source: https://github.com/shelf-nu/shelf.nu/blob/main/superpowers/plans/2026-04-30-fix-booking-compliance-report.md

Command to execute the specific lateness test file using pnpm and Vitest. This is used to verify the test setup and initial failure.

```bash
pnpm webapp:test -- --run app/modules/booking/lateness.test.ts
```

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

### Build Local Docker Image with Buildx

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/docker.md

Build a local Docker image for shelf.nu using buildx, specifying platforms for cross-architecture compatibility. This is useful for development when Dockerfile changes are made.

```bash
docker buildx build \
   --platform linux/amd64,linux/arm64 \
   --tag shelf-local \
   --file apps/webapp/Dockerfile.image .

```

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

### Scale Application Instances and VM Size

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/deployment.md

Adjust the number of running instances or change the virtual machine size for your application to manage performance and cost.

```bash
fly scale count 2              # Run 2 instances
fly scale vm shared-cpu-1x     # Change VM size
```

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

### createBlockers Factory Usage

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/scanner-drawer-development.md

Example of how to use the `createBlockers` factory function. This function takes blocker configurations and an optional `onResolveAll` callback to manage blocker UI and logic.

```typescript
const [hasBlockers, Blockers] = createBlockers({
  blockerConfigs: [...],
  onResolveAll: () => { /* cleanup logic */ },
});
```

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

### Preview Docs Production Build

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/local-development.md

Preview the production build of the VitePress documentation site locally. This helps in verifying the final output before deployment.

```bash
pnpm docs:preview
```

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

### Troubleshoot Build Failures with Fly.io

Source: https://github.com/shelf-nu/shelf.nu/blob/main/apps/docs/deployment.md

Use `fly logs` to inspect build logs or `fly deploy --verbose` for more detailed output when encountering build issues.

```bash
# Check build logs
fly logs --app your-app-name

# Deploy with more verbose output
fly deploy --verbose
```