> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsebuilder.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Extension Architecture

> Build multiple extension types in a single Shopify app

# 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

```toml theme={null}
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

```toml theme={null}
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

```toml theme={null}
type = "web_pixel"

[[targeting]]
target = "web_pixel"
```

**Use Cases:**

* Custom analytics
* Marketing pixel tracking
* Event monitoring

### Theme Extensions

```toml theme={null}
type = "theme_app_extension"
```

**Components:**

* App blocks
* App embeds
* Liquid templates

## Deployment

When you push to GitHub, **one deployment** handles all extension types:

```yaml theme={null}
- 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

<Info>
  All generated extensions automatically deploy to your merchant's GitHub repository and Shopify app with zero manual steps.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Build Checkout Extensions" icon="cart-shopping" href="/guides/checkout-extensions">
    Create dynamic checkout experiences
  </Card>

  <Card title="Build Functions" icon="function" href="/essentials/functions">
    Add business logic and automation
  </Card>

  <Card title="Deployment Pipeline" icon="rocket" href="/concepts/deployment-pipeline">
    Understand automated deployment
  </Card>

  <Card title="GitHub Integration" icon="github" href="/deployment/github-integration">
    Set up your deployment workflow
  </Card>
</CardGroup>