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

Introduction to Shopify Public App Development

Building a Shopify public app is one of the most lucrative opportunities for modern web developers. Unlike private apps, which are tailored for a single store, public apps are listed on the Shopify App Store and can be installed by millions of merchants worldwide. This scalability makes them the gold standard for SaaS products within the e-commerce ecosystem.

However, the barrier to entry involves more than just writing code. You must navigate OAuth authentication, comply with Shopify’s Mandatory Webhooks, and ensure your UI matches the merchant experience using the Polaris design system. In this guide, we will walk through the entire lifecycle of creating a public app from scratch using the modern Shopify CLI and Node.js framework.

Step 1: Setting Up Your Development Environment

Before writing your first line of code, you need a robust environment. Shopify has streamlined this process significantly with the Shopify CLI (Command Line Interface). This tool handles app creation, tunneling, and deployment.

Prerequisites

• A Shopify Partner Account: This is where you will manage your apps and create development stores.
• Node.js: Ensure you have the latest LTS version installed.
• Package Manager: npm, yarn, or pnpm.
• Cloudflare Tunnel or Ngrok: Shopify requires a secure HTTPS tunnel to communicate with your local development server.

To start, open your terminal and run the following command to initialize a new app project:

npm init @shopify/app@latest

Follow the prompts to name your app and select your preferred language (JavaScript/TypeScript). The CLI will scaffold a project structure including a frontend (React-based) and a backend (Node/Express or Remix).

Step 2: Understanding OAuth and App Authentication

Public apps require a secure handshake called OAuth to access a merchant's store data. When a merchant clicks "Install," Shopify redirects them to your app with a temporary code. Your app must then exchange this code for an access token.

The Authentication Flow

1. The merchant initiates the installation request.
2. Your app redirects the merchant to Shopify’s authorization screen.
3. The merchant grants permissions (scopes) like read_products or write_orders.
4. Shopify sends an authorization code to your redirect URI.
5. Your backend exchanges the code for a permanent access token.

Thankfully, the modern Shopify App Template handles most of this boilerplate code for you using the @shopify/shopify-api library. You simply need to define your required scopes in the shopify.app.toml configuration file.

Step 3: Designing the UI with Shopify Polaris

Shopify merchants expect a consistent experience. If your app looks like a foreign website, trust decreases. To solve this, Shopify provides Polaris, a comprehensive design system and React component library.

Using Polaris ensures that your buttons, modals, and data tables look identical to the Shopify Admin. Here is a basic example of a Polaris page structure:

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

function Dashboard() {
  return (
    <Page title="App Dashboard">
      <Layout>
        <Layout.Section>
          <Card padding="500">
            <Text as="h2" variant="headingMd">Welcome to your App</Text>
            <p>Start managing your store data here.</p>
          </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

By sticking to these components, you not only improve user experience but also pass the Shopify App Store review process much faster.

Step 4: Working with GraphQL and Webhooks

Once authenticated, your app needs to interact with store data. Shopify recommends using the GraphQL Admin API over the REST API because it is more efficient and provides access to the latest features.

Querying Data

To fetch the first ten products from a store, you would send a POST request to the GraphQL endpoint with a query like this:

{
  products(first: 10) {
    edges {
      node {
        id
        title
      }
    }
  }
}

Handling Webhooks

Webhooks are critical for public apps. They allow your server to receive real-time notifications when events occur, such as ORDERS_CREATE or APP_UNINSTALLED. Shopify requires public apps to handle three mandatory webhooks regarding GDPR data requests. Failure to implement these will result in your app being rejected from the App Store.

Step 5: Deployment and App Store Submission

After testing your app in a development store, it’s time to go live. You can host your app on platforms like Heroku, Vercel, or AWS. Ensure your environment variables (API Key, Secret Key, and Host URL) are correctly updated in your production environment.

Before submitting to the App Store, perform a final audit:

• Verify that the app handles 404 and 500 errors gracefully.
• Ensure the app is mobile-responsive.
• Check that all "Mandatory Webhooks" are correctly configured in the Partner Dashboard.
• Create a clear listing with screenshots and a detailed description of the app’s value proposition.

Conclusion

Building a Shopify public app from scratch is a journey that combines full-stack development with e-commerce strategy. By leveraging the Shopify CLI, mastering OAuth, and adhering to the Polaris design language, you can build powerful tools that help merchants succeed. While the initial setup might seem complex, the ability to reach millions of users through the Shopify ecosystem makes it a highly rewarding endeavor for any developer.