Skip to main content

Installation

This guide will help you set up the RecoApp development environment. This assumes you have good technical knowledge of Node.js, pnpm, and webapp development practices.

Prerequisites​

Before you begin, ensure you have the following installed:

  • Node.js runtime >= 20.0
  • pnpm package manager
  • Git version control

Environment Files​

For each component, you'll need .env files containing API keys, database URLs, and other configurations.

To obtain, contact darren@commera.io or will@commera.io.

Repository Access​

Project repositories are stored within the Craft Applied organisation on GitHub, in the interim.

For access, contact darren@commera.io.

Database Access​

The database is a managed service within the Craft Applied organisation on Xata Lite, in the interim.

For access, contact darren@commera.io.

Installation Guides​

Follow these guides to set up each component of the RecoApp system:

RecoApp API​

The NestJS API backend that processes tracking events from the Shopify pixel and stores them in the Xata database.

Key steps: Clone repository, install dependencies, configure environment variables, start development server, run tests.

RecoApp Shopify​

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

Key steps: Clone repository, install dependencies, configure environment variables, set up database, link to Shopify app, start development server, configure web pixel.

RecoApp Docs​

The Docusaurus documentation site for internal technical documentation (the site you're currently reading).

Key steps: Clone repository, install dependencies, start development server, build documentation.

Quick Start​

For a complete development environment, you'll need to set up all three components:

  1. Start with the API - The backend must be running for the Shopify app to function properly
  2. Set up the Shopify app - Configure the admin interface and web pixel extension
  3. Run the documentation (optional) - If you plan to contribute to documentation
# 1. RecoApp API
git clone git@github.com:craftapplied/recoapp-api.git
cd recoapp-api
pnpm install
# Add .env file, then:
pnpm run start:dev

# 2. RecoApp Shopify
git clone git@github.com:craftapplied/recoapp-shopify.git
cd recoapp-shopify
pnpm install
# Add .env file, then:
pnpm run setup
pnpm run dev

# 3. RecoApp Docs (optional)
git clone git@github.com:craftapplied/recoapp-docs.git
cd recoapp-docs
pnpm install
pnpm run start

Common Issues​

For detailed troubleshooting, see the individual installation guides. Common issues include:

  • Missing .env files - Contact darren@commera.io or will@commera.io
  • Database connection errors - Verify Xata credentials and workspace access
  • Port conflicts - Ensure ports 3000 (API), 50518 (Shopify), and 3003 (Docs) are available
  • Shopify app connection issues - Confirm API is running and RECOAPP_API_BASE_URL is correct

Next Steps​

Once all components are running:

  1. Test the full tracking flow from Shopify storefront to API
  2. Verify events are being stored in the Xata database
  3. Explore the admin interface in the Shopify app
  4. Review the CLAUDE.md files in each directory for detailed architecture information