Devian v10 — Workspace Management

Manage the Devian TypeScript monorepo with strict single workspace root policy and standardized npm workflows.

What This Skill Does

This skill enforces Devian v10's monorepo architecture where `framework-ts/` is the single source of truth for dependency management. You'll work with workspace scripts, prevent common multi-lockfile errors, and maintain consistent build/dev workflows across modules, apps, and tools.

Workspace Structure

```

framework-ts/

├── package.json # Workspace root (ONLY valid package.json)

├── package-lock.json # Single lockfile

├── node_modules/ # Single dependency tree

├── tsconfig.json # Shared TypeScript config

├── module/

│ └── devian/ # Core framework (@devian/core)

├── apps/

│ ├── game-client/ # Client application

│ └── game-server/ # Server application

└── tools/

├── builder/ # Build toolchain

└── archive/ # Project archival

```

Step-by-Step Instructions

1. Dependency Management

**CRITICAL RULE:** All `npm install` commands MUST run from `framework-ts/` root.

```bash

✅ CORRECT

cd framework-ts

npm install lodash

❌ WRONG - Never run in subfolders

cd framework-ts/apps/game-client

npm install lodash # This violates single workspace policy

```

**Adding workspace-specific dependencies:**

```bash

cd framework-ts

npm install lodash -w game-client

```

2. Running Workspace Scripts

The root `package.json` defines shortcut scripts for common tasks:

```bash

Build with builder tool

npm run builder -- ../input/input_common.json

Archive project

npm run archive -- <args>

Start client dev server

npm run dev:client

Start game server

npm run start:server

```

**Direct workspace execution (alternative):**

```bash

npm -w builder run build -- ../input/input_common.json

npm -w game-client run dev

```

3. TypeScript Path Mapping

The root `tsconfig.json` provides `@devian/core` alias:

```typescript

// Any workspace can import core framework

import { DevianCore } from '@devian/core';

```

**Configuration reference:**

```json

{

"compilerOptions": {

"target": "ES2020",

"module": "ESNext",

"moduleResolution": "node",

"baseUrl": ".",

"paths": {

"@devian/core": ["./module/devian/src"]

}

}

}

```

4. CI/CD Workflow

Always use `npm ci` in automated environments for reproducible builds:

```bash

cd framework-ts

npm ci

```

5. Recovery from Lockfile Corruption

If `package-lock.json` becomes inconsistent:

```bash

cd framework-ts

rm -rf node_modules package-lock.json

npm install

```

**When to use recovery:**

6. Adding New Workspace Packages

1. Create folder in `module/`, `apps/`, or `tools/`

2. Add `package.json` with unique name

3. Update root `workspaces` array (if pattern doesn't match)

4. Run `npm install` from root to link workspace

**Example `module/new-module/package.json`:**

```json

{

"name": "@devian/new-module",

"version": "1.0.0",

"type": "module",

"main": "./src/index.ts"

}

```

7. Common Script Patterns

**Running tests across workspaces:**

```bash

npm run test --workspaces

```

**Building specific workspace:**

```bash

npm run build -w builder

```

**Listing all workspaces:**

```bash

npm query .workspace | jq -r '.[].name'

```

Constraints

1. **Single lockfile policy:** Only `framework-ts/package-lock.json` is valid

2. **No nested node_modules:** Subfolders must not contain their own `node_modules/`

3. **Workspace scripts only:** Use root scripts or `-w` flag, never `cd` into subfolders for npm commands

4. **ES modules:** All packages use `"type": "module"` (no CommonJS)

5. **TypeScript target:** ES2020 baseline for all workspaces

Troubleshooting

**Error: "Cannot find module '@devian/core'"**

**Error: "Multiple package-lock.json files"**

**Error: "ENOWORKSPACES"**

Related Skills