Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
163 lines (115 loc) · 5.33 KB

DEVELOPMENT.md

File metadata and controls

163 lines (115 loc) · 5.33 KB
Raw

Development Guide

Quick reference for developing this Next.js personal website.

Installation

This project uses proto to pin tool versions.

proto install          # installs Node.js, pnpm, Lefthook, Ruff
pnpm install
lefthook install       # sets up Git hooks (skip in CI)

Development

pnpm dev  # Starts dev server + translation watcher

Runs at http://localhost:8825

Key Commands

Command Purpose
pnpm dev Start dev server with translation watcher
pnpm build Production build
pnpm lint Run Biome linter
pnpm lint:fix Fix auto-fixable issues
pnpm typecheck Check TypeScript types
pnpm generate Generate translation files
pnpm print-cv Generate CV PDF
pnpm format:py Format Python CI helpers with Ruff
pnpm format:py:check Check Python formatting (CI parity)
pnpm check Run all quality gates (lint, typecheck, spellcheck, test, build)
pnpm test Run unit tests (vitest)
pnpm deploy Reminder: deployments run on release

Development Flow

  1. Code → Make changes
  2. Verify → pnpm check (runs all gates)
  3. Commit → Conventional Commits with scope (see below)
  4. Deploy → merge to release (deployment workflow runs automatically)

Commit Convention

Use Conventional Commits with scope:

feat(cv): add PDF download button
fix(i18n): correct Spanish translation for contact page
refactor(styles): extract shared font constants
chore(ci): add dependency audit step
docs(dev): update development flow
perf(analytics): reduce GA loader timeout

Scopes: cv, i18n, styles, ci, components, analytics, a11y, seo, deps, dev

Key Concepts

Translations

  • Source files: src/i18n/
  • Auto-generated during pnpm dev
  • Manual regeneration: pnpm generate
  • Uses typesafe-i18n for type safety

CV PDF Generation

  • Route: /cv (print-optimized page)
  • Script: scripts/print-cv.js
  • Output: local/Marco Toniut (CV).pdf
  • Requires Chrome: npx puppeteer browsers install chrome

Styling

  • Uses Vanilla Extract (.css.ts files)
  • Colocated with components
  • Type-safe CSS-in-JS

Tech Stack

  • Framework: Next.js 16 (App Router)
  • Language: TypeScript (British English conventions)
  • Styling: Vanilla Extract
  • UI: Radix UI primitives
  • Translations: typesafe-i18n
  • Deployment: GitHub Pages

Project Structure

src/
├── app/          # Next.js routes & layouts
├── components/   # UI components + styles
├── i18n/         # Translation source files
└── styles/       # Global styles

docs/
└── decisions/    # Architecture Decision Records

scripts/          # Utility scripts

Quality Checks

Before committing:

pnpm lint:fix && pnpm typecheck && pnpm build
pnpm format:py

Run pnpm format:py:check (or rely on CI) whenever Python helper scripts change; Ruff is installed via proto for consistent local/CI formatting.

SEO & Anti-AI Scraping

This site implements comprehensive SEO optimization with anti-AI training protection.

Implementation

  • robots.txt — Blocks AI crawlers (OpenAI, Anthropic, Google Extended, CCBot, etc.)
  • sitemap.xml — Auto-generated on build via pnpm generate:sitemap
  • Pre-push hook reruns pnpm generate:sitemap only when pushing the release branch and blocks the push if public/sitemap.xml changes. Commit the regenerated file whenever the date or routes change to unblock release pushes. A matching GitHub workflow enforces the same rule on PRs targeting release.
  • Schema.org JSON-LD — Structured data in src/app/layout.tsx
  • OpenGraph & Twitter Cards — Social media metadata via src/utils/metadata.ts
  • Anti-AI Meta Tags — noai, noimageai, nocontentai in page metadata
  • Footer Legal Notice — src/components/Footer.tsx

Verification

Test robots.txt and sitemap are accessible:

curl https://marcotoniut.github.io/robots.txt
curl https://marcotoniut.github.io/sitemap.xml

Limitations

  • GitHub Pages doesn't support HTTP headers — Headers configured in next.config.js are ignored on static hosting
  • Meta tags provide equivalent protection for compliant crawlers
  • Cannot block non-compliant bots that ignore robots.txt

Blocked Crawlers

GPTBot, ChatGPT-User, Google-Extended, ClaudeBot, CCBot, PerplexityBot, FacebookBot, Bytespider, cohere-ai, Diffbot, omgili

Deployment

Deploy to GitHub Pages:

# Push or merge to the release branch
git push origin release

The GitHub Actions workflow (Deploy Next.js site to Pages) runs automatically on the release branch, building the static export and publishing it to Pages with the environment-provided analytics credentials.

The site is available at https://marcotoniut.github.io