Skip to content

Installation

This guide walks you through setting up the CyberEco Hub monorepo for local development.

Prerequisites

Before you begin, make sure you have the following installed:

Tool Version Check
Node.js >= 18 node --version
npm >= 10 npm --version
Git Latest git --version

Node.js version management

We recommend using nvm or fnm to manage Node.js versions. The project requires Node.js 18 or later, and CI tests against Node.js 18 and 20.

Clone the Repository

git clone https://github.com/cyber-eco/cybereco-hub.git
cd cybereco-hub

Install Dependencies

npm ci

This installs all workspace dependencies for the 4 npm packages and the Hub app in a single command. The ci flag ensures a clean, reproducible install from package-lock.json.

Monorepo workspaces

CyberEco Hub uses npm workspaces to manage multiple packages in a single repository. The workspace configuration in the root package.json includes packages/* and apps/*.

Environment Setup

The Hub app requires Firebase configuration. Copy the example environment file and fill in your values:

cp apps/hub/.env.example apps/hub/.env

Then edit apps/hub/.env with your Firebase project credentials:

apps/hub/.env
# Public (exposed to client via import.meta.env.PUBLIC_*)
PUBLIC_HUB_URL=http://localhost:4321
PUBLIC_FIREBASE_API_KEY=your-api-key
PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
PUBLIC_FIREBASE_PROJECT_ID=your-project-id
PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
PUBLIC_FIREBASE_APP_ID=1:123456789:web:abc123

# Server-only (NOT exposed to client)
JWT_SECRET=a-strong-random-secret-at-least-32-characters

Environment variable prefixes

Variables prefixed with PUBLIC_ are exposed to client-side code via Astro's import.meta.env.PUBLIC_*. The JWT_SECRET is server-only and must never be exposed to the browser.

Variable Reference

Variable Required Description
PUBLIC_HUB_URL Yes Base URL of the Hub app (e.g., http://localhost:4321 for dev)
PUBLIC_FIREBASE_API_KEY Yes Firebase Web API key from the Firebase Console
PUBLIC_FIREBASE_AUTH_DOMAIN Yes Firebase Auth domain (e.g., your-project.firebaseapp.com)
PUBLIC_FIREBASE_PROJECT_ID Yes Firebase project ID
PUBLIC_FIREBASE_STORAGE_BUCKET Yes Firebase Storage bucket (e.g., your-project.appspot.com)
PUBLIC_FIREBASE_MESSAGING_SENDER_ID Yes Firebase Cloud Messaging sender ID
PUBLIC_FIREBASE_APP_ID Yes Firebase app ID
JWT_SECRET Yes Secret key for signing JWTs (server-side auth tokens)

Getting Firebase credentials

  1. Go to the Firebase Console
  2. Create or select a project
  3. Go to Project Settings > General
  4. Under Your apps, click the web icon (</>) to add a web app
  5. Copy the config values from the generated firebaseConfig object

Build

Build all 5 packages (4 npm packages + Hub app) in topological order:

npm run build

Turborepo orchestrates the build, ensuring packages are built in dependency order:

@cyber-eco/types          (built first - zero deps)
       |
       +------------------+
       |                  |
       v                  v
@cyber-eco/firebase   @cyber-eco/auth     (built in parallel)
       |                  |
       +------------------+
       |
       v
@cyber-eco/services       (built after firebase + auth)
       |
       v
  apps/hub               (built last)

Build tools

  • Packages: Built with tsup producing dual ESM/CJS output
  • Hub app: Built with Astro + Vite
  • Orchestration: Turborepo with turbo.json configuration

Development

Start the Hub dev server (builds dependencies first):

npm run dev

The development server starts at http://localhost:4321 with hot module replacement (HMR) enabled.

Testing

Run all tests across the monorepo:

npm run test

Tests use Vitest and require no Firebase emulators -- all domain service tests use the MockStorageAdapter from @cyber-eco/services/testing.

Type Checking

Run TypeScript strict mode checking across all packages:

npm run type-check

Additional Commands

Command Description
npm run lint Run ESLint across all packages
npm run clean Remove all build artifacts and node_modules
npm run changeset Create a new changeset for versioning
npm run version-packages Apply changesets to bump package versions
npm run publish-packages Build and publish packages via Changesets

Next Steps