finance/ENVIRONMENT_SETUP.md

Development Environment Setup Guide

Prerequisites

• Windows, macOS, or Linux
• Git
• Node.js (version 18 or higher)
• npm or yarn
• PostgreSQL (local installation or Docker)

Initial Setup

1. Clone the Repository

   git clone https://github.com/acedanger/finance.git
   cd finance
   

2. Install Dependencies

   npm install
   

3. Create Environment File

   cp .env.example .env
   

4. Configure Database

   • Edit the .env file with your PostgreSQL connection string:

     DATABASE_URL="postgresql://username:password@localhost:5432/finance"
     

5. Set up Database

   # Run database migrations
   npx prisma migrate dev
   
   # Seed the database with initial data (optional)
   npx prisma db seed
   

Git Hooks

This project uses Git hooks via Husky to enforce code quality:

1. Pre-commit Hook:
   • Automatically runs Biome checks before each commit
   • Prevents committing code with linting or formatting errors
   • See HOOKS.md for more details and usage instructions

Pre-commit Hooks

The project uses Git hooks to enforce code quality standards automatically when committing changes.

Setup

Husky is used to manage Git hooks and is automatically installed and configured when you run npm install. No manual setup is required.

Available Hooks

1. pre-commit: Runs before each commit to ensure code quality
   • Runs Biome.js to check and auto-fix formatting and path alias usage
   • Runs TypeScript type checking
   • Auto-stages files fixed by Biome.js

Bypassing Hooks

In rare cases, you may need to bypass the pre-commit hooks:

git commit --no-verify -m "Your commit message"

⚠️ Note: Only bypass hooks when absolutely necessary and ensure code quality manually.

Troubleshooting

If the pre-commit hook fails:

1. Review the error messages in the console
2. Fix the reported issues
3. Stage your changes again
4. Retry the commit

For hook execution issues:

# Reinstall husky hooks
npm run prepare

Environment Configuration

The project uses an .env file for configuration:

• Application-specific configuration
• Database connection string
• Development server port
• API base URL
• Node environment

Troubleshooting

Database Issues

• Ensure PostgreSQL is running
• Check that your database connection string is correct in .env
• Try resetting the database: npx prisma migrate reset

Build Issues

• Clear node_modules and reinstall: Remove-Item -Recurse -Force node_modules; npm install
• Check that all environment variables are set correctly
• Ensure you have the correct Node.js version installed

Common Operations

Starting Development Server

npm run dev