Skip to content

AGENTS.md

Latest commit

 

History

History
140 lines (108 loc) · 6.03 KB

AGENTS.md

File metadata and controls

140 lines (108 loc) · 6.03 KB

AGENTS.md

This file provides context for AI agents working with the Socialify codebase.

⚠️ CRITICAL: Read CONTRIBUTING.md First

BEFORE making ANY code changes, you MUST read CONTRIBUTING.md to understand:

  • Documentation requirements (all changes must update relevant docs)
  • Required commit message format (gitmoji-style)
  • Changeset requirements (every PR needs one, generate summary/description without user input)
  • Testing requirements (pnpm verify before committing)
  • Code style (Biome linter/formatter)

Failure to follow CONTRIBUTING.md will result in rejected PRs.

Project Overview

Socialify is an open-source service that generates beautiful social preview images for GitHub repositories. It allows users to create customized images with options for logos, descriptions, badges, fonts, and background patterns.

  • Live Site: https://socialify.git.ci
  • Tech Stack: Next.js 16, React 19, TypeScript, Tailwind CSS, daisyUI
  • Image Generation: Satori (SVG) + resvg-wasm (PNG/JPEG/WebP)
  • Package Manager: pnpm
  • Node Version: 24 (see .nvmrc)

Project Structure

socialify/
├── app/                    # Next.js App Router pages and API routes
│   ├── [_owner]/           # Dynamic routes for /:owner/:repo
│   ├── api/                # API endpoints for image generation
│   └── layout.tsx          # Root layout with providers
├── src/
│   ├── components/         # React UI components
│   ├── contexts/           # React context providers
│   ├── hooks/              # Custom React hooks
│   └── typings/            # TypeScript type definitions
├── common/                 # Shared utilities and business logic
│   ├── github/             # GitHub API integration
│   ├── icons/              # Language/tech icons for images
│   ├── types/              # Shared TypeScript types
│   ├── renderCard.ts       # Card rendering logic
│   ├── renderSVG.tsx       # SVG generation with Satori
│   └── renderPNG.tsx       # PNG conversion with resvg-wasm
├── public/                 # Static assets (wasm files copied here)
├── .devcontainer/          # VS Code Dev Container configuration
├── .github/skills/         # AI skills for repo-specific workflows
├── .github/workflows/      # CI/CD workflows (build, test, release, docker)
└── .changeset/             # Changeset files for versioning

Development Workflow

Before making changes:

  1. ✅ Read CONTRIBUTING.md (if not already done)
  2. ✅ Understand the requirements and conventions
  3. ✅ Make your changes following code style guidelines

Before committing:

  1. ✅ Run pnpm verify (runs lint, tests, and build)
  2. ✅ Create a changeset: pnpm changeset
  3. ✅ Use gitmoji-style commit messages (e.g., ✨ Add feature, 🐛 Fix bug, 📝 Update docs)
  4. ✅ Commit both your changes AND the changeset file

Contributing

See CONTRIBUTING.md for full details.

Key Commands

pnpm install              # Install dependencies
pnpm dev                  # Start development server
pnpm build                # Production build
pnpm lint                 # Run Biome linter
pnpm lint:fix             # Auto-fix lint issues
pnpm test:unit            # Run Jest unit tests
pnpm test:e2e             # Run Playwright e2e tests
pnpm changeset            # Create a changeset for PR
pnpm verify               # Run all checks (lint, tests, build)

Environment Variables

Copy .env.example to .env and configure:

  • GITHUB_TOKEN - GitHub PAT with public repo read access (required)
  • PROJECT_URL - Base URL (default: http://localhost:3000)
  • GTM_ID - Google Tag Manager ID (optional)

Development Guidelines

Code Style

  • Linter/Formatter: Biome (not ESLint/Prettier)
  • Import Aliases: Use @/ for imports (e.g., @/components/...)
  • Styling: Tailwind CSS with daisyUI components

AI Skills

  • /.github/skills/add-icon/ - Add or update supported language, framework, library, tool, or platform icons in Socialify. Use when a request involves adding a new icon/logo, mapping a display name to a Simple Icons entry or a custom icon, and updating the language options list used in the UI.
  • /.github/skills/frontend-design/ - Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when building web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
  • /.github/skills/upgrade-simple-icons/ - Upgrade the simple-icons dependency and preserve icons that are no longer available via custom mappings.

Testing

  • Unit Tests: Jest with React Testing Library
  • E2E Tests: Playwright (Chromium)
  • Update snapshots: pnpm test:unit:update-snapshots / pnpm test:e2e:update-snapshots

Pull Requests

  • Every PR requires a changeset file (run pnpm changeset)
  • CI runs lint, unit tests, and build checks
  • E2E tests run on PR merges

Documentation

  • IMPORTANT: All work must include updates to relevant documentation (README, AGENTS.md, code comments, etc.) to ensure docs stay current.

API Routes

  • GET /:owner/:repo/image - Returns generated social image (SVG/PNG/JPEG/WebP)
  • GET /api/stats.svg - Returns usage statistics badge

Image URL Parameters

Common query parameters for image customization:

  • theme - Light/Dark/Auto
  • font - Font family selection
  • pattern - Background pattern
  • logo - Custom logo URL (SVG data URI)
  • description - Toggle description visibility
  • language - Toggle language badge
  • stargazers, forks, issues, pulls - Toggle badges
  • owner - Toggle owner visibility

Related Documentation