Frontend Setup

This guide walks you through setting up the Maybern React frontend for local development.

All commands in this guide should be run from within the frontend/ directory unless otherwise specified.

Set Up Node.js with nvm

Install nvm

Install Node Version Manager via Homebrew:

brew install nvm

Add nvm to shell configuration

Add nvm to your .zshrc:

echo -e '\nexport NVM_DIR="$HOME/.nvm"\n[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

Install the project Node version

Install the Node.js version specified in .nvmrc:

nvm install

Activate the Node version

Use the project’s Node version:

nvm use

Set Up pnpm Package Manager

Install pnpm globally:

npm install --global pnpm@9.6.0

Then install project dependencies:

pnpm install

Set Up Environment Variables with direnv

Install direnv

brew install direnv

Add direnv hook to shell

echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

Reload shell configuration

Open a new shell or reload your configuration:

source ~/.zshrc

Allow direnv for the project

Allow direnv to load the .envrc file:

direnv allow

Generate API Clients

Generate the TypeScript API clients from the backend OpenAPI specification:

pnpm run gen

This uses Orval to generate type-safe API clients. The configuration is in orval.config.ts.

Run this command whenever the backend API changes to keep the frontend clients in sync.

Run the Frontend (Basic)

Start the development server:

pnpm start

The app will be available at http://localhost:3000.

Run with HTTPS and Subdomains (Recommended)

For full functionality including customer-specific subdomains, set up HTTPS locally.

Set up local DNS resolution

Install and configure dnsmasq to resolve .test domains locally:

brew install dnsmasq
echo 'address=/.test/::1' > $(brew --prefix)/etc/dnsmasq.conf
sudo brew services start dnsmasq

sudo mkdir -p /etc/resolver
sudo bash -c 'echo "nameserver ::1" > /etc/resolver/test'

Set up local certificate authority

Install mkcert and create a local CA for HTTPS:

brew install nss mkcert
mkcert -install

Start with subdomains

Start the development server with HTTPS and subdomain support:

pnpm start:subdomains

Open the app

Navigate to https://app.maybern.test:3000 in your browser.

You should see the Maybern login page. If you see a certificate warning, you may need to trust the mkcert CA in your browser.

Test a Production Build

To verify the production build works correctly:

pnpm run build:preview
pnpm run start:preview

IDE Setup (VS Code / Cursor)

Install the recommended extensions:

ESLint: JavaScript/TypeScript linting
Prettier: Code formatting

Add to your settings.json:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "json"
  ]
}

Introduction

Local Setup

Frontend Setup

Frontend Setup

Set Up Node.js with nvm

Set Up pnpm Package Manager

Set Up Environment Variables with direnv

Generate API Clients

Run the Frontend (Basic)

Run with HTTPS and Subdomains (Recommended)

Test a Production Build

IDE Setup (VS Code / Cursor)

Next Steps

Running the Stack

Loading Data

Introduction

Local Setup

​Frontend Setup

​Set Up Node.js with nvm

​Set Up pnpm Package Manager

​Set Up Environment Variables with direnv

​Generate API Clients

​Run the Frontend (Basic)

​Run with HTTPS and Subdomains (Recommended)

​Test a Production Build

​IDE Setup (VS Code / Cursor)

​Next Steps

Running the Stack

Loading Data

Frontend Setup

Set Up Node.js with nvm

Set Up pnpm Package Manager

Set Up Environment Variables with direnv

Generate API Clients

Run the Frontend (Basic)

Run with HTTPS and Subdomains (Recommended)

Test a Production Build

IDE Setup (VS Code / Cursor)

Next Steps