Skip to main content

​
Multi-Extension Architecture

Synapse supports building multiple extension types in a single Shopify app. This is the recommended Shopify architecture and allows you to create a complete app experience across all surfaces.

​
Repository Structure

When you create a merchant app, all extensions deploy to the same repository and Shopify app: 
merchant-app/
├── shopify.app.toml              # Single app config
├── package.json                  # Shared dependencies
├── .github/
│   └── workflows/
│       └── deploy.yml            # Deploys all extensions
└── extensions/
    ├── checkout-banner/          # Checkout UI Extension
    │   ├── shopify.extension.toml
    │   └── src/index.tsx
    ├── admin-product-widget/     # Admin Extension
    │   ├── shopify.extension.toml
    │   └── src/index.tsx
    ├── customer-account-page/    # Customer Account Extension
    │   ├── shopify.extension.toml
    │   └── src/index.tsx
    ├── web-pixel-tracker/        # Web Pixel (Analytics)
    │   ├── shopify.extension.toml
    │   └── src/index.ts
    ├── theme-app-block/          # Theme Extension
    │   ├── shopify.extension.toml
    │   └── blocks/featured.liquid
    └── discount-function/        # Function
        ├── shopify.extension.toml
        ├── src/run.js
        └── src/run.graphql

​
Extension Types

Each extension is identified by its type in shopify.extension.toml:

​
UI Extensions

type = "ui_extension"

[[targeting]]
target = "purchase.checkout.block.render"    # Checkout
# OR
target = "admin.product-details.block.render" # Admin
# OR
target = "customer-account.order-status.block.render" # Customer Account
Surfaces:
  • Checkout - Payment flow customization
  • Admin - Merchant dashboard widgets
  • Customer Account - Customer portal pages
  • Point of Sale - In-store experiences

​
Functions

type = "function"

[[targeting]]
target = "purchase.product-discount.run"     # Discounts
# OR
target = "purchase.payment-customization.run" # Payment methods
# OR
target = "purchase.delivery-customization.run" # Shipping options
Types:
  • Product/Order/Shipping Discounts
  • Payment Customization
  • Delivery Customization
  • Cart/Checkout Validation
  • Fulfillment Constraints

​
Web Pixels

type = "web_pixel"

[[targeting]]
target = "web_pixel"
Use Cases:
  • Custom analytics
  • Marketing pixel tracking
  • Event monitoring

​
Theme Extensions

type = "theme_app_extension"
Components:
  • App blocks
  • App embeds
  • Liquid templates

​
Deployment

When you push to GitHub, one deployment handles all extension types: 
- name: Deploy to Shopify
  run: shopify app deploy --force
  # Deploys: UI extensions, functions, pixels, theme blocks
All extensions deploy together to the same Shopify app and are available to merchants in a single installation.

​
Benefits

Single App Architecture:
  • ✅ One installation for merchants
  • ✅ Shared configuration and credentials
  • ✅ Unified billing and subscription
  • ✅ Centralized analytics and monitoring
Development Benefits:
  • ✅ Shared dependencies and utilities
  • ✅ Single deployment pipeline
  • ✅ Unified version control
  • ✅ Consistent CI/CD process

​
Example: Complete E-commerce App

my-app/
└── extensions/
    ├── checkout-upsell/          # Show product recommendations
    ├── admin-analytics/          # Show sales dashboard
    ├── discount-vip/             # VIP customer discounts
    ├── payment-filter/           # Hide COD for new customers
    └── analytics-pixel/          # Track conversion events
This single app provides:
  • Customer experience (checkout upsell)
  • Merchant tools (admin analytics)
  • Business logic (discounts, payment rules)
  • Data tracking (analytics)

​
Current Support

Synapse currently generates:
  • ✅ Checkout UI Extensions - Fully supported
  • 🚧 Functions - In development
  • 📋 Admin Extensions - Planned
  • 📋 Web Pixels - Planned
  • 📋 Theme Extensions - Planned
All generated extensions automatically deploy to your merchant’s GitHub repository and Shopify app with zero manual steps.

​
Next Steps

Build Checkout Extensions

Create dynamic checkout experiences

Build Functions

Add business logic and automation

Deployment Pipeline

Understand automated deployment

GitHub Integration

Set up your deployment workflow