Component Explorer Next Steps

[t-kelly]

The Component Explorer serves as a sandbox environment to develop, preview, reference theme components. It allows components to be loaded in isolation in a variety of configurations and enforce the strict scoping to eliminate undesired or hard-to-track co-dependencies between components and reducing the spaghetti nest of code seen in larger, monolithic theme projects.

The current state of the Explorer is a simple prototype relies on setup files that can be included in a theme component directory. These setup files provide the necessary state and expose desired theme editor settings so that a component can be loaded multiple times with a variety of presets. This allows developers and designers to preview components in isolation and get a sense of everything they can do, without the need to roll out the component in a particular theme project.

After spending 6 weeks focusing on primitive element component like inputs, buttons, and badges, we want now more than ever a way to show them off and make them easy to learn and adopt. This has brought us to planning next steps like:

• Overall improvements to design and UX of the Explorer
• Better presentation of components in multiple states, including resizable window to view responsive behaviour
• Components include docs for example code, Liquid variables, CSS Tokens, and JS Events

You can follow along on the design updates in the Figma file. We're totally pulling inspiration from Tailwind UI components, Shoelace components, and Polaris components.

Using a Shopify Liquid as a Liquid reference website is pretty weird, but it's also a fun challenge which allows us to further dog-food our approach to Liquid components, and even use our components to power the reference (super meta 🤯). Below is some more thinking around technical considerations for the improvements we're going to make.

Background

Before we dive into improvements to the explorer, let's make sure we're all on the same page with how the explorer theme works.

State in Shopify Themes

One of the biggest pillars we've built on with theme components is the separating presentation from state. Components are purely presentation-- they consume state and spit it out in the UI we want to see.

State in Shopify themes can come from the following sources:

• Static values - When you call {% render 'my-component %} you can pass state via hardcoded, static values like {% render 'my-component, transparent: true %}
• Theme Editor Settings - Alternatively you can allow state to be sourced from global, section, or block theme editor settings {% render 'my-component', transparent: section.settings.transparent %}
• Store Configuration - Some state in themes comes from sources scattered throughout Shopify admin, like products, collections, navigations, blogs, etc {% render 'my-component', transparent: product.available %}
• Metafields and Metaobjects - and then of course state can be provided in the form of custom data {% render 'my-component', transparent: product.metafields.attributes.transparent %}

Mapping State to presentation

In order to preview a component, we need to provide it state from these sources. To do this, we include a setup/ folder in each component which provides everything needed to render the component and map state to it.

my-component/
├─ setup/
│  ├─ templates/
│  │  ├─ index.my-component.json
│  ├─ sections/
│  │  ├─ my-component.liquid

• sections/my-component.liquid - Section file that manages loading an instance of the component and exposing theme editor settings we want to be able to adjust within template files. This allows us to render multiple instances of a section with different configurations, e.g. a button component with transparent true in one instance and false in another instance.
• [template].my-component.json - Template files are responsible for loading sections/my-component.liquid in different configurations. These configurations are the presets for a component that we care most about and want to be easy to load. For example, the media-and-text section would show one instance of an image w/ text, another with video w/ text, and another with a 3D model w/ text. Template JSON files should have layout set to false to enforce a clean sandbox for the component that doesn't depend on global side-effects declared outside the component file

Transportability

One of the main uses of the component explorer is to develop components in isolation. A big perk we've observed with our current approach of using sections and template JSON files is that a developer can load a component library into the explorer theme on any store because the components we've made so far do not required store level state. Everything that is needed is included in the theme via theme editor settings.

Let's label this characteristic of loading components and the explorer theme onto any store "transportability."

Digging more into transportability, there are some anticipated hurdles involving store level state we're going to need to get over at some point. In fact we saw a glimpse of them within the reference-components repo and the media w/ text component.

It can be expected that as we roll out components, they could require:

• A product(s) with a certain number of options or configurations like color swatches
• Collection objects with things like featured image setup
• Navigation objects with certain levels of nesting to demonstrate things like meganav
• Metafields
• Store files like video, images, or 3D models

Conclusion: Showcasing a full collection of components needed for a theme project that demonstrates their full capabilities will require on store level state. Developers of a component collection should be developing on a shared dev store that is setup with store level state needed to properly showcase each component.

What about 3rd party developers?

Third party developers who have access to our components and the ability to clone or fork our components might want to preview and develop them with the same store level state (products, collections, navigations, etc.) we have in our main component explorer store.

We cannot provide access to 3rd party developers with Shopify's current permissions setup. Access to themes permission allows editing of the published theme which could result in bad things.

💡 It would be cool if Shopify had a theme permission that only allowed for dev themes to be created. This would allow third party devs to run shopify theme dev with our store and only preview it in their own hidden dev theme

Technical Specifications

Use Page templates for component pages

