Metaobjects Manager

A Node.js CLI tool for managing Shopify Metaobject definitions via the GraphQL Admin API. This tool allows you to synchronize Metaobject definitions between your local JSON files and your Shopify store.

Features

• PUSH: Publish local Metaobject definitions to Shopify (create new or update existing)
  • Handles field additions, updates, and deletions
  • Optional auto-confirmation with -y/--yes flag
  • Default prompt response is "yes" (just press Enter)
• PULL: Retrieve Metaobject definitions from Shopify to local JSON files
  • Automatically filters out Shopify internal metaobjects and those from other apps
  • Only pulls merchant-owned metaobjects by default
• VALIDATE: Validate local JSON files without syncing
• Selective Operations: All commands support optional file/type parameters to process specific definitions

Installation

npm install -g @mraichelson/metaobjects-manager

Or use locally in your project:

npm install @mraichelson/metaobjects-manager

Setup

1. Copy the example environment file:

   cp env.example .env

2. Configure your .env file with your Shopify store credentials:

   SHOPIFY_STORE_URL=your-store-url.myshopify.com
   SHOPIFY_CLIENT_ID=your-client-id
   SHOPIFY_CLIENT_SECRET=your-client-secret

3. Get your credentials from your custom app:

   • Shopify Partner Dashboard: https://partners.shopify.com
   • Navigate to: Apps → Develop apps → Your app → API credentials
   • Copy the Client ID and Client Secret
   • Ensure your app has the following Admin API access scopes enabled:
     • read_metaobject_definitions - Read metaobject definition schemas
     • write_metaobject_definitions - Create and update metaobject definition schemas
     • read_metaobjects - Read metaobject data instances
     • write_metaobjects - Create and update metaobject data instances

Usage

Push Command

Push local Metaobject definitions to Shopify:

metaobjects-manager push
# or
shopify-mom push

Push specific files:

metaobjects-manager push example.json dictionary.json
# or
metaobjects-manager push example dictionary
# (with or without .json extension)

Auto-confirm all prompts (useful for CI/CD):

metaobjects-manager push -y
# or
metaobjects-manager push --yes

This command will:

• Read JSON files from metaobjects (or configured directory)
  • If files are specified, only process those files
  • If no files specified, process all files in the directory
• Validate each file's structure and field types
• Check if the definition exists in Shopify
• Compare local and remote definitions to detect field changes
• Prompt for confirmation before creating or updating (defaults to "yes")
  • Use -y/--yes to skip all prompts
• Handle field deletions: If a field is removed from a local JSON file, it will be deleted from Shopify during update
• Skip files with errors and continue with others

Pull Command

Pull Metaobject definitions from Shopify to local files:

metaobjects-manager pull
# or
shopify-mom pull

Pull specific metaobject types:

metaobjects-manager pull example dictionary
# (specify by type name, not filename)

This command will:

• Fetch Metaobject definitions from your Shopify store
  • Automatically filters out:
    • Shopify internal metaobjects (prefixed with shopify--)
    • Metaobjects from other apps (prefixed with app-- or $app:)
  • Only processes merchant-owned metaobjects
  • If types are specified, only pull those types
  • If no types specified, pull all merchant-owned definitions
• Create new local JSON files for definitions that don't exist locally
• Update existing local files with current definitions from Shopify
• Log all changes to the terminal

Validate Command

Validate local metaobject JSON files without pushing or pulling:

metaobjects-manager validate
# or
shopify-mom validate

Validate specific files:

metaobjects-manager validate example.json dictionary.json
# or
metaobjects-manager validate example dictionary
# (with or without .json extension)

This command will:

• Read JSON files from metaobjects (or configured directory)
  • If files are specified, only validate those files
  • If no files specified, validate all files in the directory
• Validate each file's structure and field types
• Report which files are valid or invalid
• Display detailed error messages for invalid files
• Exit with code 0 if all files are valid, code 1 if any are invalid

Use cases:

• Verify files that were pulled from a store instance
• Verify files that were written locally before pushing
• Validate changes made locally before pushing them

Configuration

Metaobjects Directory

By default, the tool looks for Metaobject definition files in metaobjects (project root). You can customize this by setting the METAOBJECTS_DIR environment variable:

