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

Get Started

Core Concepts

Building Extensions

Building Functions

Development

Deployment

Advanced

Multi-Extension Architecture

Multi-Extension Architecture

Repository Structure

Extension Types

UI Extensions

Functions

Web Pixels

Theme Extensions

Deployment

Benefits

Example: Complete E-commerce App

Current Support

Next Steps

Build Checkout Extensions

Build Functions

Deployment Pipeline

GitHub Integration

​Multi-Extension Architecture

​Repository Structure

​Extension Types

​UI Extensions

​Functions

​Web Pixels

​Theme Extensions

​Deployment

​Benefits

​Example: Complete E-commerce App

​Current Support

​Next Steps

Build Checkout Extensions

Build Functions

Deployment Pipeline

GitHub Integration

Multi-Extension Architecture

Repository Structure

Extension Types

UI Extensions

Functions

Web Pixels

Theme Extensions

Deployment

Benefits

Example: Complete E-commerce App

Current Support

Next Steps