README.md

@yan-ad/shopify-app-tanstack

This is a community-maintained project inspired by Shopify's app tooling, rebuilt for TanStack Router.

It is not an official Shopify package.

This package is built for the Vite ecosystem, making it easy to build Shopify apps with TanStack Router while keeping familiar Shopify app primitives.

ESM-only package

This package publishes modern ESM output only (.mjs) and "type": "module" metadata.

• Use import syntax in Node and bundlers.
• require('@yan-ad/shopify-app-tanstack') is not supported.

Migration guide

The full migration guide now lives in this repository Wiki: Migration Guide

Warning

If your current project started from a Remix template (for example shopify-app-template-remix), read this official guide first: https://github.com/Shopify/shopify-app-template-react-router/wiki/Upgrading-from-Remix

Package and release info

• npm: https://www.npmjs.com/package/@yan-ad/shopify-app-tanstack
• Install with bun: bun add @yan-ad/shopify-app-tanstack @tanstack/react-router
• Install with npm: npm install @yan-ad/shopify-app-tanstack @tanstack/react-router

This repository uses changelogen to generate and maintain CHANGELOG.md from Conventional Commits.

Common commands:

• bun run changelog (update CHANGELOG.md from commits)
• bun run changelog:bump (bump version and update CHANGELOG.md)
• bun run release (build, bump, changelog, commit, and tag)

Resources

Getting started:

• TanStack Router docs
• Vite docs
• Build a Shopify app
• Project repository

Shopify:

• Intro to Shopify apps
• Shopify CLI
• Shopify App Bridge.
• Polaris Web Components.
• App extensions
• Shopify Functions

Testing your app

This package exports a helper method through @yan-ad/shopify-app-tanstack/test-helpers to simplify testing: testConfig(). This method can be used to pass dummy configuration properties to shopifyApp().

If your testing framework supports setting environment variables, we recommend using an environment variable, for example "SHOPIFY_TESTING" to replace your default config with the config returned from testConfig().

// my-app/app/shopify.server.ts
import { testConfig } from "@yan-ad/shopify-app-tanstack/test-helpers";
...
const config = {
  ...
};

if (process.env.SHOPIFY_TESTING) {
  Object.assign(config, testConfig());
}

const shopify = shopifyApp(config);
...

testConfig() accepts a config object as an optional parameter. The config values provided override the default config values returned by testConfig(). This is especially useful for integration testing and end-to-end testing to ensure shopifyApp() reads the sessions from the development database.

// my-app/app/shopify.server.ts
import { testConfig } from "@yan-ad/shopify-app-tanstack/test-helpers";
...
const sessionStorage = new PrismaSessionStorage(prisma);
const config = {
  ...
  sessionStorage,
  ...
};

if (process.env.SHOPIFY_TESTING) {
  Object.assign(config, testConfig());
}

if (process.env.SHOPIFY_TESTING === "e2e") {
  Object.assign(config, testConfig({ sessionStorage }));
}
...

Gotchas / Troubleshooting

For common issues, open or search issues in this repository: https://github.com/yanuaraditia/shopify-app-tanstack/issues