Skip to content
Neurodesk

Running the Neurodesk Site Locally (Astro + Starlight)

The Neurodesk website is built with Astro using the Starlight documentation theme. This page covers how to run it locally so you can preview your changes before opening a pull request.

1. Prerequisites

Section titled “1. Prerequisites”
  • Node.js 20 or newer
  • pnpm — the package manager this project uses

Install Node.js first: pnpm is a Node program and will fail with env: node: No such file or directory if no runtime is present.

Installing Node.js

Section titled “Installing Node.js”

Check what you already have:

Terminal window
node --version

If that prints v20 or higher, skip to Installing pnpm. If it prints command not found, install Node using whichever option suits your system:

With Homebrew:

Terminal window
brew install node

Without Homebrew, download the macOS LTS installer from nodejs.org and run it.

Installing pnpm

Section titled “Installing pnpm”

Try Corepack first — it ships with some Node builds and pins pnpm per project:

Terminal window
corepack enable
corepack prepare pnpm@latest --activate

If that reports command not found, Corepack is not bundled with your Node build. Use one of these instead — pick a single method, not several:

With Homebrew:

Terminal window
brew install pnpm

Or the standalone installer:

Terminal window
curl -fsSL https://get.pnpm.io/install.sh | sh -

Verify both before continuing:

Terminal window
node --version
pnpm --version

Only move on once both print a version number. Run the remaining commands one at a time — if you paste them as a block, later commands run before the earlier ones have finished.

2. Install dependencies

Section titled “2. Install dependencies”

From the root of your cloned repository:

Terminal window
pnpm install

This reads pnpm-lock.yaml and installs the exact dependency versions the site is built with. You only need to repeat this when dependencies change (for example after pulling in a branch that updates package.json).

3. Start the dev server

Section titled “3. Start the dev server”
Terminal window
pnpm dev

Your local site will be available at http://localhost:4321.

The dev server watches your files and hot-reloads the browser as you save, so you can keep it running while you edit. Press Ctrl+C in the terminal to stop it (this is Ctrl+C on macOS too, not Cmd+C).

4. Build and preview the production site

Section titled “4. Build and preview the production site”

Before opening a pull request, it is worth confirming that the site builds cleanly. The dev server is more forgiving than the production build, so this step catches broken links and invalid frontmatter that you would otherwise only see in CI.

  1. Build the static site into dist/:

    Terminal window
    pnpm build

  2. Serve that build locally:

    Terminal window
    pnpm preview

  3. Open the URL printed in your terminal and check your pages.

If the build fails, the error message names the file and line to fix. Common causes are a broken internal link, a missing image in public/, or an MDX component that was used without being imported. See the Markdown Reference for correct syntax.

5. Where things live

Section titled “5. Where things live”
PathContents
src/content/docs/All documentation pages (.md and .mdx). The file path becomes the URL.
src/components/Reusable Astro and React components used inside pages.
src/styles/Custom CSS layered on top of the Starlight theme.
public/Static assets served as-is: images, icons, downloads.
astro.config.mjsSite config, sidebar structure, and redirects.

6. Adding a page to the sidebar

Section titled “6. Adding a page to the sidebar”

Most sections of the sidebar are generated automatically from the directory structure in astro.config.mjs, so a new file in an existing folder appears without any extra configuration. Control its position and label from the page’s own frontmatter:

---
title: My New Page
description: A short summary used for search results and social previews.
sidebar:
  label: Short Label
  order: 2
---

If you add a whole new top-level section, add it to the sidebar array in astro.config.mjs.

7. Changing a page’s URL

Section titled “7. Changing a page’s URL”

The URL of a page follows its path under src/content/docs/. If you rename or move a file, add an entry to the redirects map in astro.config.mjs so existing links keep working:

redirects: {
  '/old/path': '/new/path/',
}

Troubleshooting

Section titled “Troubleshooting”

env: node: No such file or directory (or 'node' is not recognized on Windows) — pnpm is installed but Node.js is not. pnpm cannot run without a Node runtime; see Installing Node.js above.

pnpm: command not found — pnpm is not installed, or it is installed but not yet on your PATH. Work through Installing pnpm, then open a new terminal so the updated PATH takes effect.

corepack: command not found — Corepack is not bundled with your Node build. This is expected on Homebrew and some distro builds; use one of the other pnpm install methods instead.

Install fails with an engine or version error — check node --version. Node 20 or newer is required; older releases will fail on some dependencies.

Changes do not appear in the browser — stop the dev server, delete the Astro cache, and start again:

Terminal window
rm -rf node_modules/.astro
pnpm dev

A stale or corrupted install — remove and reinstall dependencies:

Terminal window
rm -rf node_modules
pnpm install

pnpm install fails with a permissions error — you may be running it outside the repository, or in a directory you do not own. Confirm you are in the repository root (the folder containing package.json) and that you own it. Do not run pnpm install with sudo.

Need help?

Section titled “Need help?”

If you get stuck, open a discussion or an issue and we will help you out.