Skip to main content

RecoApp Shopify Installation

The recoapp-shopify is a Shopify app built with Remix that provides the merchant-facing admin interface and web pixel extension for tracking customer behaviour.

Prerequisites​

  • Node.js runtime >= 20.0
  • pnpm package manager
  • Git version control
  • Access to the Craft Applied GitHub organisation
  • Shopify Partner account with app credentials
  • RecoApp API running and accessible

Installation Steps​

1. Clone the repository​

git clone git@github.com:craftapplied/recoapp-shopify.git
cd recoapp-shopify

2. Install dependencies​

pnpm install

3. Configure environment variables​

Obtain the .env file from darren@commera.io or will@commera.io and place it in the recoapp-shopify directory.

Required environment variables include:

  • Shopify app credentials (API key, secret)
  • RECOAPP_API_BASE_URL - URL of your running RecoApp API instance
  • Database connection details for session storage

4. Set up the database​

Generate the Prisma client and run database migrations:

pnpm run setup

This command initialises the SQLite database used for session storage.

If connecting to an existing Shopify app:

pnpm run config:link

Follow the interactive prompts to link to your Shopify app configuration.

To switch between app configurations:

pnpm run config:use

6. Start the development server​

pnpm run dev

This will:

  • Start the Remix development server on port 50518
  • Start a Shopify CLI tunnel for local development
  • Open the app in your development store

Web Pixel Configuration​

The web pixel extension tracks customer behaviour on the Shopify storefront.

Important configuration​

In the Shopify admin, ensure the web pixel extension has the shopify_shop_id setting configured with the shop's Shopify GID.

Format: gid://shopify/Shop/XXXXX

This is required for proper event tracking and linking events to the correct shop in the database.

Web pixel source code​

  • Source TypeScript: extensions/recoapp-web-pixel/src/
  • Built output: extensions/recoapp-web-pixel/dist/

Edit TypeScript files in src/ - the build process handles compilation to dist/.

Development Workflow​

Building the app​

Build both the app and extensions:

pnpm run build

Deploying to Shopify​

Deploy the app and extensions:

pnpm run deploy

Running tests​

Lint the codebase:

pnpm run lint

Project Structure​

Key components:

  • app/ - Remix application routes and components
  • extensions/recoapp-web-pixel/ - Web pixel extension for storefront tracking
  • prisma/ - Database schema and migrations for session storage
  • pnpm-workspace.yaml - pnpm workspace configuration

Shopify App Scopes​

The app requires the following Shopify API scopes:

  • write_products - Access to product data
  • write_pixels - Ability to install and configure web pixels
  • read_customer_events - Access to customer event data

Important Notes​

  • Uses pnpm workspace configuration for managing dependencies
  • Web pixel sends tracking events to RECOAPP_API_BASE_URL (external API, not embedded in Shopify)
  • Session storage uses Prisma ORM with SQLite
  • UI built with Shopify Polaris components
  • OAuth handled by @shopify/shopify-app-remix
  • Development URLs: Remix server on port 50518, storefront on port 9293
  • Favour modern functional programming patterns (see recoapp-shopify/CLAUDE.md for coding style)

Troubleshooting​

Development server won't start​

  • Verify all environment variables are set correctly
  • Check that port 50518 is not in use by another process
  • Ensure pnpm run setup completed successfully
  • Try clearing the Shopify CLI cache: shopify app config clear

App won't install on development store​

  • Verify Shopify app credentials in .env are correct
  • Ensure your Shopify Partner account has access to the app
  • Check that the app is configured for development stores
  • Review the Shopify Partner Dashboard for any configuration issues

Web pixel not tracking​

  • Verify RECOAPP_API_BASE_URL points to a running API instance
  • Check that shopify_shop_id is configured correctly in the pixel settings
  • Inspect browser console for JavaScript errors
  • Verify CORS is configured correctly on the API to accept requests from the storefront

Prisma/database issues​

  • Delete prisma/dev.db and run pnpm run setup again
  • Ensure Prisma schema matches your environment
  • Check file permissions on the database file

Next Steps​

  • Review recoapp-shopify/CLAUDE.md for detailed architecture and coding standards
  • Configure the web pixel shopify_shop_id setting in your development store
  • Test the full event tracking flow from storefront to API
  • Explore the admin interface and familiarise yourself with Polaris components