Shopify Dev Theme Template Mapping: The Complete Guide

Why Template Mapping Is a Problem on Dev Themes

If you've used Shopify CLI for theme development, you know the workflow: create a development theme on the client's production store, iterate on it via shopify theme dev, and preview changes in real-time with actual store data.

This is fantastic — until you create custom templates.

Custom templates (like page.landing.json, product.bundle.json, or collection.seasonal.json) need to be assigned to specific pages or products via the Shopify admin. But here's the catch: dev themes don't appear in the admin's template assignment dropdown.

This means your beautifully crafted landing page template sits there, technically uploaded to the theme, but with no way for a client (or even you) to see it applied to the correct page through normal navigation.

How Shopify Templates Actually Work

Before diving into solutions, let's understand the mechanics. For the full reference, see the Shopify theme templates documentation.

Template Assignment Storage

When you assign a template to a page in Shopify admin, Shopify stores that assignment in the resource's metafield, not in the theme. Specifically:

• The page/product/collection has a template_suffix field
• This suffix tells Shopify which template file to render: page.[suffix].json
• If no suffix is set, Shopify uses the default template (page.json)

How Dev Theme Preview Works

When you visit a dev theme preview URL, Shopify renders the requested page using the dev theme's templates. But it still uses the resource's template_suffix to determine which template to load.

If the page doesn't have a template_suffix assigned (because you can't assign one via admin to a dev theme), Shopify renders the default template — regardless of what custom templates exist in the theme.

The URL Override: ?view=

Shopify provides a URL parameter override: appending ?view=template-name forces a specific template to render. For example:

# Forces the "landing" template on any page
https://store.myshopify.com/pages/about?view=landing

# Forces the "bundle" template on a product
https://store.myshopify.com/products/variety-pack?view=bundle

# Combined with dev theme preview
https://store.myshopify.com/pages/about?preview_theme_id=12345&view=landing

This works perfectly for developers. But asking clients to use these links? That's where things fall apart.

The URL Parameter Approach (?view=)

The simplest solution is to send clients a list of links with the correct ?view= parameters pre-applied.

This approach works for developer-to-developer reviews. For client-facing reviews, you need something that doesn't require client cooperation.

The Snippet Injection Approach

A more robust approach: inject a Liquid snippet into the theme's layout/theme.liquid that intercepts page loads and applies the correct template based on a mapping configuration.

How It Works

1. Define a mapping in a JSON file or snippet: "When URL = /pages/about, use template = landing"
2. The snippet checks the current URL on every page load
3. If a mapping exists, it redirects to the same URL with the correct ?view= parameter
4. This happens transparently — the client just visits the page normally

{% comment %}
  Template auto-mapping — renders correct templates on dev themes
  Mappings defined as: page_url → template_suffix
{% endcomment %}

{% assign current_path = request.path %}
{% assign view_param = request.page_type %}

{% comment %} Only apply if no ?view= already present {% endcomment %}
{% unless request.design_mode or canonical_url contains 'view=' %}

  {% if current_path == '/pages/about' and template.suffix != 'story' %}
    {% assign target_url = current_path | append: '?view=story' %}
    <script>window.location.replace('{{ target_url }}');</script>
  {% endif %}

  {% if current_path contains '/products/' and product.type == 'Bundle' and template.suffix != 'bundle' %}
    {% assign target_url = current_path | append: '?view=bundle' %}
    <script>window.location.replace('{{ target_url }}');</script>
  {% endif %}

{% endunless %}

Auto-Mapping: The Best Solution

The ideal approach combines the transparency of snippet injection with a proper management interface and eliminates the redirect flash:

What Auto-Mapping Does

1. Detects all custom templates in your theme (scans the templates/ directory)
2. Fetches store content via the Admin API (pages, products, collections)
3. Lets you map each template to specific resources via a UI
4. Injects the mapping into the theme as a Liquid snippet that handles routing transparently

Why This Works Better

• Client visits any page → sees the correct template
• Internal navigation works (links between pages maintain correct templates)
• No client education needed
• Mapping is managed from a dashboard, not by editing Liquid code
• Can be removed cleanly before deployment

This is exactly what ThemeSync's Template Mapping feature provides — a visual template mapping interface that auto-detects your templates, shows available store resources, and handles the injection transparently.

Conditional Mapping for Product Types

Some templates should apply conditionally — not to a specific product, but to a type of product. Examples:

• product.bundle.json → Any product tagged "Bundle" or in the "Bundles" collection
• product.subscription.json → Any product with a selling plan
• collection.seasonal.json → Collections with "seasonal" in the handle

Direct vs. Conditional Mapping

Conditional mapping is powerful for stores with many products of the same type. Instead of mapping 50 bundle products individually, you define one rule: "Any product in the Bundles collection uses the bundle template."

Presenting Templates to Clients

With auto-mapping in place, presenting templates to clients becomes trivial:

The Client Experience

1. Client receives a single preview URL
2. They navigate the site normally (via navigation, search, or direct URLs)
3. Every page shows the correct template automatically
4. They leave feedback directly on the page (if using a feedback tool)

No instructions. No special links. No "please use this URL with these parameters." The preview just works like a real website.

Setting Expectations

Even with auto-mapping, set clear expectations with clients:

• This is a preview — content they add/change in Shopify admin won't appear until go-live
• Some features (loyalty apps, reviews, etc.) may not be active on the dev theme
• The URL will look different from their final site URL
• Design is being reviewed, not content (unless they're also doing content migration)

Common Mistakes and How to Avoid Them

Template mapping is a critical step in a complete theme delivery workflow. The Theme Ops Checklist includes a pre-presentation verification section that covers all the common failure points.

Mistake 1: Forgetting to Remove the Mapping Snippet Before Publish

If your theme contains a template mapping snippet and you publish it, it'll redirect live visitors to ?view= URLs. Always clean up before deployment.

Mistake 2: Not Mapping ALL Custom Templates

If you map 3 out of 5 templates, clients will navigate to the 2 unmapped pages and see the default template. They'll assume those pages haven't been built yet (or are broken). Map everything.

Mistake 3: Mapping to Wrong Resources

A "landing page" template mapped to the /about page will confuse everyone. Make sure your mappings reflect the actual site structure that will exist post-launch.

Mistake 4: Not Testing the Full Navigation Flow

Test the preview as if you were a client: start at the homepage, click through the navigation, visit products from collections. Every path should land on the correct template.

Mistake 5: Ignoring 404s from App Embeds

If your custom template references app blocks (Klaviyo, Yotpo, etc.) that aren't installed on the dev theme, the page may 404 entirely. Scan for external dependencies before presenting to clients.