How to Build a Shopify Public App from Scratch: A Developer's Guide

Introduction to Shopify App Development

Developing a public app for Shopify is one of the most lucrative opportunities for modern web developers. With millions of merchants globally seeking tools to enhance their storefronts, the Shopify App Store serves as a massive marketplace for innovative solutions. Unlike custom apps, which are built for a single store, public apps are designed to be installed by any merchant, offering scalability and a recurring revenue model through the Shopify Billing API.

In this comprehensive guide, we will walk through the technical architecture, the essential tools, and the step-by-step process of building a Shopify public app from scratch. Whether you are a seasoned developer or new to the ecosystem, understanding the modern Shopify stack—including the Shopify CLI, App Bridge, and Polaris—is crucial for success.

Step 1: Setting Up Your Development Environment

Before writing a single line of code, you need to configure your environment. Shopify has standardized its development workflow around the Shopify CLI (Command Line Interface), which automates the creation of app credentials, tunneling, and deployment.

Prerequisites

A Shopify Partner Account: This is where you will manage your apps and create development stores.
Node.js (Active LTS version): Most modern Shopify apps use Node.js for the backend.
Package Manager: npm, yarn, or pnpm.
A Development Store: A free sandbox environment provided by Shopify to test your app.

Once your accounts are ready, install the Shopify CLI globally on your machine using the following command:

npm install -g @shopify/cli @shopify/app

The CLI handles the heavy lifting of OAuth authentication and provides a local development server that mirrors the Shopify environment.

Step 2: Initializing Your App with Shopify CLI

Shopify provides official templates to jumpstart your development. The most popular stack includes a Node.js backend with an Express or Remix framework and a React frontend. To start your project, run the following command in your terminal:

shopify app init

Follow the prompts to name your app and select your preferred language. The CLI will scaffold a complete directory structure including:

/web: Contains the frontend code (React) and backend API (Node/Express).
/extensions: Where you will build Theme App Extensions or Function extensions.
shopify.app.toml: The configuration file that defines your app’s permissions (scopes) and URLs.

After initialization, navigate into your project folder and start the development server by running shopify app dev. This command will prompt you to log into your partner account and select a development store for testing.

Step 3: Understanding OAuth and Scopes

Public apps require a secure handshake with Shopify stores, known as OAuth. When a merchant installs your app, they must grant permission for your app to access specific data, such as orders, products, or customer information.

Defining API Scopes

In your shopify.app.toml file, you must declare the scopes your app requires. For example, if you are building an inventory management tool, you will need:

scopes = "read_products, write_products, read_inventory"

It is a best practice to follow the principle of least privilege—only request the scopes your app absolutely needs to function. During the installation flow, Shopify will present these requested permissions to the merchant. Once accepted, Shopify generates an offline or online access token that your backend uses to make authenticated requests to the Admin API.

Step 4: Building the User Interface with Polaris and App Bridge

To ensure a seamless experience for merchants, Shopify requires (or strongly encourages) that apps look and feel like the Shopify Admin. This is achieved using two core libraries: Shopify Polaris and Shopify App Bridge.

Shopify Polaris

Polaris is a React component library that provides the design system for Shopify. Instead of building buttons, modals, or data tables from scratch, you use Polaris components to ensure visual consistency.

import {Page, Layout, Card, Button} from '@shopify/polaris';

function Dashboard() {
  return (
    <Page title="App Dashboard">
      <Layout>
        <Layout.Section>
          <Card sectioned>
            <p>Welcome to your new public app!</p>
            <Button primary>View Analytics</Button>
          </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

Shopify App Bridge

App Bridge is a JavaScript library that allows your app (which lives in an iframe) to communicate with the host Shopify Admin. It enables features like toast notifications, navigation menu updates, and modal triggers that exist outside the app's iframe.

Step 5: Handling Webhooks for Real-Time Data

A robust public app must react to changes in the store without constant polling. This is where Webhooks come in. Webhooks are HTTP callbacks sent by Shopify when specific events occur, such as orders/create or app/uninstalled.

When building a public app, you must implement mandatory GDPR webhooks (customers/data_request, customers/redact, and shop/redact) to comply with Shopify's App Store requirements. The Shopify CLI facilitates webhook registration by allowing you to define them in your configuration and providing a local tunnel (via Cloudflare or ngrok) to receive them during development.

Conclusion: Preparing for the App Store

Building the app is only the first half of the journey. To go live as a public app, you must submit your app for review by the Shopify App Quality team. This involves ensuring your app meets functional, security, and UX standards. You will also need to set up a pricing model using the Shopify Billing API, which handles all subscription and one-time charges, ensuring you get paid securely.

By following this modular approach—setting up the CLI, mastering OAuth, utilizing Polaris, and implementing webhooks—you lay a solid foundation for a scalable Shopify public app. The ecosystem is constantly evolving, so stay tuned to the Shopify Changelog to keep your app compatible with the latest API versions.