App Configuration

Chapter 3: Setting up your app's identity and behavior.

Every sparQ app needs configuration files that tell sparQ what your app is called, how it should appear, and what it depends on. Let's explore the manifest files.

The Two Manifest Files

sparQ apps use two manifest files:

File Purpose When Needed
__manifest__.py Tells sparQ how to load your app Always (required)
marketplace.json Marketplace listing information Only when publishing

For development, you only need __manifest__.py. Add marketplace.json when you're ready to publish.

The __manifest__.py File

This is the heart of your app's configuration. Here's a complete example:

# __manifest__.py
manifest = {
    # Required fields
    "name": "TaskManager",       # Display name (PascalCase)
    "version": "1.0",            # Semantic version
    "mappid": "x7k2m9",          # Marketplace app ID (auto-generated)
    "main_route": "/tasks",      # URL slug (used in /m/{mappid}/{main_route})
    "type": "App",               # "App" (visible) or "System" (hidden)
    "depends": ["core"],         # Module dependencies
    # Display fields
    "icon_class": "fa-solid fa-check-square",  # FontAwesome icon class
    "color": "#3B82F6",                         # Theme color (blue)
    "description": "Simple task management for teams",
    "long_description": "Organize tasks, set priorities, and track progress.",
}

Required Fields

Field Description Example
name Display name shown in UI (PascalCase) "TaskManager"
version Version number (MAJOR.MINOR format) "1.0"
mappid Unique 6-char marketplace app ID "x7k2m9"
main_route URL slug for your app "/tasks"
type "App" (visible) or "System" (hidden) "App"
depends List of module dependencies ["core"]

About mappid

The mappid (marketplace app ID) is a unique 6-character identifier for your app. It's used to create collision-free routes in the format /m/{mappid}/{slug}.

You don't need to create this yourself. When you scaffold a new app using the SDK, the mappid is auto-generated:

cd sdk
make app name=myapp

This generates a unique mappid and inserts it into your manifest. Your app will be accessible at /m/{mappid}/myapp.

Why mappid? As the marketplace grows, simple slugs like /notes or /tasks would collide. The mappid ensures every app has a unique namespace while you still control the slug portion of the URL.

Display Fields

Field Description Default
icon_class FontAwesome icon class "fa-solid fa-cube"
color Theme color (hex code) "#7c3aed"
description Short description (1-2 sentences) Empty
long_description Detailed description for marketplace listing Empty

The color field sets your app's accent color throughout the UI:

Image: Side-by-side comparison of apps with different theme colors

Dependencies

The depends field lists modules your app requires:

'depends': ['core', 'team']

Common dependencies:

Navigation

Apps can define their own sidebar navigation with nav_sections:

'nav_sections': [
    {
        'title': 'Dashboard',
        'icon': 'speedometer2',
        'route': 'myapp.main.dashboard'
    },
    {
        'title': 'Settings',
        'icon': 'gear',
        'route': 'myapp.settings.index'
    }
]

Each section needs:

The marketplace.json File

When you're ready to publish your app, create a marketplace.json file:

{
    "marketplace_id": "task-manager",
    "name": "Task Manager",
    "type": "app",
    "author": "Your Name",
    "author_email": "you@example.com",
    "description": "Simple task management for teams",
    "category": "productivity",
    "tags": ["tasks", "productivity", "team"],
    "min_sparq_version": "1.0",
    "license": "MIT",
    "screenshots": [
        "screenshots/dashboard.png",
        "screenshots/task-list.png"
    ]
}
No version field needed! The SDK automatically injects the version from __manifest__.py when you run make archive or make release. This ensures your version is always in sync.

Required Marketplace Fields

Field Description
marketplace_id Unique ID (lowercase, hyphens only)
name Display name
type "app", "lang_pack", or "plugin"
author Your name or company
author_email Contact email

Categories

Choose one category for your app:

Version Numbers

sparQ uses a simple MAJOR.MINOR versioning format:

Examples:

Single source of truth: Always set the version in __manifest__.py. The SDK automatically syncs this to marketplace.json when packaging.

Key Takeaways