CLI Configuration

Plugin Manifest

The plugin.manifest.json file defines your plugin. The CLI validates it before every deployment.

Complete Example

{
  "pluginId": "my-checkout-plugin",
  "name": "My Checkout Plugin",
  "version": "2.1.0",
  "description": "A premium checkout experience",
  "author": "Your Name",
  "category": "checkout",
  "mode": "direct-mode",
  "tags": ["checkout", "premium"],
  "pages": [
    {
      "path": "/",
      "features": ["landing"],
      "remappable": false,
      "description": "Landing page"
    },
    {
      "path": "/checkout",
      "features": [
        {
          "type": "checkout",
          "requirements": ["payment", "shipping"]
        }
      ],
      "remappable": true,
      "description": "Checkout flow"
    },
    {
      "path": "/thankyou/:orderId",
      "features": [
        {
          "type": "thankyou",
          "requirements": ["order"]
        }
      ],
      "remappable": true,
      "description": "Order confirmation"
    }
  ],
  "router": {
    "basePath": "/",
    "matcher": ".*",
    "excluder": null
  },
  "requirements": {
    "sdk": "@tagadapay/plugin-sdk",
    "sdkVersion": "v2"
  },
  "configuration": {
    "schema": "config/schema.json",
    "uiSchema": "config/ui-schema.json"
  },
  "homepage": "https://yourwebsite.com",
  "repository": "https://github.com/you/my-plugin",
  "license": "MIT"
}

Field Reference

pluginId (required)

Unique identifier for your plugin across TagadaPay. Cannot be changed once deployed.

"pluginId": "my-checkout-plugin"

name, version, description, author (required)

Basic metadata. Version must follow semver (MAJOR.MINOR.PATCH).

"name": "My Plugin",
"version": "2.1.0",
"description": "A custom checkout",
"author": "Your Name"

category (required)

Plugin category for organization. Examples: checkout, landing, upsell, post-purchase.

"category": "checkout"

pages (required)

At least one page. Each page has a path, optional features, and remappable flag.

"pages": [
  {
    "path": "/checkout",
    "features": [
      {
        "type": "checkout",
        "requirements": ["payment", "shipping"]
      }
    ],
    "remappable": true
  }
]

Feature types: landing, checkout, thankyou, product-page, catalog, upsell, post-purchase, staticRequirements: payment, shipping, customer, order, cart, inventory

router (required)

Controls how URLs match your plugin.

basePath: Root path for the plugin (usually /)
matcher: Regex pattern for matching URLs (usually .*)
excluder: Pattern to exclude from matching (or null)

"router": {
  "basePath": "/",
  "matcher": ".*",
  "excluder": null
}

requirements (required)

SDK dependency info.

"requirements": {
  "sdk": "@tagadapay/plugin-sdk",
  "sdkVersion": "v2"
}

sdkVersion must be "v1" or "v2".

mode (optional)

Plugin loading mode:

"direct-mode" (default) — Plugin is served directly
"proxy-mode" — Plugin is proxied

"mode": "direct-mode"

configuration (optional)

Allows the CRM to configure instances with a form UI. References JSON Schema files in your config/ directory.

"configuration": {
  "schema": "config/schema.json",
  "uiSchema": "config/ui-schema.json"
}

Without this, your plugin won’t be configurable from the CRM dashboard.

Config Directory

The CLI looks for a config/ directory in your plugin root. Files found there are auto-synced after deployment.

my-plugin/
├── plugin.manifest.json
├── dist/
├── config/
│   ├── schema.json              # JSON Schema for config form
│   ├── ui-schema.json           # UI hints for the config form
│   ├── default.preset.json      # Default config values
│   ├── blue-theme.preset.json   # Named preset
│   └── green-theme.config.json  # Another named preset

Naming Conventions

Pattern	Purpose
`*.preset.json`	Config preset (synced to deployment)
`*.config.json`	Config preset (synced to deployment)
`schema.json` or `config.schema.json`	JSON Schema for the config form
`ui-schema.json` or `config.ui-schema.json`	UI Schema for form layout

