Create an apps.json File for World Vibe Web

To list your apps on wvw.dev, you need to create an apps.json file in a public GitHub repo and submit a pull request. You can prepare an apps.json file with FindUtils' WVW Apps.json Generator — a free visual form builder that handles formatting and a set of local validation checks.

This guide walks you through everything: what wvw.dev is, how the distributed app store works, the exact JSON schema you need, and how to review and submit your app records.

What Is World Vibe Web (wvw.dev)?

World Vibe Web is a distributed app store that aggregates vibe-coded projects from GitHub repositories. Unlike traditional app stores, WVW doesn't host your apps. Instead, developers maintain their own apps.json file, and WVW's build system pulls them all into a unified catalog every 6 hours.

The concept is simple:

• You control your listing — update your apps.json anytime, and WVW picks up changes automatically
• Source registration — submit a PR to stores.json, then check the merged source and catalog build
• Live stats — WVW fetches star counts and fork data directly from the GitHub API, instead of trusting manually declared counts
• Open source — built on Appetit, the standalone app store framework

WVW was created by the developer community for the developer community. If you've built something with vibe coding — whether it's a CLI tool, a web app, or a macOS utility — wvw.dev is where you list it.

The apps.json Schema Explained

Every apps.json file has three main sections: store metadata, categories, and apps.

{
  "$schema": "https://wvw.dev/apps.schema.json",
  "store": {
    "name": "My App Store",
    "developer": "Your Name",
    "tagline": "A short tagline",
    "github": "https://github.com/yourname"
  },
  "categories": [
    { "id": "web", "name": "Web Apps" },
    { "id": "cli", "name": "CLI Apps" }
  ],
  "apps": [
    {
      "id": "my-app",
      "name": "My App",
      "subtitle": "Short tagline",
      "description": "One-liner for search and cards",
      "category": ["web", "developer-tools"],
      "platform": "Web",
      "price": "Free",
      "github": "https://github.com/you/my-app"
    }
  ]
}

App Fields in This Example

Optional Fields That Make Your Listing Stand Out

Depending on the schema and application, you can also add longDescription, icon, iconEmoji, homepage, language, features, screenshots, brew, installCommand, and downloadUrl. Screenshots and feature lists can explain the app before a reader opens it.

Step-by-Step: Create Your apps.json with the Visual Builder

Step 1: Open the WVW Apps.json Generator

Go to FindUtils' WVW Apps.json Generator. The form builds JSON locally. Optional GitHub autofill makes a request to the GitHub API. The tool saves drafts in browser storage.

Step 2: Fill In Your Store Information

Enter your store name, developer name, optional tagline, and GitHub profile URL. This metadata appears at the top of your store page on wvw.dev.

Step 3: Add Your Apps One by One

Click "Add App" to open the app form dialog. Fill in the required fields (name, subtitle, description, platform, price, GitHub URL), and select categories from the 27 WVW-recognized options. The app ID is auto-generated from the name in kebab-case.

Expand the "Advanced Fields" section to add optional details like programming language, homepage URL, install commands, icon URL, and system requirements. Use the "Features" and "Screenshots" sections to add lists that enhance your detail page.

Pro tip: If you paste a GitHub URL first, click "Auto-fill from GitHub" to automatically pull the repo name, description, language, and homepage from the GitHub API.

Step 4: Review the Live JSON Preview

As you fill in fields, the JSON preview panel on the right (desktop) or the Preview tab (mobile) updates in real time. The output includes proper formatting, the $schema reference, and auto-computed categories based on your apps.

Step 5: Validate Your JSON

The Validation panel checks your apps.json against WVW rules: required fields, unique app IDs, valid category IDs, properly formatted URLs. Fix any red errors before exporting.

Step 6: Export and Download

Click "Copy JSON" or "Download apps.json" from the Export section. The tool also shows your stores.json entry and step-by-step submission instructions.

The builder's WVW category list

These are the categories bundled with the builder. Compare them with the current WVW category list. Apps with unrecognized categories have those categories stripped during the build. Apps with zero valid categories are excluded entirely.

