Getting Started - Meridian

Prerequisites

Install the tooling below before cloning the repo or running npm run setup. Meridian’s Meridian/package.json declares engines.node: 20.x—use Node 20, not 18 or 22, unless you intentionally align the whole team on a different major. You will also need Git (for clone and normal development). npm ships with Node.

Node.js 20.x and npm

macOS
Windows

Pick one approach:Option A — Homebrew

brew install node@20
brew link node@20 --force --overwrite

Option B — nvm (recommended if you switch Node versions often)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# restart the terminal, then:
nvm install 20
nvm use 20

Option C — Official installerDownload the 20.x LTS macOS installer from https://nodejs.org/ and run it.Verify:

node -v   # should print v20.x.x
npm -v

Option A — Official installer (simplest)

Open https://nodejs.org/ and download the 20.x LTS Windows installer (.msi).
Run the installer and accept the defaults that add Node and npm to PATH.
Open a new PowerShell or Command Prompt.

Option B — nvm for WindowsIf you already use nvm-windows, install and select 20.x:

nvm install 20.18.0
nvm use 20.18.0

Verify:

node -v
npm -v

MongoDB Community Server

Meridian’s backend expects a MongoDB instance you can reach from Meridian/backend/.env (for example mongodb://127.0.0.1:27017/...). The steps below install MongoDB Community Server locally—not Atlas.

macOS
Windows

Install (Homebrew — MongoDB tap)

brew tap mongodb/brew
brew update
brew install mongodb-community

Start the databaseRun mongod in the foreground when debugging, or register a background service:

brew services start mongodb-community

Check it is listening

mongosh --eval "db.runCommand({ ping: 1 })"

To stop the background service later: brew services stop mongodb-community.

Homebrew’s formula name and data directory can change over time; if brew install mongodb-community fails, run brew search mongodb and follow the current MongoDB Server install on macOS docs.

Install

Download MongoDB Community Server for Windows from MongoDB Download Center (MSI).
Run the installer. Typical choices:
- Complete setup type
- Install MongoDB as a Service (recommended)
- Install MongoDB Compass if you want a GUI (optional)

Start the service

Open Services (Win + R → services.msc), find MongoDB Server (name may vary slightly), and Start it if it is not running, or
In an Administrator PowerShell or Command Prompt:

net start MongoDB

If net start reports the service name is wrong, check the exact name in services.msc and use that name instead of MongoDB.Check it is listeningIf mongosh is on your PATH after install:

mongosh --eval "db.runCommand({ ping: 1 })"

If mongod / mongosh are not found, add MongoDB’s bin directory (often under C:\Program Files\MongoDB\Server\<version>\bin) to your user PATH, then open a new terminal.

GitHub CLI (`gh`)

The Meridian CLI uses gh for pull requests and merges when you run flows like meridian ship. Install it even if you use another Git UI day to day.

macOS
Windows

brew install gh
gh auth login

Follow the prompts (HTTPS or SSH, GitHub.com, login via browser). Confirm with gh auth status.

winget (recommended if available)

winget install --id GitHub.cli

Then open a new terminal and run:

gh auth login

MSI: alternatively download GitHub CLI from https://cli.github.com/ and run the installer, then gh auth login.Confirm with gh auth status.

Verify installs

macOS
Windows

node -v
npm -v
git --version
mongod --version
gh --version

In PowerShell or Command Prompt:

node -v
npm -v
git --version
mongod --version
gh --version

If mongod or gh are not found, ensure their install folders are on your PATH, or use the full path to each executable.

WSL2 is a practical option on Windows: run the same shell-oriented steps as macOS/Linux inside WSL and keep the Meridian checkout on a Linux filesystem (for example ~/dev/Meridian) to reduce symlink and line-ending friction.

Clone Meridian

Clone the Meridian Git repository (the web + API app)—not a parent “monorepo” meta-repo. You only need Meridian/ on disk to start; other repos are added next to it with npm run setup / meridian setup or manually.

git clone git@github.com:Study-Compass/Meridian.git
cd Meridian

Use the clone URL from GitHub for Meridian if yours differs (fork, HTTPS, enterprise host).

“Meridian-Mono” in conversation or older notes usually means a suggested local folder layout: one parent directory whose children include Meridian/, Events-Backend/, and optionally Meridian-Mobile/. That parent folder is not a single git repository you clone—it’s just the recommended development repo structure.

From here on, Meridian/ means the root of the Meridian repo you cloned (where package.json with meridian / dev scripts lives).

Bootstrap with the Meridian CLI

From Meridian/, the recommended first step is:

npm run setup

That runs meridian setup, which installs dependencies, can clone Events-Backend if it is missing, and can link backend/events to the sibling Events-Backend checkout (see platform tabs below). If the meridian command is already on your PATH, you can run meridian setup instead of npm run setup.

Platform-specific setup

macOS
Windows

Put `meridian` on your PATH

From Meridian/:

npm link

After that, meridian should resolve in any terminal. If it does not, confirm your global npm bin is on PATH (often npm prefix -g plus /bin).

Events-Backend and `backend/events`

Layout should be:

workspace/              # any parent folder you choose (not a git repo)
  Meridian/             # this Meridian clone
  Events-Backend/       # sibling; added by setup/CLI or cloned manually

After npm run setup, accept the prompt to symlink, or run:

meridian symlink

Node creates a normal symlink here; no extra Windows-style steps.

MongoDB

If you installed MongoDB Community in Prerequisites, ensure it is running:

brew services start mongodb-community

Free a port (3000 / 5001)

lsof -ti:3000 | xargs kill
lsof -ti:5001 | xargs kill

Health check

curl http://localhost:5001/health

Put `meridian` on your PATH (manual)

npm link on Windows still registers a global shim, but meridian may not be on your PATH` depending on how Node was installed.

From Meridian/, run: npm link
Find the global npm prefix: npm prefix -g
The meridian.cmd (and related shims) usually live under that folder, often alongside node.exe paths such as:
- %AppData%\npm
- or C:\Program Files\nodejs\

Add the folder that contains meridian.cmd to your user PATH:Settings → System → About → Advanced system settings → Environment Variables → User variables → Path → Edit → New → paste the folder path → OK out.Open a new terminal and run where meridian. If it still fails, you can always run the CLI without PATH changes:

cd path\to\Meridian
npm run meridian -- setup
npm run meridian -- status

Events-Backend and `backend/events` (symlinks / junctions)

Layout should still be:

workspace\
  Meridian\
  Events-Backend\

meridian symlink uses a filesystem symlink. On Windows, creating symlinks often requires one of:

Developer Mode enabled (Settings → System → For developers → Developer Mode), then run meridian symlink again, or
Running your terminal as Administrator when creating the link, or
Skipping the CLI symlink step and creating a directory junction yourself (no symlink privilege in many setups):

In Command Prompt from your Meridian repo root (same folder that contains package.json and backend\), with backend\events removed or renamed first if it already exists as a real folder:

mklink /J backend\events ..\Events-Backend

Junctions only work when Events-Backend lives next to Meridian as shown above. The app should still be started with npm run server / npm run dev from Meridian/ so Node can follow the link with --preserve-symlinks.

MongoDB

If you installed MongoDB Community in Prerequisites, start the Windows service from Services (services.msc) or, in an Administrator prompt:

net start MongoDB

The exact service name depends on the installer (often MongoDB).

Free a port (3000 / 5001)

netstat -ano | findstr :3000
netstat -ano | findstr :5001

Note the PID in the last column, then:

taskkill /PID <pid> /F

Health check

curl http://localhost:5001/health

Or in PowerShell:

Invoke-RestMethod http://localhost:5001/health

Workspace layout

Meridian and Events-Backend should be sibling directories under whatever parent folder you use (again: the parent is not a repo—only Meridian and Events-Backend are separate clones):

workspace/
  Meridian/
  Events-Backend/

Optional: add Meridian-Mobile/ as another sibling if you work on the Expo app; it is its own clone, not inside Meridian.

Environment variables

Create both:

Meridian/.env
Meridian/backend/.env

At minimum:

JWT_SECRET=replace-me
MONGO_URI_RPI=mongodb://127.0.0.1:27017/meridian
NODE_ENV=development

Use MONGODB_URI when the backend is configured to read that variable instead of MONGO_URI_RPI.

Run the app

From Meridian/:

npm run dev

Frontend: http://localhost:3000
Backend: http://localhost:5001

Run services separately

Backend (preserves backend/events links):

npm run server

Frontend only:

npm run client

Verify

Open http://localhost:3000
Hit the backend health endpoint (see macOS vs Windows tabs above for curl vs PowerShell).

Development workflow

Making changes

Frontend hot-reloads via the webpack dev server
Backend runs under nodemon when using npm run dev

Testing

From Meridian/:

npm run test:backend
npm run test:frontend
npm run test:ci

See Testing for suites, folders, and CI.

Meridian CLI branch flow

meridian start MER-123-Your-Feature
meridian status
meridian ship

Development

Day-to-day workflow, debugging, and troubleshooting after the stack is up.

Web client best practices

React conventions, routing, state, and useFetch / postRequest API access.

Backend best practices

req.db, routes, auth middleware, and multi-tenant patterns in Meridian/backend.

Authentication overview

Multi-tenant identity

Global users, memberships, and SSO across school subdomains.

SAML

University IdP integration when a tenant enables institutional SSO.

Testing

npm run test:*, folder layout, and CI parity.

API reference

REST surfaces and how the web and mobile clients call them.

Troubleshooting

Module not found after clone / setup

From Meridian/:

npm run setup

Database connection issues

macOS
Windows

brew services start mongodb-community

Start the MongoDB Windows service (name varies by installer), or run net start <MongoDBServiceName> from an elevated prompt if you use a service install.

Need more detail on the CLI? See Meridian CLI. For general workflow help, see the Development guide.

​Prerequisites

​Node.js 20.x and npm

​MongoDB Community Server

​GitHub CLI (gh)

​Verify installs

​Clone Meridian

​Bootstrap with the Meridian CLI

​Platform-specific setup

​Put meridian on your PATH

​Events-Backend and backend/events

​MongoDB

​Free a port (3000 / 5001)

​Health check

​Put meridian on your PATH (manual)

​Events-Backend and backend/events (symlinks / junctions)

​MongoDB

​Free a port (3000 / 5001)

​Health check

​Workspace layout

​Environment variables

​Run the app

​Run services separately

​Verify

​Development workflow

​Related pages

Development

Web client best practices

Backend best practices

Authentication overview

Multi-tenant identity

SAML

Testing

API reference

​Troubleshooting

Prerequisites

Node.js 20.x and npm

MongoDB Community Server

GitHub CLI (`gh`)

Verify installs

Clone Meridian

Bootstrap with the Meridian CLI

Platform-specific setup

Put `meridian` on your PATH

Events-Backend and `backend/events`

MongoDB

Free a port (3000 / 5001)

Health check

Put `meridian` on your PATH (manual)

Events-Backend and `backend/events` (symlinks / junctions)

MongoDB

Free a port (3000 / 5001)

Health check

Workspace layout

Environment variables

Run the app

Run services separately

Verify

Development workflow

Related pages

Troubleshooting