GTD XXVI Website

Table of Content

• Project Setup
  • Prerequisites
  • Setting Up
  • Additional Tools
    • Prisma Studio
    • Stripe CLI
    • Brevo SMTP
• Workflow
  • Git & GitHub
  • Style Guide
  • Project Structure
• Troubleshooting
  • Merge conflicts in pnpm-lock.yaml
  • Access the Dashboard
  • Error running development server or husky
  • Database errors
  • Save storage space
• Packages Usage
  • tRPC
    • In Server Components
    • In Client Components
  • Day.js
  • Sharp CLI
• Learn More

Project Setup

Prerequisites

1. Install Node Version Manager (NVM). Installation: macOS/Linux, Windows.
2. Install Node.js Iron (LTS):

# For macOS/Linux
nvm install --lts=iron
nvm use --lts=iron

# For Windows
nvm install lts
nvm use lts

3. Install pnpm using Corepack (or alternatively, using npm):

corepack enable pnpm

4. Install Docker. Installation: macOS, Linux, Windows.

Setting Up

1. Install dependencies:

pnpm install

2. Copy .env.example contents to .env.development.local and fill the environment variables (instructions inside file):

# For macOS/Linux
cp .env.example .env.development.local

# For Windows
copy .env.example .env.development.local

3. Start the development database:

pnpm dev:db:start

4. Initialize the development database with sample data:

pnpm dev:db:reset

5. Run the development server:

pnpm dev

6. Open http://localhost:3000 with your browser to see the result.

Additional Tools

Prisma Studio

See development database contents:

pnpm dev:db:studio

Stripe CLI

Listen for Stripe events and trigger webhooks in development environment:

1. Sign up for a Stripe account or sign in to your Stripe account. No need to activate payments.
2. Add your API secret key and publishable key to .env.development.local.
3. Setup 2FA for your Stripe account and generate a restricted key.
4. Setup Stripe CLI for development.
5. Run the Stripe CLI:

pnpm dev:stripe

Brevo SMTP

Send emails:

1. Sign up for a Brevo account.
2. Go here to create an API key and add it to .env.development.local.

Workflow

Git & GitHub

1. Create new feature branch with the following format name/feature and push the new branch to remote (this repository):

git checkout -b bob/leaderboard-router
git push -u origin bob/leaderboard-router

2. Stage changes, commit on your feature branch, and push to remote (note: do not commit on main branch):

git add .
git commit -m "feat: add leaderboard router"
git push

Style Guide

• Use kebab case to name files, e.g., leaderboard-router.ts
• Use kebab case + full component name for component files, e.g., button-group-card.tsx for <ButtonGroupCard />
• Use import aliases instead of relative paths for package imports, e.g. import { Button } from "@/components/ui/button";
• Git commits style guide: Conventional Commits 1.0.0
• Use TypeScript types instead of interfaces unless necessary (why?)
• Use function declarations for React components and event handlers
  • Learn more: function declaration vs function expression vs arrow function

Project Structure

Path	Import Alias	Usage
src/app	@/app	Next.js App Router
src/app/_components	@/components	App-wide components
src/app/_components/ui	@/components/ui	Components scaffolded by shadcn/ui
src/lib	@/lib	Library/package-related files
src/server	@/server	Server-related files
src/assets	@/assets	App-wide assets
public	~/public	Public assets
emails	~/emails	React Email templates

Troubleshooting

Merge conflicts in pnpm-lock.yaml

1. pnpm can automatically resolve lockfile conflicts. Run:

pnpm install

2. Stage and commit the lockfile:

git add pnpm-lock.yaml
git commit -m "chore: resolve lockfile conflict"

Access the Dashboard

1. Sign up for a user at /dashboard/signup.
2. Open Prisma Studio:

pnpm dev:db:studio

3. Open the User Model:

4. Change the user's role to ADMIN:

5. Save changes in Prisma Studio.

6. Log in as the user at /dashboard/login. You should be able to access the dashboard now.

Error running development server or husky

1. Remove the .next folder:

rm -rf .next

2. Retry.

Database errors

1. Reset the development database by first removing the image:

docker image rm -f gtd-xxvi/db-dev

2. Remove the volume where the development database data is stored:

docker volume rm gtd-xxvi-db-pgdata-dev

3. Restart the development database:

pnpm dev:db:start

Save storage space

1. Remove unused packages:

pnpm prune

2. Remove unused and dangling Docker containers and images:

docker system prune

Packages Usage

tRPC

In Server Components

Use the tRPC client api defined in src/trpc/server. Example:

// example-page.tsx
import { api } from "@/server/trpc";

export default async function ExamplePage() {
  const event = await api.event.getById(1);
  return <main>{event?.name}</main>;
}

In Client Components

Use the tRPC client api defined in src/trpc/client. Example:

// example-page.tsx
"use client";

import { api } from "@/lib/trpc/provider";

export default function ExamplePage() {
  const { data: event } = api.event.getById.useQuery(1);
  return <main>{event?.name}</main>;
}

Day.js

Do:

• Use Day.js to parse, find difference, format, etc. Date to String

Don't:

• Use Day.js as prop/state. Use Date instead (dayjs().toDate())

Sharp CLI

Compress one image into .webp:

pnpm dlx sharp-cli -f webp --effort 6 -q 75 -i large-image.jpg -o {dir}

Compress all images in the current working directory into .webp:

pnpm dlx sharp-cli -f webp --effort 6 -q 75 -i ./* -o {dir}

More info: Sharp CLI documentation

Learn More

• Learning resources: github.com/GTD-IT-XXIV/gtd-xxvi-learning-resources
• Learning articles:
  • Making Sense of React Server Components
  • Server and Client Composition Patterns
• Official documentation: Tailwind CSS, shadcn/ui, Next.js, tRPC, Zod, Prisma