AutoCom Docs

module.json Reference

The module.json manifest is the single source of truth for your module. It defines metadata, backend configuration, frontend routes, navigation, settings, and integrations.

JSON Schema Support

AutoCom provides a JSON Schema for IDE validation and autocomplete:

{
  "$schema": "./module.schema.json"
}

Complete Example

{
  "$schema": "./module.schema.json",
  "name": "StoreShopify",
  "alias": "store-shopify",
  "displayName": "Shopify Integration",
  "description": "Connect and sync orders from your Shopify store",
  "version": "1.0.0",
  "type": "store",
  "priority": 50,
  "enabled": false,
  "isCore": false,

  "backend": {
    "namespace": "Modules\\StoreShopify",
    "providers": ["Modules\\StoreShopify\\StoreShopifyServiceProvider"],
    "aliases": {},
    "migrations": true,
    "contracts": ["StoreProviderContract"],
    "workflowNodes": [
      "Modules\\StoreShopify\\Nodes\\Triggers\\ShopifyOrderCreatedTrigger"
    ],
    "widgetDataProviders": {
      "shopify:store-stats": "Modules\\StoreShopify\\App\\WidgetProviders\\StoreStatsProvider"
    }
  },

  "frontend": {
    "routes": {
      "basePath": "/integrations/shopify",
      "catchAll": true,
      "pages": {
        "/": "index.tsx",
        "/settings": "settings.tsx",
        "/sync": "sync.tsx"
      }
    },
    "navigation": {
      "title": "Shopify",
      "href": "/integrations/shopify",
      "icon": "Store",
      "position": 10
    },
    "exports": {
      "components": ["ShopifyConnectButton"],
      "hooks": ["useShopify"],
      "types": ["ShopifyStore"]
    }
  },

  "dependencies": {
    "modules": ["Core", "Orders"],
    "backend": { "php": "^8.2" },
    "frontend": {}
  },

  "settings_schema": {
    "shop_domain": {
      "type": "string",
      "required": true,
      "label": "Shop Domain",
      "placeholder": "mystore.myshopify.com"
    },
    "api_key": {
      "type": "string",
      "required": true,
      "encrypted": true,
      "label": "API Key"
    },
    "auto_sync": {
      "type": "boolean",
      "default": true,
      "label": "Auto-sync orders"
    }
  }
}

Field Reference

Top-Level Fields

Field Type Required Description
name string Yes PascalCase module name (e.g., StoreShopify)
alias string Yes Kebab-case identifier (e.g., store-shopify)
displayName string Yes Human-readable name shown in UI
description string Yes Brief description of the module
version string Yes Semantic version (e.g., 1.0.0)
type string Yes Module type — see table below
priority int No Boot order (lower = earlier). Default: 50
enabled bool No Initial enabled state. Default: false
isCore bool No Core modules can't be uninstalled. Default: false

Module Types

Type Description Contract
core Essential system modules —
store E-commerce platform integrations StoreProviderContract
shipping Logistics provider integrations ShippingProviderContract
channel Communication channels ChannelProviderContract
payment Payment gateways PaymentProviderContract
ai AI service integrations AIProviderContract

Backend Configuration

"backend": {
  "namespace": "Modules\\YourModule",
  "providers": ["Modules\\YourModule\\YourModuleServiceProvider"],
  "aliases": {},
  "migrations": true,
  "contracts": ["StoreProviderContract"],
  "workflowNodes": ["Modules\\YourModule\\Nodes\\..."],
  "widgetDataProviders": {
    "yourmodule:widget": "Modules\\YourModule\\App\\WidgetProviders\\..."
  }
}
Field Description
namespace PSR-4 namespace root
providers Service provider classes to register
migrations Whether to load migrations from the module
contracts Provider contracts this module implements
workflowNodes Workflow trigger/action node classes
widgetDataProviders Dashboard widget data provider classes

Frontend Configuration

"frontend": {
  "routes": {
    "basePath": "/your-module",
    "catchAll": true,
    "pages": {
      "/": "index.tsx",
      "/settings": "settings.tsx",
      "/[id]": "detail.tsx"
    }
  },
  "navigation": {
    "title": "Your Module",
    "href": "/your-module",
    "icon": "Box",
    "position": 10,
    "children": [
      { "title": "Overview", "href": "/your-module", "icon": "LayoutDashboard" }
    ]
  },
  "exports": {
    "components": ["YourComponent"],
    "hooks": ["useYourModule"],
    "types": ["YourType"]
  }
}
Field Description
routes.basePath URL prefix for all module pages
routes.catchAll Handle all sub-routes under basePath
routes.pages Map route paths to page component files
navigation Sidebar menu entry (icon uses Lucide icon names)
exports Public components, hooks, and types other modules can import

Settings Schema

Define dynamic settings that appear in the module configuration UI:

"settings_schema": {
  "field_key": {
    "type": "string",
    "required": true,
    "encrypted": false,
    "label": "Field Label",
    "placeholder": "Enter value...",
    "default": ""
  }
}
Type Description Extra Options
string Text input placeholder, validation.pattern
number Numeric input validation.min, validation.max
boolean Toggle switch default
select Dropdown options: [{label, value}]
password Password input encrypted: true
textarea Multi-line text placeholder
json JSON editor —

Fields with encrypted: true are stored encrypted at rest.

Dependencies

"dependencies": {
  "modules": ["Core", "Orders"],
  "backend": { "php": "^8.2" },
  "frontend": {}
}

Module dependencies are checked at install time. If a required module isn't installed, the installation will fail with a clear error message.

Related