Skip to main content

The app.json Manifest

The app.json file is the heart of your SitePack App. It acts as a manifest that defines your app's identity, permissions, user interface extensions, and webhook subscriptions. When a merchant installs your app, SitePack reads this file to understand how to integrate your service into their store.

The Manifest Structure​

The app.json is a standard JSON file containing several key sections. Below is a breakdown of the most important fields.

Basic Information​

These fields define your app's identity in the SitePack App Marketplace and Admin.

  • uuid: A unique, URL-friendly identifier for your app (e.g., sitepack-shipping-expert).
  • name: The display name of your app as seen by merchants.
  • version: The current version of your app (using Semantic Versioning).
  • author: Your name or company name.
  • category: The marketplace category (e.g., content, marketing, utilities).

Authentication (auth)​

This section defines how SitePack should handle the OAuth 2.0 flow for your app.

  • redirect_uri: The endpoint on your server where SitePack will send the authorization code.
  • scopes: An array of permissions your app requires (e.g., content:read, leads:write).

Setup & Configuration (setup)​

Define where the merchant should be directed to complete the app setup.

  • onboarding_url: The URL where the merchant is sent immediately after installation to link their account or perform initial setup.
  • configuration_url: The settings page for your app, accessible from the SitePack Admin App list.

Editor Integration (editor)​

Extend the SitePack visual editor with custom blocks and assets.

  • preview_template: Path to the Twig file used for editor canvas rendering.
  • blocks: Definitions for custom editor blocks.
  • assets: List of js and css files to load in the editor context.

Admin & UI Integration (admin)​

Extend the SitePack Admin interface with settings, navigation, and widgets.

  • settings_type: abstract (JSON Schema) or iframe (Remote URL).
  • settings_url: URL for iframe type settings.
  • settings_schema: JSON Schema for abstract type settings.
  • navigation: Add custom menu items to the SitePack Admin sidebar.
  • widgets: Embed your app's functionality directly into existing SitePack Admin pages.

Webhooks (webhooks)​

Subscribe to real-time events happening in the store.

  • topic: The event you want to listen to (e.g., order.created, lead.created).
  • address: The HTTPS endpoint on your server where SitePack will POST the event data.

Full Example​

Here is a complete example of a valid app.json file:

{
  "uuid": "sitepack-photo-album",
  "name": "Photo Album Pro",
  "version": "1.2.0",
  "author": "SitePack Core Team",
  "category": "content",
  "auth": {
    "scopes": ["content:read", "content:write", "media:read"]
  },
  "editor": {
    "preview_template": "templates/album_preview.html.twig",
    "assets": {
      "js": ["assets/album-editor.js"],
      "css": ["assets/album-editor.css"]
    },
    "blocks": [
      {
        "id": "photo-album",
        "label": "Photo Album",
        "icon": "image-gallery"
      }
    ]
  },
  "admin": {
    "settings_type": "abstract",
    "settings_schema": {
      "type": "object",
      "properties": {
        "columns": { "type": "integer", "default": 3, "minimum": 1, "maximum": 6 },
        "gap": { "type": "string", "default": "1rem" },
        "theme": { "type": "string", "enum": ["light", "dark", "minimal"] }
      }
    },
    "navigation": [
      { "label": "Gallery Manager", "path": "/galleries", "icon": "images" }
    ]
  },
  "webhooks": [
    {
      "topic": "lead.created",
      "address": "https://api.your-app.com/webhooks/sitepack-lead"
    }
  ]
}

Next Steps​