@brighterly/lib-core-functions

Front-end core functions — helpers and the Amplitude analytics, with utils and composables to come.

Analytics

Amplitude tracking shared by the apps, on its own entry point: @brighterly/lib-core-functions/analytics.

An app that uses it installs the Amplitude SDK (an optional peer dependency — apps without analytics skip it):

pnpm add @amplitude/marketing-analytics-browser

import {
  flushBeforeLeave,
  initAmplitude,
  setUserPropsFromQuery,
  trackEvent,
} from '@brighterly/lib-core-functions/analytics'

// once per page load; the SDK is loaded lazily, calls made before that are queued
initAmplitude({
  apiKey: config.amplitudeApiKey,
  serverUrl: config.amplitudeServerUrl,
  userId,
  deviceId,
  userProps: { environment, user_type: 'customer', brand },
  // attached to every event
  eventProps: () => ({ customer_type: customer.type, kid_id: kid.id, device_type: deviceType }),
  debug: import.meta.env.DEV, // logs the props the registries dropped
})

setUserPropsFromQuery() // utm_*, gclid… of the landing URL + their `initial_` variants

trackEvent('Button_click', { feature: 'classroom', name: 'join_lesson' })

flushBeforeLeave() // right before a `window.location` change, so queued events are not lost

• Event names, event props and user props come from registries — unknown names are compile errors, and props outside the registry are dropped at runtime. What each one means: src/analytics/docs/ (EVENTS.md, EVENT_PROPS.md, USER_PROPS.md, NAMING.md), also shipped in dist/analytics/docs/.
• The registries are JSON in src/analytics/config/, exported raw for the backend: @brighterly/lib-core-functions/analytics/amplitude.json and …/analytics/user-props.json.
• Changing them: edit the JSON and its doc together; make validate:analytics checks both, and make build runs it first.
• GTM is not part of the library.

Publishing New Versions

This project uses GitHub Actions for automatic deployment to NPM. To release a new version, follow these steps:

1. Bump the version Use one of the following commands to update package.json and create a git tag:

   pnpm version patch   # 1.0.0 -> 1.0.1 (bug fixes)
   pnpm version minor   # 1.0.0 -> 1.1.0 (new features)
   pnpm version major   # 1.0.0 -> 2.0.0 (breaking changes)

2. Push repo to github:

   git push

3. NPM release will be created automatically

Git Hooks

Pre-commit hook

Runs pnpm lint, pnpm typecheck and pnpm test on staged .ts / .vue files and on the analytics JSON / docs in src/analytics/.

Prepare:

chmod +x _tools/git/pre-commit
ln -s ../../_tools/git/pre-commit .git/hooks/pre-commit

Pre-push hook

Validates that a release tag (v*) matches the version in package.json before pushing.

Prepare:

chmod +x _tools/git/pre-push
ln -s ../../_tools/git/pre-push .git/hooks/pre-push

Dependencies

Install deps:

pnpm install

First time

pnpm publish --no-git-checks --access public --registry=https://registry.npmjs.org/ --//registry.npmjs.org/:_authToken=$NODE_AUTH_TOKEN