I propose that we start to use page.my-component.liquid template files as the dedicated reference pages for components. They can acts as the dedicated page that displays everything we want for a component. It fetches the contents of [template].my-component.json files inside of iframes to be displayed in a preview window. It contains references to Liquid params, JS events, and CSS tokens used within the component (Could be dynamically generated from code?)

Using pages has a few unique advantages due to the manual setup that is required at the store level to use them:

• Pages Setup - In order for a page to be shown on a store and page.my-component.json to be used, a store needs to have created a page entry in Admin > Online Store > Pages and to have set that page to use the [page.my-component.json] template. Having a unique page entry at the store level allows another level of setup for the explorer theme which can sit on top of the autogenerated list of template views we currently have.
• Navigation Setup - Since pages require manual setup, we can extend this manual setup level to navigation. We can use Admin > Online Store > Navigation to create our main Explorer navigation

Component Preview Component 😂

The utility-component-preview component will consist of a width adjustable container around an iframe that loads the contents of component template JSON files like index.my-component.json via the Section Render API. Component presets will exist as individual instances of sections in the template JSON file:

{
  "sections": {
    "primary": {
      "type": "button",
      "settings": {
        "type": "primary",
        "text": "Primary Button"
      }
    },
    "icon": {
      "type": "button",
      "settings": {
        "heading": "Icon",
        "type": "primary",
        "icon": "chevron-right"
      }
    },
    "icon-end": {
      "type": "button",
      "settings": {
        "heading": "Icon End Button",
        "type": "primary",
        "text": "Icon Button",
        "icon": "chevron-right"
      }
    }
...

Sections are shown in the preview container one at a time. You can shuffle between component presets with the buttons above the preview which result in the corresponding section to be displayed.

Navigation and component groupings

We can harness Pages in combination with Navigation to organize groups of components (e.g. elements, block, sections, utilities) and list of corresponding components in that group.

We can use this Navigation object to render the primary navigation as well as the home page that lists all components with a grid with a preview image and description. We can define Page metafields such as featured_image and description to populate the content needed for each card on the component listing.

Wrapping things up

The Explorer theme is evolving into more than just a sandbox—it’s becoming a powerful tool for developing, showcasing, and sharing theme components in a way that’s intuitive, portable, and developer-friendly. By focusing on isolating components, improving their presentation with better UX and responsive previews, and embedding comprehensive documentation (like example code, Liquid variables, CSS Tokens, and JS Events), we’re setting the stage for a resource that simplifies adoption and experimentation of theme components.

Looking ahead, transportability remains a key challenge especially around store-level state as components grow more complex. A shared dev store with pre-configured state will be critical for showcasing full capabilities, and while third-party developers can’t yet access it directly, we’re excited to explore ways to make this ecosystem more open—perhaps with future Shopify permission updates or better dev store demo data. For now, we’re doubling down on refining the Explorer’s design and functionality, drawing inspiration from tools like Tailwind UI and Polaris, while leaning into the quirky, meta challenge of building a Liquid reference with Liquid itself.

[chrisberthe]

Overall, I'm liking where this is going, but I have some additional thoughts and questions I'll document here. Fair warning: my thoughts will evolve!

The component explorer should be a frictionless, self-contained tool for developers and designers to reference, preview, and test components in isolation. This is our Storybook—everything you get from running shopify theme component dev should just work, and it should provide a consistent and reliable baseline for all themers.

Keeping the explorer self-contained

Relying on store-level state (like manually creating pages and navigation items) adds friction (even though it's an enhancement). The biggest issue with requiring store setup like this is that:

• For n components, we need to manually create n pages and n navigation items.
• Custom page templates are only available for the published theme, meaning every new component page requires manual setup and must be pushed live before it's accessible.

Right now, shopify theme component dev already generates a list of components dynamically. This works, but we should focus on refining it—improving navigation and grouping using defined conventions rather than adding more manual setup and see how far we can get with this principle.

Relying on our own tools

Instead of depending on store setup, we should see where we can enhance our own tools to automate as much as possible. Improvements to the CLI plugin and explorer theme repo should benefit everyone running shopify theme component dev, without extra steps.

For example:

• Generating documentation dynamically—Liquid params, design tokens, and other metadata should be built and surfaced directly from our components and their conventions we define.
• Enhancing store setup via the Storefront API—Could the CLI populate necessary store data automatically when needed?
• Relying more on static assets—Default to static assets and/or data unless a store is fully set up?
• Leveraging Shopify's generated test store data as a baseline for store setup—Can we use this to automate store setup further? Some things (like navigation) are missing, so we'd need to identify the gaps.

At some point, we'll need to address store-level state, and it's definitely something worth thinking about but until then, I suggest we figure out how to push the limits of what can be done without it and how far we can make the explorer as streamlined and consistent as possible for everyone.