Shopify App Template - Remix

This template uses Prisma to manage session data. By default, it is configured to use an SQLite database via the schema defined in prisma/schema.prisma.

While SQLite is suitable for single-instance production apps, you can switch to other databases (MySQL, PostgreSQL, MongoDB, or Redis) by:

1. Updating the datasource provider in prisma/schema.prisma.
2. Using a different SessionStorage adapter package from @shopify/shopify-api.

Commonly used database providers include:

• MySQL: Digital Ocean, Planet Scale, Amazon Aurora, Google Cloud SQL
• PostgreSQL: Digital Ocean, Amazon Aurora, Google Cloud SQL
• Redis: Digital Ocean, Amazon MemoryDB
• MongoDB: Digital Ocean, MongoDB Atlas

While you can register shop-specific webhooks in the afterAuth hook using shopify.registerWebhooks, this approach can be unreliable because afterAuth only runs during initial installation or when an access token expires. During normal development, subscriptions may not update.

Recommended: Declare app-specific webhooks in your shopify.app.toml file. Shopify will automatically update these subscriptions every time you run npm run deploy.

To create a new project using the Shopify App Template - Remix, use the shopify app init command with the template URL.

shopify app init --template=https://github.com/Shopify/shopify-app-template-remix

By default, this template is configured for embedded apps. If you need to build a non-embedded app, apply these four changes:

1. In shopify.app.toml, set embedded = false.
2. In ./app/shopify.server.js|ts, pass isEmbeddedApp: false to the shopifyApp() function.
3. In /app/routes/app.jsx|tsx, set the isEmbeddedApp prop to false on the AppProvider component.
4. Remove the @shopify/app-bridge-react dependency from package.json and vite.config.ts|js, and remove all imports from that package (e.g., NavMenu, TitleBar, useAppBridge).

When hosting on Vercel, it is recommended to use the Vercel Preset. You must also ensure that imports intended for @remix-run/node are replaced with imports from @vercel/remix.

Update your vite.config.ts to include the vercelPreset in the Remix plugin configuration:

import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig, type UserConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";
import { vercelPreset } from '@vercel/remix/vite';

export default defineConfig({
  plugins: [
    remix({
      ignoredRouteFiles: ["**/.*"],
      presets: [vercelPreset()],
    }),
    tsconfigPaths(),
  ],
});

Run the following command to start your local development environment. The Shopify CLI will handle logging into your partner account, connecting to your app, providing environment variables, updating remote configuration, and creating a tunnel.

shopify app dev

To build your application for production, use the build command corresponding to your package manager:

Using npm:

npm run build

Using yarn:

yarn build

Using pnpm:

pnpm run build

The template is currently set up for Node v18.20+, but @shopify/polaris v13 requires Node v20+. To upgrade:

1. Upgrade your local and deployment Node version to v20.10 or higher.
2. Update your Dockerfile to use FROM node:20-alpine instead of node:18-alpine.

Before setting up the template, ensure you have the Shopify CLI installed globally on your machine.

npm install -g @shopify/cli@latest

This template uses SQLite by default. To use MongoDB, you must modify your schema and Prisma configuration.

1. Mapping the ID field

Prisma expects the ID field to be the ID of the session, not the MongoDB _id field. Add a field to your Session model that maps the _id attribute to an id field:

model Session {
  session_id  String    @id @default(auto()) @map("_id") @db.ObjectId
  id          String    @unique
  ...
}

2. Handling migrations

MongoDB does not support prisma migrate. Instead, use prisma db push. Update your shopify.web.toml file to use the following commands:

[commands]
predev = "npx prisma generate && npx prisma db push"
dev = "npm exec remix vite:dev"

3. Replica Set requirement

Prisma requires your MongoDB server to be running as a replica set to perform transactions.

Embedded Shopify apps run inside an iFrame and must maintain user sessions. To prevent navigation or redirection from breaking the app session, follow these rules:

1. Links: Use Link from @remix-run/react or @shopify/polaris. Do not use standard <a> tags.
2. Redirects: Use the redirect helper returned from authenticate.admin. Do not use the standard redirect from @remix-run/node.
3. Forms: Use useSubmit or the <Form/> component from @remix-run/react. Do not use lowercase <form/> tags.

// Correct way to redirect in an embedded app
const { redirect } = await authenticate.admin(request);
return redirect('/path');

Webhooks created manually via the Shopify Admin will fail HMAC validation because the payload is not signed with your app's secret key. To fix this, use one of these two methods:

1. App-specific webhooks (Recommended): Define them in your shopify.app.toml file.
2. Programmatic subscriptions: Create subscriptions using the shopifyApp object.