Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 55 ยท Orientation

Creating an App with the CLI

Create your first Shopify app with shopify app init, tour the React Router template folder by folder and learn what shopify app dev and its tunnel do for you.

With your tools installed (Tooling and Setup), you can create a real app in a few minutes. The Shopify CLI downloads a template, registers an app record in your developer account and wires up a local development loop: your code runs on your machine, a tunnel gives it a public address, and Shopify's servers can reach it as if it were deployed.

This lesson walks through that sequence and then tours the files you get. As everywhere in this track, the commands and files below are real but read-only on this site, because we cannot run a CLI or a tunnel in your browser. The runnable part is a small configuration parser, a stand-in that shows what a tool does when it reads the app's main settings file. We will say which is which.

Creating the app

Open a terminal in a folder where you keep projects and run:

Terminal
shopify app init

The CLI asks a few questions. The wording changes between CLI versions, but you can expect these:

  1. A name for the app. This becomes the app's name in your dashboard and the folder name. You can change the display name later.
  2. A template. Choose the React Router template (the current default; older tutorials mention Remix, which the template was based on before). There are also options to start with no UI, or to use a template from a Git URL.
  3. A package manager, usually npm.

The CLI then clones the template, installs dependencies and creates the app record on Shopify. When it finishes, you have a folder with a complete, runnable app. Change into it:

Terminal
cd my-first-app

The prompts, defaults and some command flags change over time. Treat the steps here as the shape of the process and trust shopify app init --help for the exact options in your version.

Starting the development loop

From the app folder, run:

Terminal
shopify app dev

This one command does several things:

  • It asks which development store to use (and which app to connect, the first time) and remembers your choice.
  • It starts a tunnel, a secure public URL that forwards to your local server. Shopify needs a public address because the admin loads your app in an iframe from the merchant's browser, and Shopify's servers send webhooks to you.
  • It updates the app's URLs on Shopify to point at the tunnel, so you do not edit them by hand. (A setting in the build section of the configuration controls this.)
  • It starts your web server and builds any extensions, reloading them as you edit.
  • It prints a link to install the app on your development store, and offers keyboard shortcuts in the terminal, such as one to open a preview and one to open GraphiQL, a browser tool for trying Admin API queries against your store.

Follow the install link, approve the permissions on the consent screen, and the app opens inside the Shopify admin. You are now running code on your machine from inside a real store.

sequenceDiagram
    participant Dev as You
    participant CLI as Shopify CLI
    participant Tun as Tunnel
    participant App as Local server
    participant Shop as Shopify admin
    Dev->>CLI: shopify app dev
    CLI->>App: start server
    CLI->>Tun: open public URL
    CLI->>Shop: point app URLs at the tunnel
    Shop->>Tun: load app in iframe
    Tun->>App: forward request

The tunnel exists so Shopify, which is on the public internet, can reach the server on your laptop.

Because the tunnel URL changes between sessions, never hard-code it. Read it from the environment, the way the template does. If you stop shopify app dev and start it again, a new URL may be assigned and the CLI updates Shopify again.

A tour of the template

Names move around between template versions, so expect small differences. The overall layout is stable:

TEXT
my-first-app/
  app/
    routes/            pages and API endpoints (one file per route)
    shopify.server.js  the app's Shopify configuration and helpers
    db.server.js       the Prisma database client
    root.jsx           the page shell
  extensions/          UI extensions and functions (empty at first)
  prisma/
    schema.prisma      database tables (sessions at the start)
  shopify.app.toml     the app's configuration
  shopify.web.toml     how to build and run the web part
  package.json
  .env                 secrets (created by the CLI; never commit it)

