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:

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

Before committing:

✅ Run
```
pnpm verify
```
(runs lint, tests, and build)
✅ Create a changeset:
```
pnpm changeset
```
✅ Use gitmoji-style commit messages (e.g.,
```
✨ Add feature
```
,
```
🐛 Fix bug
```
,
```
📝 Update docs
```
)
✅ 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

.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

README.md - User documentation and usage guide
CONTRIBUTING.md - Contribution guidelines and development setup
CODE_OF_CONDUCT.md - Community code of conduct
CHANGELOG.md - Version history and release notes

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

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:

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

Before committing:

✅ Run
```
pnpm verify
```
(runs lint, tests, and build)
✅ Create a changeset:
```
pnpm changeset
```
✅ Use gitmoji-style commit messages (e.g.,
```
✨ Add feature
```
,
```
🐛 Fix bug
```
,
```
📝 Update docs
```
)
✅ 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

.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

README.md - User documentation and usage guide
CONTRIBUTING.md - Contribution guidelines and development setup
CODE_OF_CONDUCT.md - Community code of conduct
CHANGELOG.md - Version history and release notes

AGENTS.md

AGENTS.md

⚠️ CRITICAL: Read CONTRIBUTING.md First

Project Overview

Project Structure

Development Workflow

Contributing

Key Commands

Environment Variables

Development Guidelines

Code Style

AI Skills

Testing

Pull Requests

Documentation

API Routes

Image URL Parameters

Related Skills

Markdown Converter

Nano Banana Pro

1password

AGENTS.md

⚠️ CRITICAL: Read CONTRIBUTING.md First

Project Overview

Project Structure

Development Workflow

Contributing

Key Commands

Environment Variables

Development Guidelines

Code Style

AI Skills

Testing

Pull Requests

Documentation

API Routes

Image URL Parameters