---
url: https://findutils.com/blog/how-to-create-apps-json-for-wvw-dev-world-vibe-web
title: "Create an apps.json File for World Vibe Web"
description: "Build and review a WVW apps.json file. Add store details, categories, and app entries, then validate the output before submitting the catalog source."
category: developer
content_type: blog
locale: en
read_time: 9
status: published
author: "olgunozoktas"
published_at: 2026-03-15T12:00:00Z
updated_at: "2026-09-08T09:44:19Z"
excerpt: "World Vibe Web (wvw.dev) is a distributed app store for vibe-coded projects. To get listed, you need an apps.json file. This guide shows you how to create one — the easy way."
tag_ids: ["developer-tools", "json", "app-store", "vibe-coding", "open-source"]
tags: ["Developer Tools", "JSON", "App Store", "Vibe Coding", "Open Source"]
primary_keyword: "wvw.dev apps.json generator"
secondary_keywords: ["world vibe web", "apps.json format", "appetit store", "vibe coding app store", "list app on wvw.dev", "create apps.json"]
tool_tag: "wvw-apps-json-generator"
related_tool: "wvw-apps-json-generator"
related_tools: ["wvw-apps-json-generator", "json-formatter", "json-schema-validator", "json-schema-generator", "meta-tag-generator"]
og_image: "/images/content/blog/how-to-create-apps-json-for-wvw-dev-world-vibe-web-cover-20260908.webp"
image_alt: "Several small application models fit into matching compartments in one open index box, with consistent color tabs joining their entries."
---

To list your apps on [wvw.dev](https://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](/developers/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](https://github.com/f/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.

```json
{
  "$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

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier in kebab-case (e.g., `my-cool-app`) |
| `name` | string | Display name |
| `subtitle` | string | Short tagline shown in list views |
| `description` | string | One-liner for search results and cards |
| `category` | string[] | Array of WVW category IDs |
| `platform` | string | Platform label (Web, CLI, macOS, etc.) |
| `price` | string | Price label, typically "Free" |
| `github` | string | GitHub repository URL |

### 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](/developers/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](https://github.com/f/wvw.dev/blob/master/categories.json). Apps with unrecognized categories have those categories stripped during the build. Apps with zero valid categories are excluded entirely.

| Category ID | Display Name |
|-------------|-------------|
| `macos` | macOS Apps |
| `web` | Web Apps |
| `cli` | CLI Apps |
| `developer-tools` | Developer Tools |
| `productivity` | Productivity |
| `utilities` | Utilities |
| `education` | Education |
| `entertainment` | Entertainment |
| `games` | Games |
| `music` | Music |
| `photo-video` | Photo & Video |
| `graphics-design` | Graphics & Design |
| `social-networking` | Social Networking |
| `finance` | Finance |
| `health-fitness` | Health & Fitness |
| `lifestyle` | Lifestyle |
| `news` | News |
| `business` | Business |
| `reference` | Reference |
| `travel` | Travel |
| `food-drink` | Food & Drink |
| `navigation` | Navigation |
| `sports` | Sports |
| `weather` | Weather |
| `shopping` | Shopping |
| `books` | Books |
| `medical` | Medical |

The [WVW Apps.json Generator](/developers/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](https://github.com/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

| Task | Builder behavior | Remaining review |
|---|---|---|
| JSON formatting | Serializes fields into JSON | Confirm the intended values |
| App identifiers | Generates a kebab-case suggestion | Check uniqueness across published stores |
| Categories | Offers its bundled category list | Compare with the current WVW list |
| Required fields | Reports missing fields it checks | Validate against the target schema |
| URLs | Checks URL syntax for supported fields | Confirm HTTPS destinations and ownership |
| GitHub autofill | Requests public repository metadata | Review imported values before publication |
| Persistence | Saves the draft in browser storage | Clear saved data on a shared device |

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](https://github.com/f/appetit):

```bash
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](/developers/wvw-apps-json-generator/)** — Visual form builder to create valid apps.json files for wvw.dev
- **[JSON Formatter](/developers/json-formatter/)** — Pretty-print and validate any JSON data
- **[JSON Schema Validator](/developers/json-schema-validator/)** — Validate JSON against a schema definition
- **[JSON Schema Generator](/developers/json-schema-generator/)** — Generate JSON Schema from sample data
- **[Meta Tag Generator](/seo/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](/developers/wvw-apps-json-generator/)
- **Validate existing JSON** with the [JSON Formatter](/developers/json-formatter/) or [JSON Schema Validator](/developers/json-schema-validator/)
- **Learn about JSON schemas** in our guide on [JSON Schema validation](/developers/json-schema-generator/)
- **Generate meta tags** for your app's homepage with the [Meta Tag Generator](/seo/meta-tag-generator/)