Development Environment Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• apps/api/package.json
• apps/portal/package.json
• apps/extensions/package.json
• apps/extensions/README.md
• apps/api/src/main.ts
• apps/portal/next.config.js
• apps/extensions/webpack.dev.js
• apps/extensions/webpack.config.js

This document provides a comprehensive guide to setting up the development environment for the Ever Rec platform. The project is a monorepo managed by Turborepo, containing several distinct applications: a NestJS API server (api), a Next.js web portal (portal), and a browser extension (extensions). Following these instructions will allow a developer to clone, configure, and run the entire platform locally.

The setup process involves installing prerequisites, cloning the repository, installing dependencies with pnpm, configuring environment variables for each application, and running the development servers. Special instructions are also provided for browser extension development.

Sources: README.md:1-20, 100-103

1. Prerequisites

Before setting up the project, ensure your development machine has the following tools installed.

• Node.js: Version 20.x or higher.
• PNPM: The specified package manager for this project.

You can verify your installations with the following commands:

# Verify Node.js version
node --version
# Expected output: v20.x.x or higher

# Install PNPM globally if you haven't already
npm install -g pnpm

# Verify PNPM installation
pnpm --version
# Expected output: 9.9.0 or higher

Sources: README.md:83-97, package.json:71-74

2. Initial Setup

The initial setup involves cloning the repository and installing all dependencies for the monorepo packages.

This diagram illustrates the initial one-time setup process.

1. Clone the Repository:

   git clone https://github.com/ever-co/ever-rec
   cd ever-rec
   

2. Install Dependencies: The project uses pnpm workspaces. The pnpm install command will install dependencies for all applications and packages within the monorepo.

   pnpm install
   

Sources: README.md:99-107, package.json:48-55

3. Environment Configuration

Each application within the monorepo requires its own environment configuration file. Sample files are provided and should be copied to create local development configurations.

Sources: README.md:109-110

API Environment (apps/api)

1. Create a local environment file for the API server.

   cp apps/api/.env.sample apps/api/.env.dev
   

2. Populate .env.dev with the necessary values. These are primarily for Firebase and Firebase Admin integration.

Variable	Description
FIREBASE_API_KEY	Firebase project API key.
FIREBASE_AUTH_DOMAIN	Firebase project auth domain.
FIREBASE_DATABASE_URL	Firebase Realtime Database URL.
FIREBASE_PROJECT_ID	Firebase project ID.
FIREBASE_STORAGE_BUCKET	Firebase storage bucket URL.
FIREBASE_MESSAGING_SENDER_ID	Firebase messaging sender ID.
FIREBASE_APP_ID	Firebase application ID.
FIREBASE_MEASUREMENT_ID	Firebase measurement ID.
FIREBASE_ADMIN_PRIVATE_KEY	Firebase Admin SDK private key.
FIREBASE_ADMIN_CLIENT_EMAIL	Firebase Admin SDK client email.
EXTENSION_ID	The ID of the browser extension.

Sources: README.md:112-136

Portal Environment (apps/portal)

1. Create a local environment file for the web portal.

   cp apps/portal/.env.sample apps/portal/.env.local
   

2. Populate .env.local with the correct URLs for your local environment.

Variable	Description	Default Local Value
NEXT_PUBLIC_API_BASE_URL	Base URL for the API server.	http://localhost:3000
NEXT_PUBLIC_WEBSITE_URL	Base URL for the web portal itself.	http://localhost:4200
NEXT_PUBLIC_STATIC_FILES_URL	URL for static files.	your_static_files_url
EXTENSION_ID	The ID of the browser extension.	your_extension_id

Sources: README.md:138-150

Extensions Environment (apps/extensions)

1. Create a local environment file for the browser extension.

   cp apps/extensions/.env.sample apps/extensions/.env.dev
   

2. Populate .env.dev with the correct values. The dotenv-webpack plugin is used to inject these variables during the development build.

Variable	Description	Default Local Value
EXTENSION_ID	The ID of the browser extension.	your_extension_id
API_BASE_URL	Base URL for the API server.	http://localhost:3000
WEBSITE_URL	Base URL for the web portal.	http://localhost:4200
STATIC_FILES_URL	URL for static files.	your_static_files_url

Sources: README.md:152-164, apps/extensions/webpack.dev.js:7,12-14

4. Running the Development Servers

The project uses Turborepo to manage the development workflow. A single command can start all applications concurrently.

This diagram shows how the top-level dev script uses Turborepo to run the individual dev scripts in each application.

• Start all services:

  pnpm dev
  

• Access Development Environment:
  • API Server: http://localhost:3000
  • Web Portal: http://localhost:4200

You can also run each application individually using Turborepo filters:

# Start only the API server
pnpm dev:api

# Start only the web portal
pnpm dev:portal

# Start only the extension in watch mode
pnpm dev:extensions

Sources: README.md:166-174, package.json:19-22, apps/api/src/main.ts:40, apps/portal/package.json:11

5. Browser Extension Development

Developing the browser extension involves a separate build process and installation into a browser that supports unpacked extensions.

Building the Extension

The extension uses Webpack for bundling. The development build starts a watcher that recompiles on file changes.

• Start development build with watch mode:

  # From the root directory
  pnpm dev:extensions
  

  This command runs webpack --watch --config webpack.dev.js inside the apps/extensions directory. The output is placed in apps/extensions/build/dev.

Sources: README.md:176-179, apps/extensions/package.json:28, apps/extensions/webpack.dev.js:10

Installing in Chrome

The following flowchart outlines the steps to load the unpacked extension into Google Chrome for testing.

1. Open Google Chrome and navigate to chrome://extensions.
2. Enable the Developer mode toggle, usually in the top-right corner.
3. Click the Load unpacked button.
4. Navigate to the project directory and select the development build folder: apps/extensions/build/dev.
5. The extension will now be installed and active. Any changes to the source code will trigger a rebuild, but you may need to manually reload the extension in Chrome to see the changes.

Sources: README.md:181-193, apps/extensions/README.md:16-19