How to Deploy & Use cjbarber/ToolsOfTheTrade

# ToolsOfTheTrade Deployment & Usage Guide

## Prerequisites

**Runtime Environment**
- **Node.js**: v18.x LTS or higher (tested on v20.11.0)
- **Git**: v2.40+ for submodules if using curated data forks
- **Package Manager**: npm (v9+) or pnpm (recommended)

**System Requirements**
- OS: Linux/macOS/Windows (WSL2 preferred for Windows)
- Memory: 4GB RAM minimum for build process
- Disk: 2GB free space for `node_modules` and build cache

**Accounts & Keys** (only if deploying with HN API sync)
- Hacker News API key (optional, for automated refresh scripts)
- Algolia Search API key (if using search functionality)

## Installation

**1. Clone the repository**
```bash
git clone https://github.com/cjbarber/ToolsOfTheTrade.git
cd ToolsOfTheTrade

2. Install dependencies

# Using pnpm (fastest)
pnpm install

# Or npm
npm ci

3. Verify environment

node --version  # Should print v18.x or higher
npm --version   # Should print 9.x or higher

Configuration

Environment Variables Copy the example environment file and configure:

cp .env.example .env.local

Edit .env.local:

# Optional: For HN data sync scripts
HN_API_KEY=your_hackernews_api_key_here

# Optional: Algolia search (if using search index)
NEXT_PUBLIC_ALGOLIA_APP_ID=your_app_id
ALGOLIA_ADMIN_KEY=your_admin_key

# Site configuration
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Config Files

• next.config.js — Next.js configuration (static export settings, image optimization)
• tailwind.config.ts — Theme customization (colors, fonts for the tools grid)
• data/tools.json — Curated list data source (edit to add new tools)

Build & Run

Development Mode (with hot reload)

npm run dev
# Server starts at http://localhost:3000

Production Build (local testing)

npm run build
npm start
# Serves optimized build at http://localhost:3000

Static Export (for GitHub Pages/Netlify drop)

npm run build
# Outputs to ./dist or ./out directory (check next.config.js)

Data Refresh (if updating from HN threads)

npm run sync:hn
# Fetches latest tools from configured HN threads

Deployment

Vercel (Recommended) Zero-config deployment for Next.js:

npm i -g vercel
vercel --prod

Environment variables are auto-detected from .env.local during vercel env pull.

Netlify

1. Build settings:
   • Build command: npm run build
   • Publish directory: dist (or out depending on next.config.js)
2. Environment variables: Add HN_API_KEY in Netlify UI → Site settings → Environment variables
3. Deploy hook: Configure GitHub integration for auto-deploy on push to main

GitHub Pages (Static)

# Ensure next.config.js has: output: 'export'
npm run build
git subtree push --prefix dist origin gh-pages

Or use GitHub Actions workflow (.github/workflows/deploy.yml):

- run: npm ci
- run: npm run build
- uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./out

Docker (Self-hosted)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Build and run:

docker build -t tools-of-trade .
docker run -p 3000:3000 --env-file .env.local tools-of-trade

Troubleshooting

Build fails with "Module not found"

• Ensure you're in the project root (not a subdirectory)
• Delete node_modules and lock file: rm -rf node_modules package-lock.json && npm install

Port 3000 already in use

# Kill process on port 3000 (macOS/Linux)
lsof -ti:3000 | xargs kill -9
# Or use different port
npm run dev -- --port 3001

Static export fails with "Image optimization" error

• Edit next.config.js: Set images: { unoptimized: true } for static hosting
• Or use next/image with loader: 'custom' configured

HN API rate limiting (429 errors)

• Add delay between requests in scripts/sync-hn.js: await new Promise(r => setTimeout(r, 1000))
• Use Algolia HN Search API instead (higher limits): https://hn.algolia.com/api/v1/search

Environment variables not loading

• Ensure .env.local is in project root (not in src/)
• Restart dev server after editing env files (hot reload doesn't pick up env changes)
• Check file encoding: must be UTF-8 without BOM