Here is what to look at first.

  • shopify.app.toml is the single most important file. It declares the app's name, URLs, permissions, webhooks and more. The next lesson, App Configuration with shopify.app.toml, covers it in detail.
  • app/shopify.server.js calls the library's setup function once, with the API key, secret, scopes, API version and session storage. Every route imports the helpers from here, for example authenticate. Later lessons on authentication open this file again.
  • app/routes/ holds the pages. In this router, file names become URLs, and dots become slashes. A file named app._index.jsx is the app's home page, and app.additional.jsx is a second page under /app. Files named webhooks.app.uninstalled.jsx hold webhook handlers. Routes export a loader (runs on the server to fetch data), an action (handles form submits) and a component.
  • prisma/schema.prisma defines the database. The template starts with a Session model and SQLite, which is fine for development. Databases and Session Storage in Production covers moving to a real database.
  • extensions/ is empty until you run shopify app generate extension. App Extensions Overview explains what you can put there.
  • .env is created and updated by the CLI. It holds values such as the app's API key and secret. Keep it out of Git. The template's .gitignore already does this.

A minimal route looks like this (read-only, trimmed from the template's pattern):

JavaScript
// app/routes/app._index.jsx (read-only sketch)
import { authenticate } from "../shopify.server";

export const loader = async ({ request }) => {
  const { admin } = await authenticate.admin(request);
  // admin.graphql(...) would call the Admin API as this shop
  return null;
};

export default function Index() {
  return <p>Hello from inside the Shopify admin.</p>;
}

The first line of the loader is the key idea: before anything else, the route proves the request comes from a valid shop session. Authenticated Requests and Route Protection explains how.

What the CLI reads: a configuration parser

Many CLI features start by reading shopify.app.toml. TOML is a plain-text configuration format: key = "value" lines, [table] headers that group keys, and [[array.of.tables]] headers that add one more entry to a list. The script below is a small stand-in parser that handles just those pieces, so you can see how a tool turns text into an object. A real tool uses a full TOML library; this one is for learning and ignores many details of the format (multi-line strings, inline tables, dates).

Run it, then change the text and run it again.

JS Parse a tiny shopify.app.toml

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice what the parsed object shows: tables become nested objects, and [[webhooks.subscriptions]] becomes an array inside webhooks. That is why a TOML file can describe several webhook subscriptions by repeating the header.

Reading the environment the way the template does

The template never writes your API secret into source code. The CLI puts it in .env (and a hosting provider has its own place for environment variables). The server code reads from process.env. Another small stand-in shows why a missing variable should stop the app at startup instead of failing later in confusing ways:

JS Fail fast on missing environment values

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The real variable names can differ between template versions, so read your own .env and shopify.server.js; the habit (validate once, fail fast, never log secrets) is what matters.

Common problems

  • The app opens a blank page or an error in the admin. Check the terminal for server errors first. Then confirm the tunnel is still running; if you stopped and restarted shopify app dev, reload the admin page.
  • "Port already in use". Another process holds the port. Stop it or let the CLI choose another.
  • Changes to the TOML file do not seem to apply. Some settings are sent to Shopify when shopify app dev starts, and others only when you run shopify app deploy. The next lesson explains the difference.
  • Prisma errors after pulling a template update. Run the Prisma generate and migrate commands listed in the template's scripts.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does shopify app dev start a tunnel?

    The admin loads your app from the browser and Shopify sends webhooks to your URL, so the server on your laptop needs a public address.
  2. 2. Which file declares an app's name, URLs, scopes and webhook subscriptions?

    shopify.app.toml is the app's configuration file. The .env file holds secrets, and the other two files are code and database definitions.
  3. 3. What does a [[webhooks.subscriptions]] header in TOML mean?

    Double brackets add an item to an array of tables, so repeating the header describes several subscriptions.
  4. 4. Where should the app's API secret live?

    Secrets belong in environment configuration. Source code and public pages are visible to people who should not see the secret.

Summary

  • shopify app init creates the app record and a working project from a template (React Router today).
  • shopify app dev runs the server, opens a tunnel, updates the app URLs, builds extensions and gives you an install link.
  • The key places are shopify.app.toml, app/shopify.server.js, app/routes/, prisma/schema.prisma, extensions/ and .env.
  • Routes start with a call such as authenticate.admin(request) to prove the request is from a valid shop.
  • The CLI commands and template files are real but read-only here; the TOML parser and environment loader are stand-ins that show the underlying ideas.

Next: App Configuration with shopify.app.toml