Megapay HR Docs

Appearance

Getting Started ​

Set up your local development environment for Megapay HR.

Prerequisites ​

  • Node.js 18+
  • pnpm package manager
  • Git for version control

Installation ​

First, clone the repository and install dependencies:

bash
# Clone the repository
git clone <repository-url>
cd megapay-hr

# Install all dependencies
pnpm install

Why pnpm?

This project uses pnpm for faster installs and better disk space efficiency. If you don't have pnpm installed, run npm install -g pnpm.

Development Setup ​

Choose one of two development modes based on your needs:

Best for working on frontend features without setting up the full backend infrastructure.

1. Create environment file:

Create a .env file in the apps/frontend directory:

bash
# apps/frontend/.env
API_BASE_URL=https://api.dev.megapayapp.com

2. Start the development server:

bash
cd apps/frontend
pnpm run dev

The frontend will be available at http://localhost:3000 and will connect to the development API.

Hot Reload

The dev server supports hot module replacement (HMR) - your changes will appear instantly without refreshing.

Option 2: Full Stack with SST (For Backend Development) ​

Best for working on backend features or testing full-stack changes locally.

1. Set up AWS credentials:

Create or update your AWS credentials file. The exact location depends on your needs:

bash
# ~/.aws/credentials (for your personal dev environment)
[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY

Or create a credentials file specific to this project (check with your team for the correct path).

2. Start SST development mode:

From the root directory:

bash
npx sst dev

This will:

  • Deploy backend resources to AWS
  • Start the frontend dev server
  • Set up live Lambda development
  • Connect everything together

First Run

The first npx sst dev run takes longer as it deploys all infrastructure. Subsequent runs are much faster.

Verify Installation ​

Once your dev server is running, verify everything works:

  1. Open http://localhost:3000 in your browser
  2. You should see the Megapay HR login page
  3. Try navigating to a few pages to ensure routing works

Development Workflow ​

Frontend-Only Mode ​

bash
# Terminal 1: Run frontend dev server
cd apps/frontend
pnpm run dev

# Make changes to files in apps/frontend/app/
# Browser will auto-reload with your changes

Full Stack Mode ​

bash
# Terminal 1: Run SST
npx sst dev

# SST will show you URLs for:
# - Frontend (usually http://localhost:3000)
# - Backend API endpoints
# - AWS resources being used

Common Commands ​

bash
# Install dependencies
pnpm install

# Frontend only
cd apps/frontend
pnpm run dev        # Start dev server
pnpm run build      # Build for production
pnpm run preview    # Preview production build

# Backend (from root)
cd apps/backend
pnpm run build      # Compile TypeScript

# Full stack (from root)
npx sst dev         # Start development
npx sst deploy      # Deploy to AWS
npx sst remove      # Remove deployment

Project Structure ​

megapay-hr/
├── apps/
│   ├── frontend/       # Nuxt 3 frontend application
│   ├── backend/        # Backend API (Hono + Drizzle)
│   ├── docs/           # This documentation site
│   └── dbSeeding/      # Database seeding scripts
├── infra/              # SST infrastructure definitions
└── packages/           # Shared packages

IDE Setup ​

Install these extensions for the best experience:

  • Vue - Official (Vue.js language support)
  • TypeScript Vue Plugin (Volar) (TypeScript support in Vue files)
  • Tailwind CSS IntelliSense (Tailwind autocomplete)
  • ESLint (Linting)

WebStorm ​

WebStorm has built-in support for Vue, TypeScript, and Tailwind. No additional plugins needed.

Environment Variables ​

Frontend Environment Variables ​

Create apps/frontend/.env:

bash
# Required for frontend-only mode
API_BASE_URL=https://api.dev.megapayapp.com

# Optional
NUXT_PUBLIC_API_BASE_URL=https://api.dev.megapayapp.com

Don't Commit .env

The .env file is gitignored. Never commit credentials or API keys.

Troubleshooting ​

Port Already in Use ​

If port 3000 is already in use:

bash
# Option 1: Kill the process using the port
lsof -ti:3000 | xargs kill -9

# Option 2: Use a different port
PORT=3001 pnpm run dev

pnpm install fails ​

bash
# Clear pnpm cache
pnpm store prune

# Remove node_modules and try again
rm -rf node_modules
pnpm install

SST deployment fails ​

bash
# Check AWS credentials are set correctly
aws sts get-caller-identity

# Remove .sst directory and try again
rm -rf .sst
npx sst dev

TypeScript errors in IDE ​

bash
# Restart TypeScript server in VS Code
# Command Palette (Cmd+Shift+P) > "TypeScript: Restart TS Server"

# Or regenerate types
cd apps/frontend
pnpm run dev  # Types are generated on dev server start

Next Steps ​

Now that your environment is set up, learn about:

Ready to code? Start with the Folder Structure guide to understand how the project is organized.