Source: https://www.hype-stack.dev/docs/development/monorepo

# Monorepo

Hype Stack uses **pnpm workspaces** for package management and **Nx** for task orchestration. This gives you fast
installs, shared dependencies, and intelligent build caching.

## Workspace structure

Defined in `pnpm-workspace.yaml`:

```yaml
packages:
  - "apps/*"
  - "packages/*"
  - "shared/*"
  - "libs/*"

publicHoistPattern:
  - "*"
```

Each app and package has its own `package.json` with a scoped name. The template uses `@hype-stack/*`; `create` renames
the scope to your project name, so in your repo it reads `@my-app/backend`, `@my-app/frontend`, and so on. These docs
keep the template's names.

The hoist pattern matters. pnpm 12 reads hoisting settings only from this file, and Vite's dependency optimizer plus
Electron Forge both need the root `node_modules` to hold what they import. Leave it in place.

## Nx task orchestration

Nx knows the dependency graph between your apps and packages. When you run `pnpm build`, it builds dependencies first,
then dependents. Most targets are inferred from each app's `package.json` scripts by the Nx Vite and TypeScript plugins;
the backend declares its `serve` target explicitly under the `nx` key of its `package.json`.

The `nx.json` file configures:

- **Task pipelines** - which tasks depend on which other tasks
- **Cache inputs** - which files affect cache validity
- **Target defaults** - shared config for build, lint, typecheck targets

## Adding a package

1. Create a new folder in `packages/`:

   ```bash
   mkdir packages/my-lib
   cd packages/my-lib
   pnpm init
   ```

2. Set the package name in `package.json`:

   ```json
   {
     "name": "@hype-stack/my-lib"
   }
   ```

3. Import it from any app:
   ```bash
   pnpm --filter @hype-stack/backend add @hype-stack/my-lib
   ```

Nx picks up the new package automatically.

## Why not just one big app?

The monorepo split pays off when:

- Backend and frontend can be deployed independently
- Shared types live in `packages/` and are imported by both sides
- Nx caches builds, so unchanged apps don't rebuild
- Teams can own specific apps without stepping on each other