DevHive-Cli pnpm-workspace

Understand and build on the pnpm monorepo template. Use when working on workspace structure, TypeScript project references, dependency management, artifact routing, shared libraries, or cross-package changes.

install

source · Clone the upstream repo

git clone https://github.com/El3tar-cmd/DevHive-Cli

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/El3tar-cmd/DevHive-Cli "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/pnpm-workspace" ~/.claude/skills/el3tar-cmd-devhive-cli-pnpm-workspace && rm -rf "$T"

manifest: skills/pnpm-workspace/SKILL.md

source content

pnpm workspace skill

Structure

artifacts-monorepo/
├── artifacts/              # Deployable applications
├── lib/                    # Shared libraries
├── scripts/                # Utility scripts (single workspace package)
├── pnpm-workspace.yaml     # Workspace package discovery, catalog pins, overrides
├── tsconfig.base.json      # Shared strict TS defaults for packages that can extend it
├── tsconfig.json           # Root TS solution config for composite libs only
└── package.json            # Root task orchestration and shared dev tooling

TypeScript

Default model:

```
lib/*
```
packages are composite and emit declarations via
```
tsc --build
```
.
```
artifacts/*
```
and
```
scripts
```
are leaf workspace packages checked with
```
tsc --noEmit
```
. They should never import from each other, if you need to share functionality (encouraged) you must create a new lib.
Root
```
tsconfig.json
```
is a solution file for libs only, used by
```
tsc --build
```
.
```
tsconfig.base.json
```
contains shared strict defaults. Not all packages extend it (e.g. Expo apps will use its own base).

Root commands:

```
pnpm run typecheck:libs
```
runs
```
tsc --build
```
for the composite libs.
```
pnpm run typecheck
```
is the canonical full check: builds libs first, then runs leaf workspace package typechecks.
Prefer the root
```
typecheck
```
result over editor/LSP state when they disagree.

Adding a new lib:

Add

composite

declarationMap

, and

emitDeclarationOnly

to its

tsconfig.json

Add it to the root
```
tsconfig.json
```
```
references
```
array.
If it imports another lib, add that lib to its own
```
references
```
.

Adding a new artifact:

Should be usually handled via the
```
artifacts
```
skill unless no artifact template satisfies the user's requirements.
Do not add it to the root
```
tsconfig.json
```
references.

Project references:

When one lib imports another lib, the importing lib must declare it in
```
references
```
so
```
tsc --build
```
can order and rebuild correctly.
Root
```
tsconfig.json
```
should list the lib packages, not every workspace package.
Artifact
```
references
```
to libs are optional but useful for:
- explicit documentation of direct workspace dependencies
- better editor/tsserver project awareness
- standalone
```
tsc -b artifacts/<name>
```
  style workflows

Server & API contracts

For backend-backed apps, define the contract in OpenAPI first, then generate helpers from it.

Codegen command:

pnpm --filter @workspace/api-spec run codegen

This generates files such as React Query hooks and Zod schemas. It is strongly recommended that you use them. The server should use Zod schemas to validate inputs and outputs, and clients should use the available hooks.

Logging

Never use

console.log

in server code. Use

req.log

in route handlers and the singleton

logger

for non-request code. See

references/server.md

for setup and examples.

References

```
references/openapi.md
```
— Setting up OpenAPI spec and code generation in this contract-first repo.
```
references/server.md
```
— Important information about adding routes and general tips.
```
references/db.md
```
— Adding new database schemas and running migrations.

scripts

(

@workspace/scripts

)

Put shared utility scripts in

./scripts

Each script lives in
```
scripts/src/
```
Add a matching npm script in
```
scripts/package.json
```
```
scripts
```
is treated like a leaf workspace package and typechecked with
```
tsc --noEmit
```

Proxy & service routing

A global reverse proxy routes traffic by path using each artifact's

.replit-artifact/artifact.toml

Example:

[[services]]
localPort = 8080
name = "API Server"
paths = ["/api"]

Rules for accessing services:

For ad hoc requests, such as
```
curl
```
, always go through the shared proxy at
```
localhost:80
```
. Never call service ports directly.
- Correct:
```
localhost:80/api/healthz
```
- Wrong:
```
localhost:8080/api/healthz
```
Paths are not rewritten. Services must handle their full base path themselves.
The only exception is the EXPO artifact. If one exists, use $REPLIT_EXPO_DEV_DOMAIN to access it locally.
In application code, prefer relative URLs when possible. For user-facing access, both development previews and published production domains already route through the shared proxy automatically. Published apps are exposed over HTTPS on the domains listed in
```
$REPLIT_DOMAINS
```
(comma-separated).
Do NOT add Vite proxy configs or custom base URLs to reach other services; the shared proxy already handles cross-service routing.
Routes across artifacts are matched most-specific-first, so a service on
```
/api
```
won't conflict with one on
```
/
```
.

Package management

Workspace package rules:

Workspace package names should use the
```
@workspace/
```
prefix.
Each package must declare its own dependencies; dependencies are not shared implicitly across workspace packages.
Root dependencies are for repo-level tooling such as
```
typescript
```
,
```
prettier
```
,
```
eslint
```
,
```
vitest
```
, etc.
Do not use
```
pnpm add --no-frozen-lockfile
```
.
```
pnpm add
```
will automatically use
```
catalog:
```
if the dependency already has a catalog entry.

devDependencies vs dependencies

Static/client-only artifacts (Vite-built React apps): all packages →
```
devDependencies
```
.
Server artifacts: runtime imports (
```
express
```
,
```
drizzle-orm
```
,
```
pg
```
) →
```
dependencies
```
; build tools,
```
@types/*
```
→
```
devDependencies
```
.
If a dependency already exists in the
```
pnpm-workspace.yaml
```
catalog, use
```
"catalog:"
```
.
Libraries should declare shared runtimes (
```
react
```
,
```
react-dom
```
) as
```
peerDependencies
```
.

Codegen Outputs

See

references/openapi.md

for generated file paths and naming conventions. Do not change the OpenAPI

info.title

— it controls generated filenames.

Common pitfalls

Do not introduce an all-composite setup for leaf workspace packages. Declaration emit from apps causes type portability issues (TS2742) when multiple versions of
```
@types/*
```
packages exist across workspace packages.
Do not add leaf workspace packages to the root
```
tsconfig.json
```
references; that solution file is for buildable libs only.
Prefer root commands with
```
--filter
```
when targeting a specific package:
- ```
pnpm --filter @workspace/api-server run build
```
If the editor and CLI disagree on cross-package types, trust
```
pnpm run typecheck
```
.
If you change Orval output paths or the barrel exports, generated imports may break.

Artifact Lifecycle

If you are creating or updating an artifact, follow the

artifacts

skill for the artifact callback lifecycle (

createArtifact

verifyAndReplaceArtifactToml

presentArtifact