Development Setup

This guide will help you set up your local development environment for contributing to Neroli's Lab.

Prerequisites

Before you begin, ensure you have the following installed:

Required Tools

1. Node.js (v24 or higher)

   • We recommend using Node Version Manager (nvm) for easy version management. We have a dedicated .nvmrc to align our node versions. On Windows it is recommended to use nvm inside WSL (Windows Subsystem for Linux), but other alternatives like nvm-windows exist.

   • Install Node.js: nvm install && nvm use

2. Visual Studio Code

   • We recommend Visual Studio Code
   • Open the project through our *.code-workspace file
   • Install the recommended extensions when prompted (if you miss the prompt just check recommendations in the workspace file)

Optional Tools

1. Bun (recommended for faster development)

   • Install Bun for faster package management and execution

2. Docker (for database setup)

   • Install Docker
   • Used for running MySQL database locally

Initial Setup

1. Fork and Clone the Repository

First, fork the repository to your own GitHub account by clicking the "Fork" button on the main repository page.

Then clone your fork:

# Replace 'your-username' with your actual GitHub username
git clone https://github.com/your-username/nerolis-lab.git
cd nerolis-lab

# Add the upstream remote to keep your fork updated
git remote add upstream https://github.com/nerolis-lab/nerolis-lab.git

2. Open the Workspace in VS Code

Open the cloned repository in VS Code, navigate to the workspace and open it. Click the green "open workspace" button.

3. Install Dependencies and Build Modules

# Install root dependencies
npm install

# Install dependencies for each component
cd common && npm install && npm run build && cd ..
cd backend && npm install && npm run build && cd ..
cd frontend && npm install && npm run build && cd ..
cd guides && npm install && cd ..

Component Setup

Backend Setup

See the Backend Documentation for detailed setup instructions including:

• Database configuration
• OAuth provider setup

Frontend Setup

See the Frontend Documentation for detailed setup instructions including:

• Development server setup
• OAuth client configuration

Guides Setup (optional)

If you work on the guides package (guides/ in the repo), run the VitePress dev server:

cd guides
npm run dev

See guides/DEVELOPMENT.md for maintainer tooling and how guide content is structured. Guides are served under /guides/ on the main app in production.

Development Workflow

Make sure you have installed and built each module.

1. Making Changes

1. Common Library Changes: Rebuild with npm run build in the common directory. You can also npm run build-watch which will automatically rebuild on changes
2. Component Changes: The hot-reload from npm run dev will handle changes automatically

2. Testing

# Run tests for all components
npm run test

# Hot-reloads the tests on code changes, useful during active test writing
npm run test-watch

# Or run tests for specific components
cd common && npm run test
cd backend && npm run test
cd frontend && npm run test

Environment Configuration

Each component requires its own environment configuration. See the component-specific documentation for details:

• Backend Environment Setup
• Frontend Environment Setup