---
title: Local Preview
description: The Jamdesk CLI lets you preview your documentation on your machine before pushing to production. Changes appear instantly as you edit.
---

Run `jamdesk dev` (or `npx jamdesk dev`) from any directory that contains a `docs.json` to start a local server with hot reload, full search, and all components working exactly as they do in production.

## Prerequisites

Before you start, make sure you have:

- **Node.js 20+** - Check with `node --version`
- **A docs project** - With a `docs.json` configuration file

## Starting the Dev Server

<Tabs>
  <Tab title="npm (Global Install)">
    Install the CLI globally, then run from your docs directory:

    ```bash
    npm install -g jamdesk
    cd your-docs
    jamdesk dev
    ```
  </Tab>
  <Tab title="npx (No Install)">
    Run directly without installing:

    ```bash
    cd your-docs
    npx jamdesk dev
    ```
  </Tab>
</Tabs>

Your docs will be available at **http://localhost:3000**

## What You Get

<Columns cols={2}>
  <Card title="Hot Reload" icon="bolt">
    Edit MDX files and see changes instantly. Edits to docs.json and your `style.css` are picked up on refresh.
  </Card>
  <Card title="Full Search" icon="magnifying-glass">
    Test Cmd+K search with your actual content
  </Card>
  <Card title="All Components" icon="puzzle-piece">
    Every component works exactly like production
  </Card>
  <Card title="Theme Switching" icon="moon">
    Test both light and dark modes
  </Card>
</Columns>

## Custom Port

The default port is 3000. If it's in use, specify a different one:

```bash
jamdesk dev --port 3001
```

Or set a permanent default in `~/.jamdeskrc`:

```json
{
  "defaultPort": 3001
}
```

## Verbose Mode

See detailed build information with the `--verbose` flag:

```bash
jamdesk dev --verbose
```

This shows:
- File change detection
- Build timing
- Navigation parsing
- Any warnings or errors

## First Run Performance

<Note>
The first time you run `jamdesk dev`, it installs dependencies to `~/.jamdesk`. This takes 30-60 seconds. Subsequent runs start in under 5 seconds.
</Note>

To clear the cache and force a fresh install:

```bash
jamdesk clean
jamdesk dev
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Port already in use">
    Another process is using port 3000.

    **Option 1:** Use a different port
    ```bash
    jamdesk dev --port 3001
    ```

    **Option 2:** Find and stop the process
    ```bash
    lsof -i :3000
    kill -9 <PID>
    ```
  </Accordion>

  <Accordion title="docs.json not found">
    Make sure you're in the directory containing your `docs.json` file:

    ```bash
    ls docs.json  # Should show the file
    jamdesk dev
    ```
  </Accordion>

  <Accordion title="Changes not appearing">
    Try these steps:
    1. Check the terminal for errors
    2. Hard refresh the browser (Cmd+Shift+R)
    3. Restart the dev server
    4. Run `jamdesk clean` and try again
  </Accordion>

  <Accordion title="Slow startup">
    Run diagnostics:
    ```bash
    jamdesk doctor
    ```

    This checks your environment and identifies issues.
  </Accordion>
</AccordionGroup>

## What's Next?

<Columns cols={2}>
  <Card title="VS Code Extension" icon="window" href="/development/vscode-extension">
    Start the dev server from the VS Code status bar
  </Card>
  <Card title="Deployment" icon="rocket" href="/development/deployment">
    Learn about the build and deploy process
  </Card>
</Columns>