Vibe Platform

Appearance

/Platform/Web ​

This folder is the root of the frontend and Node-based workspace for the Vibe platform.

It is intentionally a single npm workspace root that coordinates many packages, apps, and servers from one place.

If npm is angry with you, it’s usually because you are not running commands from this folder.

What lives here ​

This workspace contains multiple categories of projects:

  • packages/*
    Core shared libraries (TypeScript, Vue, domain logic, UI, etc.)

  • packages/.generated/*
    Generated API clients (do not edit by hand)

  • web/*
    Browser applications (admin, controller, website)

  • servers/*
    Node-based backend or local tooling servers

  • identity/*
    Authentication / identity-related web apps

All of these are wired together using npm workspaces.

Tooling versions (important) ​

This repo is pinned to known-good versions.

  • Node.js: 20.19.4
    (managed via Volta)

  • npm: comes with Node 20.x (npm 10+)

  • TypeScript: ^5.9.2

If things behave strangely, check versions first.

bash
node --version
npm --version

npm workspaces (how this actually works) ​

This folder contains the only workspace root.

json
{
  "name": "vibe-labs",
  "private": true,
  "workspaces": [
    "packages/*",
    "packages/.generated/*",
    "servers/*",
    "identity/*",
    "web/*"
  ]
}

Key rules:

  • All installs must be run from this folder
  • Individual packages use local workspace links
  • Internal dependencies are resolved via workspaces, not the registry
  • Running npm install inside a sub-package is not supported

If you run npm commands in the wrong directory, npm will punish you.

Installation (the correct way) ​

Install everything:

bash
npm install

This is equivalent to:

bash
npm install --workspaces --workspace-root

The install script exists to make this explicit and repeatable.

Building everything ​

Build all packages and apps in dependency order:

bash
npm run build

Internally this runs:

bash
npm run build --workspaces --if-present

Notes:

  • Libraries build first
  • Apps build after their dependencies
  • Some apps may expect environment variables (warnings are normal)
  • Known build failures in specific apps do not invalidate the workspace setup

Running dev servers ​

To start all available dev servers:

bash
npm run dev

Only packages that define a dev script will run.

Cleaning the workspace ​

Remove all build output and node_modules:

bash
npm run clean

This is useful if npm gets into a strange state or after dependency refactors.

Versioning strategy ​

  • A single VERSION.txt exists at repo root
  • All npm packages share the same version
  • Versions are updated via scripts, not manually
  • Workspace dependencies use compatible local versions

This keeps releases predictable and atomic.

Common mistakes (avoid these) ​

  • Running npm install inside a package folder
  • Deleting node_modules while a process is still running
  • Editing files under packages/.generated
  • Mixing Node versions outside Volta
  • Panicking when npm logs look scary

npm always looks scary. This is normal.

If things go wrong ​

The nuclear reset:

bash
npm run clean
npm install
npm run build

If that fails, the problem is real.

Final sanity check ​

If this works:

bash
npm install
npm run build

Then the workspace is healthy.