Skip to main content

​
Overview

Adding a new company to Who To Bother involves creating a JSON file with contact information, adding the company logo, and validating the data. This guide walks you through each step.

​
Quick Start

1

Create the JSON file

Create a new file in src/data/companies/ with your company’s name (lowercase, hyphenated):
touch src/data/companies/yourcompany.json
2

Add company data

Populate the file with your company’s information following the schema structure.
3

Add the logo

Add your company’s SVG logo to src/components/company-logos.tsx
4

Validate and test

Run validation and test locally:
pnpm validate
pnpm dev

​
Company JSON Structure

Each company is represented by a JSON file following this structure:
src/data/companies/yourcompany.json
{
  "$schema": "./schema.json",
  "id": "yourcompany",
  "name": "Your Company",
  "description": "Brief description of what your company does",
  "logoType": "yourcompany",
  "categories": [
    {
      "name": "Category Name",
      "contacts": [
        {
          "product": "Product or Role",
          "handles": ["@twitter_handle"],
          "email": "[email protected]"
        }
      ]
    }
  ]
}
The $schema property enables IDE autocomplete and validation hints. Always include it at the top of your JSON file.

​
Field Descriptions

​
Required Fields

​
id
string
required
Unique identifier for the company (lowercase, alphanumeric with hyphens only)
  • Must match the filename (without .json)
  • Used to generate the route: /yourcompany
  • Example: "vercel", "tanstack", "google-ai-studio"
​
name
string
required
The display name of the company
  • This is what users will see in the UI
  • Can include spaces and proper capitalization
  • Example: "Vercel", "TanStack", "Google AI Studio"
​
description
string
required
Brief description of what the company does
  • Keep it concise (1-2 sentences)
  • Helps users understand what the company offers
  • Example: "Frontend cloud platform for deploying web applications"
​
logoType
string
required
Key used to lookup the logo in company-logos.tsx
  • Must match a key in the companyLogos object
  • Usually the same as the id field
  • Example: "vercel", "tanstack"
​
categories
array
required
Array of category objects grouping related contacts
  • At least one category is required
  • Each category groups contacts by product, team, or area
  • Example categories: "Frameworks & OSS", "Vercel products", "v0 & AI"

​
Category Structure

​
name
string
required
The name of the category
  • Groups related contacts together
  • Examples: "Engineering", "Support", "Community"
​
contacts
array
required
Array of contact objects
  • At least one contact is required per category
  • Each contact represents a person or team

​
Contact Structure

​
product
string
required
The product, role, or area this contact is responsible for
  • Examples: "Next.js", "Customer Support", "Community Manager"
​
handles
array
required
Array of Twitter/X handles
  • Must start with @
  • Can only contain letters, numbers, and underscores
  • At least one handle is required
  • Example: ["@timneutkens"], ["@shadcn", "@rauchg"]
​
email
string
Email address for contact (optional)
  • Must be a valid email format
  • Only include publicly available emails
  • Example: "[email protected]"
​
discord
string
Discord invite URL (optional)
  • Must be a valid URL
  • Example: "https://discord.gg/yourserver"

​
Optional Company Fields

URL to external logo image (optional)
  • Alternative to using logoType
  • Must be a valid URL
​
website
string
Company website URL (optional)
  • Must be a valid URL
  • Example: "https://vercel.com"
​
docs
string
Documentation URL (optional)
  • Must be a valid URL
  • Example: "https://nextjs.org/docs"
​
github
string
GitHub organization or repository URL (optional)
  • Must be a valid URL
  • Example: "https://github.com/vercel"
​
discord
string
Discord server invite URL (optional)
  • Must be a valid URL
  • Example: "https://discord.gg/vercel"

​
Real Example

Here’s a real example from the Vercel company file:
src/data/companies/vercel.json
{
  "$schema": "./schema.json",
  "id": "vercel",
  "name": "Vercel",
  "description": "Frontend cloud platform for deploying web applications",
  "logoType": "vercel",
  "categories": [
    {
      "name": "Frameworks & OSS",
      "contacts": [
        { "product": "Next.js", "handles": ["@timneutkens"] },
        { "product": "Turbopack", "handles": ["@timneutkens"] },
        { "product": "Turborepo", "handles": ["@anthonysheww"] },
        { "product": "shadcn/ui", "handles": ["@shadcn"] }
      ]
    },
    {
      "name": "Vercel products",
      "contacts": [
        { "product": "Domains", "handles": ["@RhysSullivan", "@ethanniser"] },
        { "product": "Functions / Runtime / Compute", "handles": ["@tomlienard", "@dglsparsons"] },
        { "product": "Image Optimization", "handles": ["@styfle"] }
      ]
    }
  ]
}

​
Best Practices

Organize contacts logically: Group contacts by product area, team, or function to make it easier for users to find the right person.

​
Handles and Emails

Only include public contact information: Make sure all Twitter/X handles and email addresses are publicly available or you have explicit permission to include them.
  • Handles: Only include people who are comfortable being contacted
  • Email addresses: Only include publicly available emails (from websites, public profiles, etc.)
  • Verify accuracy: Double-check that handles are correct and active

​
Descriptions

  • Keep descriptions concise and informative
  • Focus on what the company does, not marketing speak
  • Examples:
    • Good: "Frontend cloud platform for deploying web applications"
    • Bad: "The world's best and most innovative cloud platform that revolutionizes..."

​
Categories

  • Use clear, descriptive category names
  • Group related contacts together
  • Common categories:
    • By product: "Next.js", "v0 & AI"
    • By team: "Engineering", "Support"
    • By area: "Community", "OSS Projects"

​
Validation

Before submitting your changes, validate your JSON file: 
pnpm validate
The validation script will check:
All required fields are present
Twitter/X handles follow the correct format (@username)
Email addresses are valid (if provided)
URLs are valid (if provided)
Company ID uses only lowercase letters, numbers, and hyphens
At least one category and contact per company

​
Common Validation Errors

Error: Handle must start with @ and contain only letters, numbers, and underscoresSolution: Make sure all handles start with @ and don’t contain spaces or special characters:
// ❌ Wrong
"handles": ["timneutkens", "@user name", "@user-name"]

// ✅ Correct
"handles": ["@timneutkens", "@username"]
Error: Company ID is required or similarSolution: Make sure all required fields are present:
  • id
  • name
  • description
  • logoType
  • categories (with at least one category)
  • Each category must have name and contacts
  • Each contact must have product and handles
Error: Must be a valid email addressSolution: Check that email addresses are properly formatted:
// ❌ Wrong
"email": "not-an-email"

// ✅ Correct
"email": "[email protected]"
Error: Company ID must be lowercase with only letters, numbers, and hyphensSolution: Use lowercase letters, numbers, and hyphens only:
// ❌ Wrong
"id": "YourCompany", "id": "your_company"

// ✅ Correct
"id": "yourcompany", "id": "your-company"

​
Testing Locally

After creating your company file, test it locally: 
pnpm dev
Navigate to http://localhost:3000/yourcompany to see your company page.
The company ID (filename without .json) becomes the route path automatically.

​
Next Steps

Once you’ve created your company JSON file:
  1. Add your company logo to company-logos.tsx
  2. Validate your changes with pnpm validate
  3. Test locally with pnpm dev
  4. Submit a Pull Request

Add Logos

Learn how to add your company logo

Schema Validation

Deep dive into schema validation

Build docs developers (and LLMs) love

Get started for freeTalk to us