> ## Documentation Index
> Fetch the complete documentation index at: https://softmaple.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get Softmaple running locally in under 5 minutes

<iframe width="560" height="315" src="https://www.youtube.com/embed/G8sVu76uRgs" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

<Note>
  If the video doesn't display, you can also watch it on [哔哩哔哩](https://www.bilibili.com/video/BV1y3411v7f1?share_source=copy_web).
</Note>

## Prerequisites

Before you begin, make sure you have the following installed:

* Node.js 20+ (LTS recommended)
* pnpm 9.0+
* PostgreSQL (for database)
* Git

## Setup Instructions

<AccordionGroup>
  <Accordion icon="github" title="1. Clone the repository">
    Clone the Softmaple repository from GitHub:

    ```bash theme={null}
    git clone https://github.com/softmaple/softmaple.git
    cd softmaple
    ```
  </Accordion>

  <Accordion icon="package" title="2. Install dependencies">
    Install all dependencies using pnpm:

    ```bash theme={null}
    pnpm install
    ```

    This will install dependencies for all workspaces in the monorepo.
  </Accordion>

  <Accordion icon="gear" title="3. Set up environment variables">
    Copy the web and database environment files and configure them:

    ```bash theme={null}
    cp apps/web/.env.example apps/web/.env
    cp packages/db/.env.example packages/db/.env
    ```

    Edit `apps/web/.env` with your configuration:

    ```env theme={null}
    # Supabase Auth
    NEXT_PUBLIC_SUPABASE_URL="your-supabase-url"
    NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY="your-publishable-key"
    NEXT_PUBLIC_APP_URL="http://localhost:3000"
    ```

    Add the same database connection values to `packages/db/.env` so Prisma
    commands can connect when run from the database package:

    ```env theme={null}
    DATABASE_URL="postgresql://user:password@localhost:5432/softmaple"
    DIRECT_URL="postgresql://user:password@localhost:5432/softmaple"
    ```
  </Accordion>

  <Accordion icon="server" title="4. Configure collaboration">
    Create `apps/collab-nitro/.env.local` from its example, then provide
    `DATABASE_URL`, `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY`, and
    `COLLAB_ALLOWED_ORIGINS`. Local development defaults to the in-memory
    realtime adapter; Vercel deployments require `REDIS_URL`.

    ```bash theme={null}
    cp apps/collab-nitro/.env.example apps/collab-nitro/.env.local
    ```

    ```env theme={null}
    DATABASE_URL="postgresql://user:password@localhost:5432/softmaple"
    SUPABASE_URL="your-supabase-url"
    SUPABASE_PUBLISHABLE_KEY="your-publishable-key"
    COLLAB_ALLOWED_ORIGINS="http://localhost:3000"
    COLLAB_REALTIME_DRIVER="memory"
    ```
  </Accordion>

  <Accordion icon="database" title="5. Set up the database">
    Generate Prisma client and run migrations:

    ```bash theme={null}
    pnpm --filter @softmaple/db db:generate
    pnpm --filter @softmaple/db db:migrate
    ```
  </Accordion>

  <Accordion icon="rocket" title="6. Start the development servers">
    Stock `next dev` does not forward `/collab/*` WebSocket upgrades. For a
    working same-origin collaboration path locally, run the collab service,
    Next.js on an internal port, and the Upgrade-capable router on port 3000:

    ```bash Terminal 1 — collaboration service theme={null}
    pnpm --filter @softmaple/collab-nitro dev
    ```

    ```bash Terminal 2 — Next.js (internal) theme={null}
    pnpm --filter @softmaple/web exec next dev --port 3001
    ```

    ```bash Terminal 3 — same-origin /collab router theme={null}
    E2E_GATEWAY_PORT=3000 \
    E2E_NEXT_ORIGIN=http://127.0.0.1:3001 \
    E2E_COLLAB_ORIGIN=http://127.0.0.1:3002 \
      pnpm --filter @softmaple/web e2e:router
    ```

    Open [http://localhost:3000](http://localhost:3000). Set
    `COLLAB_ALLOWED_ORIGINS="http://localhost:3000"` in
    `apps/collab-nitro/.env.local`.

    Alternatively, use `vercel dev` from the repository root so the Services
    routing in `vercel.json` serves `/collab/*` from `apps/collab-nitro`.

    <Note>
      The local router is not a release-equivalent test of Vercel Services
      WebSocket routing. Verify document and Presence handshakes on a real
      Preview deployment before promoting.
    </Note>
  </Accordion>
</AccordionGroup>

## Development Workflow

<AccordionGroup>
  <Accordion icon="code" title="Running specific commands">
    Use pnpm filters to run commands for specific packages:

    ```bash theme={null}
    # Type checking
    pnpm --filter @softmaple/web typecheck

    # Linting
    pnpm --filter @softmaple/web lint

    # Build production
    pnpm build
    ```
  </Accordion>

  <Accordion icon="test-tube" title="Running tests">
    Run tests for specific packages:

    ```bash theme={null}
    # Run unit tests
    pnpm --filter @softmaple/md2latex test

    # Run E2E tests
    pnpm --filter @softmaple/web test:e2e
    ```
  </Accordion>

  <Accordion icon="git-branch" title="Creating branches">
    Follow the branch naming convention:

    ```bash theme={null}
    git checkout -b feature/my-feature-$(date +%s)
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

Explore the key features and start building with Softmaple:

<CardGroup>
  <Card title="Monorepo Structure" icon="folder-tree" href="/development">
    Learn about the project structure and package organization.
  </Card>

  <Card title="API Reference" icon="square-code" href="/api-reference/introduction">
    Explore the API endpoints for documents and workspaces.
  </Card>

  <Card title="Live Demo" icon="browser" href="https://softmaple.ink">
    Try Softmaple online without installing locally.
  </Card>

  <Card title="Community Support" icon="discord" href="https://discord.gg/Vwsuqq7dQD">
    Get help and connect with other developers.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.