METAOBJECTS_DIR=custom/path/to/metaobjects

JSON File Format

Each Metaobject definition should be stored as a JSON file named {type}.json. Example:

{
  "type": "size_chart",
  "name": "Size Chart",
  "description": "Product sizing information",
  "displayNameKey": "size",
  "access": {
    "admin": "MERCHANT_READ_WRITE",
    "storefront": "PUBLIC_READ"
  },
  "capabilities": {
    "publishable": {
      "enabled": true
    },
    "translatable": {
      "enabled": true
    },
    "renderable": {
      "enabled": true,
      "data": {
        "metaTitleKey": "title",
        "metaDescriptionKey": "description"
      }
    },
    "onlineStore": {
      "enabled": true,
      "data": {
        "urlHandle": "size-charts",
        "canCreateRedirects": true
      }
    }
  },
  "fieldDefinitions": [
    {
      "key": "size",
      "name": "Size",
      "type": "single_line_text_field",
      "description": "The size identifier",
      "required": true,
      "capabilities": {
        "adminFilterable": {
          "enabled": true
        }
      },
      "validations": [
        {
          "name": "choices",
          "value": ["XS", "S", "M", "L", "XL"]
        }
      ]
    },
    {
      "key": "chest_inches",
      "name": "Chest (inches)",
      "type": "number_decimal",
      "required": false
    }
  ]
}

Metaobject Type Naming

⚠️ Important: Reserved Type Names

Metaobject types cannot conflict with Shopify's native content types. Do not use reserved type names such as:

• article, page, blog, product, collection, customer, order, cart, checkout
• Any type that matches Shopify's built-in content object types

Naming Patterns and Requirements:

For detailed information on naming conventions, ownership types, and type identifier requirements, see the official Shopify documentation:

• Ownership and Reserved Prefixes - Learn about app-owned vs merchant-owned metaobjects and the $app: prefix
• Manage Metaobject Definitions - Type identifier requirements and naming best practices
• About Metaobjects - Overview of metaobject ownership types and naming patterns

Available Options

Metaobject-level options:

• type (required): Unique identifier for the metaobject type (see naming guidelines above)
• name (required): Human-readable name
• description (optional): Administrative description
• displayNameKey (optional): Field key to use as display name
• access (required): Access permissions (admin and storefront)
• capabilities (optional): Optional features:
  • publishable: Enable draft/active status workflow
  • translatable: Enable translation support
  • renderable: Enable SEO metadata (requires metaTitleKey and/or metaDescriptionKey)
  • onlineStore: Enable Online Store pages (requires urlHandle)

Field-level options:

• key (required): Unique field identifier
• name (required): Human-readable field name
• type (required): Field data type (see valid types below)
• description (optional): Field description
• required (optional): Whether field is required
• validations (optional): Validation rules (e.g., min/max, choices, regex)
• capabilities (optional): Field capabilities:
  • adminFilterable: Enable filtering in Shopify admin

See metaobjects/example.json for a sample Metaobject definition.

Valid Field Types

Field types must match Shopify's Metaobject field types. See the official documentation for the complete list.

Common types include:

• single_line_text_field
• multi_line_text_field
• number_integer
• number_decimal
• date
• date_time
• boolean
• url
• file_reference
• color

Error Handling

The tool handles errors gracefully:

• Invalid JSON: Logs the error and skips the file
• Invalid field types: Lists invalid types and references valid types
• Missing required fields: Lists missing fields
• API errors: Displays user-friendly error messages from Shopify
• Network errors: Logs with retry suggestions

On any error, the tool skips the current operation and continues with remaining files.

Development

Building

npm run build

This compiles TypeScript files from src/ to dist/.

Project Structure

.
├── src/
│   ├── cli/          # CLI command implementations
│   ├── files/        # File reading/writing utilities
│   ├── graphql/      # GraphQL queries and mutations
│   ├── shopify/      # Shopify API client and auth
│   ├── types/        # TypeScript type definitions
│   └── validators/   # JSON validation logic
├── metaobjects/      # Default directory for Metaobject JSON files
├── dist/             # Compiled JavaScript (generated)
└── package.json

License

ISC