Example: Config Schema

config/schema.json

{
  "type": "object",
  "properties": {
    "theme": {
      "type": "object",
      "properties": {
        "primaryColor": { "type": "string", "format": "color" },
        "fontFamily": { "type": "string" }
      }
    },
    "features": {
      "type": "object",
      "properties": {
        "expressCheckout": { "type": "boolean" },
        "upsells": { "type": "boolean" }
      }
    }
  }
}

Example: Config Preset

config/blue-theme.preset.json

{
  "theme": {
    "primaryColor": "#007bff",
    "fontFamily": "Inter, sans-serif"
  },
  "features": {
    "expressCheckout": true,
    "upsells": true
  }
}

When you deploy, the CLI auto-detects these files and syncs them via the /plugins/v2/deployment/sync-config API. This makes the presets and schema available in the CRM when creating instances.

Local Development

Create .local.json in your plugin root for local development:

.local.json

{
  "storeId": "store_dev_123",
  "accountId": "acc_dev_456",
  "config": "blue-theme",
  "apiUrl": "https://app.tagadapay.dev"
}

Field	Description
`storeId`	Your development store ID
`accountId`	Your account ID
`config`	Preset name (matches `config/*.preset.json` filename without extension)
`apiUrl`	API endpoint for development

Path Remapping

Pages with "remappable": true can have their URLs remapped by the CRM. This allows merchants to customize URL paths without changing plugin code.

{
  "pages": [
    {
      "path": "/products/:id",
      "features": ["product-page"],
      "remappable": true
    }
  ]
}

When a merchant configures a remap (e.g., external /p/:slug → internal /products/:id), the routing engine handles the translation automatically. See the Path Remapping guide for details.

Environments

The CLI supports three environments plus custom URLs:

Name	Flag	API URL
Production	`--prod` (default)	`https://app.tagadapay.com`
Development	`--dev`	`https://app.tagadapay.dev`
Local	`--local`	`http://app.localhost:3000`
Custom	`--base-url <url>`	Any URL

tgd login --dev
tgd deploy --local --store store_123
tgd login --base-url https://custom.tagadapay.com

Troubleshooting

Manifest validation failed

The CLI validates your manifest before deploying. Common missing fields:

category — required (e.g. "checkout")
router — required (basePath, matcher, excluder)
requirements — required (sdk, sdkVersion)

Check validation output for specific errors.

Invalid JSON

cat plugin.manifest.json | python3 -m json.tool

Path remapping not working

Verify "remappable": true on the page in your manifest
Check the CRM routing configuration
See the Path Remapping guide for debugging tips

Config not appearing in CRM

Make sure you have a configuration field in your manifest pointing to valid schema files, and that your config/ directory contains the referenced files. They are synced automatically after tgd deploy.

Next Steps

Quick Start

Deploy your first plugin

CLI Reference

All commands and flags

Plugin SDK

Build interactive plugins with React hooks

Hosting & A/B Testing

Host pages and set up A/B tests via API

Hosting & A/B Testing

Plugin SDK

Plugin CLI

Integration Guides

CLI Configuration

CLI Configuration

Plugin Manifest

Complete Example

Field Reference

Config Directory

Naming Conventions

Example: Config Schema

Example: Config Preset

Local Development

Path Remapping

Environments

Troubleshooting

Next Steps

Quick Start

CLI Reference

Plugin SDK

Hosting & A/B Testing

Hosting & A/B Testing

Plugin SDK

Plugin CLI

Integration Guides

​CLI Configuration

​Plugin Manifest

​Complete Example

​Field Reference

​Config Directory

​Naming Conventions

​Example: Config Schema

​Example: Config Preset

​Local Development

​Path Remapping

​Environments

​Troubleshooting

​Next Steps

Quick Start

CLI Reference

Plugin SDK

Hosting & A/B Testing

CLI Configuration

Plugin Manifest

Complete Example

Field Reference

Config Directory

Naming Conventions

Example: Config Schema

Example: Config Preset

Local Development

Path Remapping

Environments

Troubleshooting

Next Steps