The WVW Apps.json Generator only shows these 27 categories, but the published WVW list can change.

How to Submit Your apps.json to wvw.dev

Once your apps.json is ready:

1. Commit the file to the root of a public GitHub repository
2. Fork the f/wvw.dev repository
3. Add your repo to stores.json — just add "yourname/your-repo" to the array
4. Open a pull request — after merge, WVW fetches your apps every 6 hours

Your stores.json entry can be either a GitHub repo path (owner/repo) or a direct URL to your apps.json file.

WVW Guardrails: What You Should Know

WVW applies several guardrails during its build process:

• Stars and forks are overwritten — WVW fetches live counts from the GitHub API. You can't inflate your stats
• Featured apps are curated — your featured array is ignored; WVW maintainers control featured.json
• Category enforcement — only the 27 recognized categories survive the build
• Deduplication — if two repos use the same app id, only the first one is kept
• Owner attribution — every app gets a badge derived from the GitHub repo path, not from your JSON

What the builder checks

The builder reduces manual JSON editing. It cannot guarantee acceptance, global identifier uniqueness, or future compatibility with a changed WVW schema.

Common Mistakes When Creating apps.json

Mistake 1: Using Invalid Category IDs

WVW only recognizes 27 specific category IDs. Using "dev-tools" instead of "developer-tools" or "videos" instead of "photo-video" can leave the app without a recognized category. Compare the export with the current category list.

Mistake 2: Non-Unique App IDs

App IDs must be globally unique across all WVW stores. If someone else already has an app called my-tool, your app won't appear. Use specific, project-name-based IDs like janedev-my-tool.

Mistake 3: Setting Stars and Forks Manually

Any stars and forks values you declare are ignored — WVW overwrites them with live GitHub API data on every build. Don't waste time maintaining these.

Mistake 4: Forgetting the $schema Reference

Adding "$schema": "https://wvw.dev/apps.schema.json" enables editor validation and autocomplete in VS Code and other editors. The visual builder includes this automatically. Schema support depends on the editor, and a schema link alone does not validate the document.

Mistake 5: Not Adding Screenshots

Screenshots help readers inspect the app before opening it. Host them in your repo's docs/ folder and use raw.githubusercontent.com URLs.

Run Your Own Standalone Store

You don't have to submit to wvw.dev. You can run your own standalone store using Appetit:

git clone https://github.com/f/appetit.git my-store
cd my-store
# Replace apps.json with your own (use the visual builder to generate it)
python3 -m http.server 8080

Deploy to GitHub Pages, Netlify, Vercel, or any static host. It's just HTML, CSS, and JavaScript.

Tools Used in This Guide

• WVW Apps.json Generator — Visual form builder to create valid apps.json files for wvw.dev
• JSON Formatter — Pretty-print and validate any JSON data
• JSON Schema Validator — Validate JSON against a schema definition
• JSON Schema Generator — Generate JSON Schema from sample data
• Meta Tag Generator — Generate HTML meta tags for your app's homepage

Frequently asked questions

Does the builder submit my store?

No. It prepares the JSON and submission instructions. Follow the current WVW process to publish the source and submit it.

Does GitHub autofill use the network?

Yes. It requests metadata for the public repository from the GitHub API. JSON editing and serialization happen locally.

Does a green validation result guarantee acceptance?

No. It checks the rules bundled with the tool. Compare the exported file with the current target schema and submission requirements.

Can I edit the file after submission?

Yes. Maintain the source file at the registered location. The catalog updates after a successful fetch and build; do not assume an exact publication time.

Are app IDs checked against every other store?

The builder detects duplicate IDs in the current draft. Check the published catalog for conflicts outside that draft.

Can I run a separate store?

Yes. Appetit provides a separate store workflow. Its publication and hosting choices do not automatically register the store with WVW.

Next Steps

• Create your apps.json now with the WVW Apps.json Generator
• Validate existing JSON with the JSON Formatter or JSON Schema Validator
• Learn about JSON schemas in our guide on JSON Schema validation
• Generate meta tags for your app's homepage with the Meta Tag Generator