Suggested Updates to heat-stack/README.md

[derekvmcintire]

H.E.A.T. Frontend Setup Documentation

This guide will help you set up the frontend application for the Home Energy
Analysis Tool (H.E.A.T.) project. Please follow these instructions carefully.

---

Prerequisites

Install Git Large File Storage (Git LFS)

Git LFS is required to manage large files in the repository. Choose one of the
methods below to install it:

Method 1: Using Homebrew (Recommended)

brew install git-lfs
git lfs install

Method 2: Manual Installation

1. Download the Git LFS installer from git-lfs.com.
2. Unzip the downloaded file and navigate to the extracted folder:

   cd ~/Downloads/git-lfs-<version>

3. Run the installation script:

   ./install.sh
   git lfs install

4. Confirm the installation with:

   git lfs install

For more details, visit the
official documentation.

---

Repository Setup

1. Clone the repository:

   git clone git@github.com:codeforboston/home-energy-analysis-tool.git

2. Navigate to the project directory:

   cd home-energy-analysis-tool/heat-stack

3. Copy the example environment file into a new .env file:

   cp .env.example .env

---

Node.js Setup

The project requires Node.js version 18 to avoid engine errors with node v19+.
Use Node Version Manager (NVM)
for managing Node.js versions (nvm is preinstalled in coding spaces).

Install NVM (Official Method)

1. Download and install NVM:

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

2. Restart your terminal. Ensure NVM is installed by running:

   nvm --version

3. Install Node.js version 18:

   nvm install 18

4. Use Node.js version 18:

   nvm use 18

---

Install Dependencies and Build

1. Install project dependencies:

   npm install

2. Build the rules engine into the public/pyodide-env folder (note, you may need to run this each time you switch to a new branch):

   npm run buildpy

3. Start the development server:

   npm run dev

If you encounter errors during this process, try the following steps:

• Delete the node_modules folder and package-lock.json file:

  rm -rf node_modules package-lock.json

• Reinstall dependencies:

  npm install

• Run the development server again:

  npm run dev

---

Setting Up in GitHub Codespaces

If using GitHub Codespaces, follow these steps:

1. Navigate to the project directory:

   cd home-energy-analysis-tool/heat-stack

2. Create an environment file:

   cp .env.example .env

3. Use Node.js version 18:

   nvm use 18

4. Install dependencies and build:

   npm install
   npm run buildpy
   npm run dev

5. Disable auto-save in VSCode (this is to avoid auto recompiling and page
   refresh while making changes):

   • Go to File > Preferences > Settings.
   • Search for "Auto Save" and uncheck it.
   • For reference, see
     this Stack Overflow post.

---

Handling Special Cases

Updating Pyodide

If the version of Pyodide changes or you encounter issues with the Pyodide
environment:

1. Copy the necessary Pyodide files:

   cp ./node_modules/pyodide/* public/pyodide-env/

2. Ensure the correct numpy wheel file is in the public/pyodide-env folder.
   If missing:
   • Download the latest Pyodide release from
     Pyodide releases.
   • Extract the file and locate the numpy wheel file.
   • Copy it into the public/pyodide-env folder.
3. Check the Pyodide version:

   npm list pyodide

   Ensure the numpy file matches the version.

Fixing Loader Errors

If you encounter a loader error, run:

npm run postinstall

---

Additional Notes

• The npm audit fix command can resolve minor dependency issues.
• For a clean setup, ensure sufficient disk space (at least 1GB).

---

Script Overview

Below is a table summarizing the available scripts in the project:

Script	Description
npm run build	Runs all build-related tasks.
npm run build:icons	Generates icons for the project.
npm run build:remix	Builds the Remix application using Vite.
npm run build:server	Builds the server files.
npm run predev	Prepares the environment before starting development (e.g., generates icons).
npm run dev	Starts the development server.
npm run prisma:studio	Launches the Prisma Studio UI for database management.
npm run format	Formats the codebase using Prettier.
npm run lint	Lints the codebase using ESLint.
npm run setup	Runs setup tasks including building, migrations, and Playwright setup.
npm run start	Starts the application in production mode.
npm run start:mocks	Starts the application with mock data in production mode.
npm run test	Runs unit tests and builds the Python rules engine.
npm run buildpy	Builds the Python rules engine and copies it to the public/pyodide-env folder.
npm run coverage	Runs tests and generates a coverage report.
npm run test:e2e	Runs end-to-end tests interactively.
npm run test:e2e:run	Runs end-to-end tests in CI mode.
npm run test:e2e:install	Installs dependencies for Playwright end-to-end tests.
npm run typecheck	Checks TypeScript types.
npm run validate	Validates the project by running linting, type-checking, and testing.

---

Epic Stack Docs:

The Epic Stack 🚀

Ditch analysis paralysis and start shipping Epic Web apps.

This is an opinionated project starter and reference that allows teams to ship their ideas to production faster and on a more stable foundation based on the experience of Kent C. Dodds and contributors.

npx create-epic-app@latest

The Epic Stack

---

Watch Kent's Introduction to The Epic Stack

"The Epic Stack" by Kent C. Dodds

Docs

Read the docs
(please 🙏).

Support

• 🆘 Join the
  discussion on GitHub
  and the KCD Community on Discord.
• 💡 Create an
  idea discussion
  for suggestions.
• 🐛 Open a GitHub issue to
  report a bug.

Branding

Want to talk about the Epic Stack in a blog post or talk? Great! Here are some
assets you can use in your material:
EpicWeb.dev/brand

Thanks

You rock 🪨