Skip to content

getting-started.md

Latest commit

 

History

History
182 lines (123 loc) · 4 KB

getting-started.md

File metadata and controls

182 lines (123 loc) · 4 KB

Getting Started

This guide walks you through setting up PRFC Connect for local development.

Prerequisites

Install fnm

fnm manages Node.js versions. It reads the .nvmrc file and switches to the correct version automatically.

macOS/Linux:

curl -fsSL https://fnm.vercel.app/install | bash

Windows:

winget install Schniz.fnm

After installing, restart your terminal and enable auto-switching:

# Add to your shell profile (.bashrc, .zshrc, etc.)
eval "$(fnm env --use-on-cd)"

Setup

1. Clone the Repository

git clone https://github.com/hack4impact-calpoly/prfc-connect.git
cd prfc-connect

2. Install Node.js

fnm will read .nvmrc and install the correct version.

fnm install
fnm use

Verify you're on the right version:

node -v  # Should show v22.x

3. Install Dependencies

npm install

4. Start the Database

Start MySQL using Docker:

npm run docker:up

This starts MySQL on port 3306 and Adminer (database UI) on port 8080.

5. Set Up Environment Variables

Copy the example file and get secrets from a tech lead:

cp .env.local.example .env.local

Required variables:

  • DATABASE_URL - MySQL connection string
  • SMTP settings for email

Optional (for production):

  • PRFC_PORTAL_SECRET - Shared HMAC secret with PRFC portal (uses dev fallback locally)

6. Run Migrations

Set up the database schema:

npx prisma migrate dev

7. Start the App

npm run dev

Visit http://localhost:3000. You should see the referral form.

To access protected pages (like the referral database), use the mock portal at http://localhost:3000/dev/mock-portal. This simulates the PRFC member portal login flow.

IDE Setup

Install these VS Code extensions:

Enable format on save:

  1. Open Settings (Cmd/Ctrl + ,)
  2. Search "default formatter" -> select Prettier
  3. Search "format on save" -> check the box

Helpful Commands

Development:

  • npm run dev - Start dev server at localhost:3000
  • npm run build - Build for production
  • npm run lint - Check code style
  • npm run lint:fix - Auto-fix style issues
  • npm test - Run tests

Database:

  • npm run docker:up - Start MySQL container
  • npm run docker:down - Stop MySQL container
  • npm run db:seed - Populate test data
  • npx prisma studio - Open database GUI
  • npx prisma migrate dev - Run migrations

Project Structure

prfc-connect/
├── .github/           # GitHub Actions and templates
├── docs/              # Documentation
├── prisma/            # Database schema and migrations
├── public/            # Static assets
├── src/
│   ├── app/           # Next.js pages and API routes
│   ├── actions/       # Server Actions
│   ├── components/    # React components
│   ├── hooks/         # Custom React hooks
│   ├── lib/           # Utilities (db, dal, rate-limit)
│   ├── schema/        # Zod validation schemas
│   ├── services/      # Business logic
│   └── utils/         # Helper functions
└── test/              # Test files

Troubleshooting

Port 3306 already in use: Stop any existing MySQL process or change the port in docker-compose.yml.

Prisma client errors: Regenerate the client:

npx prisma generate

Node version mismatch: Make sure fnm is using the correct version:

fnm use

Next Steps

Once your environment is running, read Contributing to learn the development workflow.