Unlock Your Shopify App: Making Your App Embeds Visible

Making Your Shopify App Embeds Visible: A Community Deep Dive

Hey everyone! Ever wrestled with getting your Shopify app to show up in the "App embeds" section of the theme editor? You're definitely not alone. I recently saw a great discussion in the Shopify Community about this very issue, and I wanted to share some of the key takeaways and solutions that were discussed. It can be a bit tricky, so let's break it down.

Understanding App Embeds vs. Theme Blocks

One of the first things that came up in the discussion, thanks to Ruchita, is the crucial distinction between regular theme blocks and app embed blocks. They're not the same! If you want your app to appear in the "App embeds" menu, it needs to be specifically designed as an app embed block. A regular section block just won't cut it.

The Correct File Structure

Ruchita also provided a super helpful file structure example that's worth its weight in gold. Getting this right is key:

extensions/
  my-app-embed/
    blocks/app-embed.liquid
    shopify.extension.toml
    settings_schema.json  (optional, for settings)

Make sure you have that blocks/app-embed.liquid file in there! That's where your app's front-end code will live.

The shopify.extension.toml File: Configuration is Key

This file is where you define the extension type and target. Here's an example of what it should look like:

type = "theme"
name = "My App Embed"

[[extensions]]
target = "head"   # or "body" , do NOT use "section"
name = "Global Embed"

Important: Notice the target. It should be either "head" or "body". Do NOT use "section" here. This is a common mistake that can prevent your app from showing up in the App Embeds menu.

Adding Settings with settings_schema.json

If you want to give merchants the ability to configure your app embed, you'll need a settings_schema.json file. This file defines the settings that will appear in the theme editor. For example:

{
  "settings": [
    { "type": "checkbox", "id": "show_banner", "label": "Show banner" },
    { "type": "text", "id": "banner_text", "label": "Banner text", "default": "Welcome!" }
  ]
}

This will create a checkbox and a text field in the App Embed settings panel, allowing merchants to control whether to show a banner and what text to display.

Step-by-Step Instructions to Make it Work

Ruchita also outlined the steps to get everything working properly:

1. Build and deploy the extension with Shopify CLI.
2. Install the app in your store.
3. Go to Online Store → Themes → Customize → App embeds and toggle it on.
4. The schema panel will now appear for merchants to configure.

Troubleshooting: Where Does the Schema Go?

Emilianoc, another community member, chimed in with a question that I think a lot of developers have: "Where do I put the schema for the app extension in 'app embeds'?" He shared some screenshots to illustrate the problem:

And the desired outcome:

The key takeaway here is that the schema needs to live within the embed extension itself, in that settings_schema.json file we talked about earlier. Normal theme block schemas won't work for App Embeds.

So, if you're struggling to get your app to show up in the App Embeds menu, double-check that you're using the correct file structure, that your shopify.extension.toml file is configured correctly with the right target, and that your schema is located within the embed extension itself. These are the most common culprits. Good luck, and happy coding!