Guide: Local Dev Setup (ERN Stack)

Purpose

To provide a standardized local development setup guide for web projects, ensuring all developers work in a consistent, reproducible environment across frontend and backend stacks.

Scope

  • Applies to all web development projects (frontend, backend, full-stack).
  • Used by Developers, Tech Leads, and DevOps Engineers.
  • Covers environment setup, package installation, configuration, and verification.

Objectives

  • Ensure new devs can spin up projects locally within a day.
  • Standardize tools, configurations, and dependencies.
  • Avoid “works on my machine” issues.

Step-by-Step Setup Process

Step 1 – Prerequisites

  • Install the following (versions to be specified in each project’s README):
    • Node.js + NVM (LTS version, e.g., v18.x).
    • Package Manager: npm or yarn (consistent per project).
    • Git (with SSH key configured).
    • Docker Desktop (for DB and services, if project uses containers).
    • Database Client (e.g., PgAdmin, TablePlus, or MySQL Workbench).
    • IDE: VS Code (with extensions from checklist).

Step 2 – Repo & Branch Setup

  • Clone project repo:
  • git clone git@github.com:org/project-name.git
  • cd project-name
  • Checkout appropriate branch:
  • git checkout develop
  • Pull latest updates:
  • git pull origin develop

Step 3 – Dependency Installation

  • Install dependencies:
  • npm install
  • # or
  • yarn install
  • Verify no peer dependency conflicts.
  • If project uses monorepo (Nx, Lerna, Turborepo), run workspace install.

Step 4 – Environment Variables

  • Copy sample env file:
  • cp .env.example .env
  • Fill with:
    • API URLs (staging/dev).
    • Database credentials (read-only for dev).
    • Third-party service keys (e.g., Firebase, Stripe test keys).
  • Store secrets securely (never commit .env to repo).

Step 5 – Database Setup

  • Start database (if containerized):
  • docker-compose up -d
  • Run migrations:
  • npm run migrate
  • Seed dev database if required:
  • npm run seed

Step 6 – Run Local Build

Step 7 – Verification

  • Confirm:
    • Builds without errors.
    • Connects to staging DB or mock DB.
    • Default test user can log in.
  • Submit a test commit + PR (to confirm repo access + CI triggers).

Best Practices

  • Always use NVM for Node version control.
  • Keep dependencies updated monthly.
  • Use Dockerized services for consistency across machines.
  • Add pre-commit hooks (lint + format) to avoid code style drift.

Do’s & Don’ts

Do’s

  • Follow the .env.example strictly — don’t improvise keys.
  • Document any new setup step you discover.
  • Use aliases in terminal (e.g., npm run db:migrate).

Don’ts

  • Don’t hardcode credentials in config files.
  • Don’t install global dependencies unless mandated.
  • Don’t skip initial migrations (causes inconsistent states).

Outcome

  • Every dev can set up a local environment within 1 day.
  • Consistent, reproducible builds across all dev machines.
  • Directly supports EPIC 1 – Doc 1 (Onboarding SOP) and Doc 2 (Onboarding Kit).