gather-vue

Gather Vue

Gather Vue is the Vue 3 customer referral widget used for referral campaigns, pop-ups, and the campaign editor. It runs inside an iframe on merchant sites, fetches campaign configuration from Gather Rails, and communicates with the host page through window.postMessage.

How it fits into Gather

Merchant site
  -> gather-integration evaluates targeting and creates an iframe
  -> gather-vue renders the campaign inside the iframe
  -> gather-rails supplies campaign data and handles API requests

The built widget is published as an npm package for jsDelivr and is also deployed to S3 behind CloudFront.

Requirements

• Node.js 24 LTS, pinned in .nvmrc
• pnpm 10, matching the version used by GitHub Actions
• Gather Rails running locally if you need live API responses

Setup

git clone git@github.com:gathercustomers/gather-vue.git
cd gather-vue
nvm install
nvm use
corepack enable
corepack prepare pnpm@10 --activate
cp .env.development.example .env.local
pnpm install
pnpm dev

The development example points VITE_GATHER_URL at a local Gather Rails server on port 3000. Add any credentials needed for the integrations you are testing to .env.local; the file is ignored by Git and must not be committed.

The Vite development server prints the local URL when it starts.

Commands

Before committing, run:

pnpm type-check
pnpm lint
pnpm test:unit --run

End-to-end tests

Install the Playwright browsers once:

pnpm exec playwright install

Then build the app and run the suite:

pnpm build
pnpm test:e2e

Useful variants include:

pnpm test:e2e --project=chromium
pnpm test:e2e --debug

Releases and deployment

Feature work merges into develop. Release commits are promoted to staging for the staging npm/S3/CloudFront deployment, then to master for production. npm publishing runs in GitHub Actions with OIDC trusted publishing; it does not use a long-lived npm publish token.

Do not publish a release manually. Follow RELEASES.md for the versioning, branch promotion, trusted-publisher configuration, and deployment verification process.

Further documentation

• docs/ARCHITECTURE.md — application architecture, state, iframe communication, and build design
• RELEASES.md — release and deployment runbook
• docs/OBSERVABILITY.md — frontend telemetry setup
• CUSTOMER_README.md — customer integration examples

Recommended editor

Visual Studio Code with Vue - Official provides Vue and TypeScript language support. Disable Vetur if it is installed.