Skip to content

Shared Core & UI

SMACKZ uses two shared npm packages to keep common code consistent across all frontend applications. These packages are published to GitHub Packages and consumed by Admin, Websites, Mobile, and other services.

Packages

Package Scope Contents
@smackz-llc/shared-core Auth, API, types, catalog Authentication utilities, API client functions, TypeScript type definitions, constants, data catalog entity definitions
@smackz-llc/shared-ui UI components Reusable React components shared across apps
@smackz-llc/page-renderer Page rendering Dynamic page section rendering (see Page Renderer)

Publishing Strategy

Packages use a prerelease dist-tag strategy to keep QA builds on bleeding-edge versions without affecting production:

Branch Version Format npm Tag Example
main X.Y.Z latest 2.0.5
qa X.Y.Z-qa.{run} qa 2.0.5-qa.17

Build Order

When pushing changes to qa across multiple packages:

  1. Push shared-core first, wait for its workflow to complete
  2. Push shared-ui (it picks up the new shared-core@qa automatically)
  3. page-renderer is independent -- push anytime

How Dependent Apps Get QA Packages

Cloudflare Pages (Admin, Websites)

A prebuild script in package.json runs before every build:

"prebuild": "node scripts/install-qa-packages.js"

The script checks CF_PAGES_BRANCH: - If qa -- installs @smackz-llc/shared-core@qa, @smackz-llc/shared-ui@qa - Otherwise -- uses whatever version is in package-lock.json

GitHub Actions (Restaurant-Websites)

A conditional step in the deploy workflow overrides packages when deploying from qa.

Local Development

In Docker development, shared packages are symlinked so changes are reflected immediately without publishing. The Docker Compose configuration mounts local package directories into the containers.

Authentication for Cross-Repo Packages

Context Token
Publishing GITHUB_TOKEN (automatic)
Installing own-repo packages GITHUB_TOKEN (automatic)
Installing cross-repo packages PACKAGES_READ_TOKEN (Classic PAT with read:packages)

The PACKAGES_READ_TOKEN is a Classic PAT (not fine-grained, as fine-grained PATs do not support package permissions).

Verification

# Check latest QA version
npm view @smackz-llc/shared-core --tag qa

# Check latest stable version
npm view @smackz-llc/shared-core --tag latest

Data Catalog

shared-core includes a catalog/ directory that serves as the single source of truth for data entity definitions across all SMACKZ services. It contains:

  • catalog/entities/ -- YAML definitions for each lakehouse entity (orders, users, restaurants, etc.)
  • catalog/schema/entity.schema.json -- JSON Schema for entity YAML validation
  • catalog/validate.py -- Validation script (JSON Schema compliance, cross-entity references, duplicate fields)
  • catalog/loader.ts -- TypeScript loader (loadCatalog(), getEntity())

The catalog drives the lakehouse Data Catalog metadata layer and Data Quality check generation. Quality fields like null_expectation, freshness, and table_type are defined directly in the entity YAML and auto-generate quality checks in the lakehouse pipeline.

See the Data Catalog wiki page for full details on quality fields and the contributor guide.

Key Files

  • shared-core/ -- Core package source (includes catalog/ directory)
  • shared-ui/ -- UI package source
  • docs/CI-CD-Workflows.md -- Full publishing and consumption details
  • Smackz-Websites/scripts/install-qa-packages.js -- QA package override script