Skip to main content

RecoApp API Installation

The recoapp-api is a NestJS API backend that processes tracking events from the Shopify pixel and stores them in the Xata database.

Prerequisites​

Installation Steps​

1. Clone the repository​

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

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-api directory.

Required environment variables:

  • XATA_API_KEY - API key for Xata database access
  • DATABASE_URL - PostgreSQL connection string
  • XATA_BRANCH - Xata branch name (e.g., main or development)
  • APP_NAME - Application identifier
  • CORS_ORIGINS - Comma-separated list of allowed CORS origins

4. Start the development server​

pnpm run start:dev

The API will start with hot reload enabled, automatically restarting when you make code changes.

For debugging with inspector enabled:

pnpm run start:debug

5. Verify installation​

Run the test suite to ensure everything is configured correctly:

pnpm run test

For test coverage:

pnpm run test:cov

Development Workflow​

Building for production​

pnpm run build

Running tests in watch mode​

pnpm run test:watch

End-to-end tests​

pnpm run test:e2e

Code quality​

Lint and auto-fix code:

pnpm run lint

Format code with Prettier:

pnpm run format

Project Structure​

Key directories and files:

  • src/pixels/ - PixelsModule handling incoming Shopify pixel events
  • src/xata/ - XataModule providing database access (XataClient and Kysely)
  • src/services/ - Event-specific services (ProductViewedService, ProductAddedToCartService)
  • src/xata.ts - Auto-generated file (DO NOT edit manually - regenerated by Xata CLI)

Important Notes​

  • DO NOT edit src/xata.ts - this file is generated by the Xata CLI and will be overwritten
  • The XataService provides global database access with both XataClient and Kysely query builder instances
  • CORS is configured for specific Shopify store origins via the CORS_ORIGINS environment variable
  • All incoming pixel events must include a shop_id field to link events to the shops table

Troubleshooting​

API won't start​

  • Verify your .env file contains all required variables
  • Check that XATA_API_KEY and DATABASE_URL are valid credentials
  • Ensure no other service is using the API port (default: 3000)
  • Check the console for environment validation errors (uses Joi schemas)

Database connection issues​

  • Verify DATABASE_URL is correctly formatted
  • Confirm you have access to the Xata workspace
  • Check that XATA_BRANCH matches an existing branch in Xata
  • Test the connection with Xata CLI if available

Test failures​

  • Ensure all environment variables are set (tests may require valid config)
  • Clear any cached data: rm -rf dist/ node_modules/.cache/
  • Reinstall dependencies: rm -rf node_modules/ && pnpm install

Next Steps​

  • Review recoapp-api/CLAUDE.md for detailed architecture information
  • Read recoapp-api/docs/SCHEMA_DATABASE.md for database schema documentation
  • Read recoapp-api/docs/SCHEMA_EVENTS.md for event schema specifications
  • Set up the Shopify app to send events to your API instance