Publishing Guide

Overview

Publishing on KidsBuild is a three-step process: build your app, submit for review, and go live. Our review process ensures all apps are safe and appropriate for the community.

Before You Publish

Make sure your app is ready:

1. App Metadata

Your app.json must include all required fields:

{
  "id": "my-awesome-game",
  "name": "My Awesome Game",
  "version": "1.0.0",
  "description": "A fun puzzle game where you match colors to score points.",
  "category": "game",
  "tags": ["puzzle", "casual", "colorful"],
  "ageRating": "everyone",
  "pricing": {
    "type": "free"
  },
  "assets": {
    "icon": "./assets/icon.png",
    "screenshots": [
      "./assets/screenshot-1.png",
      "./assets/screenshot-2.png"
    ]
  },
  "permissions": []
}

2. Required Assets

• Icon - 512x512 PNG, no transparency required
• Screenshots - At least 2, either 1280x720 (landscape) or 720x1280 (portrait)
• Optional: Video - 30-second gameplay preview (MP4, max 10MB)

3. Pre-Publish Checklist

Publishing with CLI

Step 1: Build

This compiles your TypeScript, optimizes assets, and creates a production bundle in ./dist.

Step 2: Publish

This uploads your build and submits it for review. You'll see:

Publishing my-awesome-game v1.0.0...

Validating app.json... ✓
Checking assets...
  ✓ Icon: 512x512 PNG
  ✓ Screenshot 1: 1280x720 PNG
  ✓ Screenshot 2: 1280x720 PNG
Building production bundle... ✓
Uploading (1.2 MB)... ✓

Submitted for review!

Track status at:
https://kidsbuild.com/developer/apps/my-awesome-game

Review typically takes 1-2 business days.

Draft Publishing

Want to test your production build without submitting for review?

Draft apps are only visible to you and can be accessed via a special URL. Great for testing before the official release.

Publishing with AI

You can automate publishing using AI assistants. Here's a prompt for Claude Code:

Help me publish my KidsBuild app. Run these commands in order:

1. First, check that I'm logged in:
   kb whoami

2. Build the production version:
   kb build

3. If the build succeeds, publish:
   kb publish

4. Show me the status URL when done.

If any step fails, help me fix the issue before continuing.

API Publishing

For advanced automation, you can publish via the REST API:

# Get upload URL
UPLOAD_URL=$(curl -X POST \
  -H "Authorization: Bearer $KB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId": "my-awesome-game", "version": "1.0.0"}' \
  https://api.kidsbuild.com/api/v1/publish/init | jq -r '.uploadUrl')

# Upload build
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary @dist.zip

# Submit for review
curl -X POST \
  -H "Authorization: Bearer $KB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId": "my-awesome-game", "version": "1.0.0"}' \
  https://api.kidsbuild.com/api/v1/publish/submit

The Review Process

Our review team checks every app for:

Safety

• No inappropriate content
• No external links to unsafe sites
• No collection of personal information beyond KidsBuild's standard auth
• No malicious code or security vulnerabilities

Quality

• App functions as described
• No crashes or major bugs
• Reasonable performance
• Accessible UI (keyboard navigation, readable text)

Compliance

• Follows platform guidelines
• Accurate metadata and screenshots
• Appropriate age rating
• Valid pricing (if paid)

Review Timeline

• First submission: 1-2 business days
• Updates to existing apps: Usually same day
• Apps with schema changes: May take longer for DB review

After Review

If Approved

Your app goes live in the marketplace immediately. You'll receive an email notification and can see download stats in your dashboard.

If Rejected

You'll receive specific feedback on what needs to change. Common reasons:

• Broken functionality - Fix the bug and resubmit
• Missing assets - Add required screenshots or icon
• Inappropriate content - Remove or modify the content
• Performance issues - Optimize and resubmit

There's no penalty for rejections. Fix the issues and resubmit when ready.

Versioning

Use semantic versioning (MAJOR.MINOR.PATCH) for your app:

• PATCH (1.0.0 → 1.0.1): Bug fixes, minor tweaks
• MINOR (1.0.0 → 1.1.0): New features, backward compatible
• MAJOR (1.0.0 → 2.0.0): Breaking changes, major redesigns

Update the version in app.json before each publish:

{
  "version": "1.1.0",
  "changelog": "Added leaderboard feature and fixed score display bug"
}

Updating Published Apps

To update an already-published app:

1. Make your changes
2. Bump the version in app.json
3. Run kb publish

Updates go through a lighter review (usually same-day) unless they include significant changes or new database schemas.

Unpublishing

Need to take your app offline?

This hides your app from the marketplace but keeps all data intact. You can republish anytime.

Next Steps

• Review Guidelines Details
• Version Management
• AI Prompts for Publishing