Skip to content
Back to skills

Frontend Workspaces

ASecurity

Opt-in pnpm-workspaces layout for sharing TypeScript code across multiple frontends (web + mobile). When to use it, the resulting layout, how to add new shared packages, and the dev loop.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
developmenttypescriptgobashreactnextjsapifrontend

Works with

  • cli
  • api

Security analysis

A92/100
  • mediumInstalls packages at runtime which could introduce malicious dependencies
  • mediumInstalls packages at runtime which could introduce malicious dependencies

Pro shows the line behind each finding and how to fix it

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill frontend-workspaces --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Frontend Workspaces?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Frontend Workspaces
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-frontend-workspaces/badge)](https://www.skillsdirectory.com/skills/reliant-labs-frontend-workspaces)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: frontend-workspaces
description: Opt-in pnpm-workspaces layout for sharing TypeScript code across multiple frontends (web + mobile). When to use it, the resulting layout, how to add new shared packages, and the dev loop.
---

# Frontend Workspaces

## When to use this

The default forge layout gives each frontend its own standalone
`package.json` under `frontends/<name>/`. That works fine for a single
frontend — but the moment you add a second one (e.g. a Next.js web app
plus a React Native Expo app), each frontend ends up with:

- Its own copy of the buf-generated Connect TS clients (`src/gen/`).
- Its own copy of the React Query hook wrappers.
- No clean way to share custom hooks, design tokens, or domain types.

The pnpm-workspaces layout reshapes the project into a pnpm workspace
so all frontends can share these pieces from one source of truth.

Reach for it when:

- You have **two or more frontends** (web + mobile is the canonical
  case).
- You want **one place** for the generated TS clients, hooks, or
  cross-frontend utilities.
- You're OK adopting **pnpm** as the package manager (pnpm is required
  — it's the only manager that handles `workspace:*` resolution
  cleanly).

If you only have one frontend, leave the layout off. The default layout
is simpler.

## Turning it on

Pass `--frontend-workspaces` to `forge project new`. That writes
`pnpm-workspace.yaml` at the project root, and **that file is the switch**:
forge detects the layout from it, so there is no `frontend:` block in
`forge.yaml` to set. To adopt the layout in an existing project, add the root
`pnpm-workspace.yaml` (`packages: ["packages/*", "frontends/*"]`); the next
`forge generate` emits `packages/api` and `packages/hooks` without disturbing
your existing frontend's code. Delete the file to go back to the per-frontend
layout.

## Resulting layout

```
<project root>/
  pnpm-workspace.yaml          # lists packages/* + frontends/*
  packages/
    api/                       # @<project>/api
      package.json
      buf.gen.yaml             # buf emits TS stubs here
      src/
        index.ts               # re-export barrel
        gen/                   # buf-generated *_pb.ts (committed, like all generated code)
    hooks/                     # @<project>/hooks
      package.json
      src/
        transport.ts           # setApiTransport() bootstrap
        use-api-query.ts       # base wrappers (DOM-free)
        use-api-mutation.ts
        index.ts
        generated/             # per-service hooks (forge-generated)
          users-hooks.ts
          orders-hooks.ts
          index.ts
    ui-web/                    # @<project>/ui-web — shared web components
      package.json
      src/
        components/
          ui/                  # React/Tailwind component library
            button.tsx
            card.tsx
            ...
        index.ts               # re-export barrel
  frontends/
    web/                       # Next.js
      package.json             # declares "@<project>/api": "workspace:*"
                               # plus "@<project>/ui-web": "workspace:*"
      tsconfig.json            # paths: "@/components/ui/*" → ui-web
      src/
        lib/connect.ts         # builds Transport, calls setApiTransport()
        ...
    mobile/                    # Expo / React Native
      package.json             # api+hooks deps; NOT ui-web (web-only)
      ...
```

The npm scope is derived from your project name (`forge.yaml: name`).
`name: my-app` produces `@my-app/api` and `@my-app/hooks`. The scope is
lowercased and stripped to valid npm chars; falls back to `@app` if the
name doesn't produce a valid segment.

## Dev loop

After flipping the flag and running `forge generate`:

```bash
# install + link all workspace members in one shot
pnpm install

# run a frontend
pnpm --filter web dev      # Next.js
pnpm --filter mobile start # Expo

# type-check everything (each workspace + each frontend)
pnpm -r typecheck
```

## How the pieces fit together

The `@<project>/hooks` package is **DOM-free** — its `tsconfig.json`
omits the `DOM` lib so accidentally reaching for `document` or
`window` is a compile error. This is what makes the same hooks usable
from Next.js and React Native.

Because the hooks package can't construct its own fetch-based
Transport (that's frontend-specific), it exposes a tiny `transport.ts`
shim:

```typescript
// packages/hooks/src/transport.ts
import { createClient, type Transport } from "@connectrpc/connect";

let _transport: Transport | null = null;

export function setApiTransport(t: Transport) { _transport = t; }
export function connectClient<S>(service: S) {
  return createClient(service, _transport ?? throwIfNull());
}
```

Each frontend builds its Transport (browser fetch in Next.js, custom
fetch in React Native) once at startup and hands it over:

```typescript
// frontends/web/src/lib/connect.ts (auto-generated)
import { setApiTransport } from "@my-app/hooks";

export const transport = buildTransport();
setApiTransport(transport);
```

After that, every hook in `@my-app/hooks/generated` resolves its
Connect client against whichever Transport is registered. The hook
files themselves don't import from frontend-specific paths, so they
work identically in every workspace member.

## The `ui-web` package

`packages/ui-web/` holds the shared React + Tailwind component library
that browser-targeted frontends (Next.js, Vite SPA) import from. In the
non-workspaces layout the same components get copied into EVERY
`frontends/<name>/src/components/ui/` directory. With workspaces on
they live ONCE under `packages/ui-web/src/components/ui/`, and per-
frontend tsconfig path mapping redirects the existing
`@/components/ui/*` imports to the shared package.

The mapping is scoped to `/ui/` deliberately — non-ui local paths
like the owned `@/components/nav.tsx` and `@/components/session_nav.tsx`
keep resolving against the per-frontend `src/` tree, so the components
each frontend owns keep working unchanged.

### Ownership rule

forge writes `packages/ui-web/` files **once**, on first scaffold.
After that re-running `forge generate` is a no-op for every file under
the package — the user owns them. Edit, restyle, delete, rename
freely; nothing here will be clobbered.

`src/index.ts` (the re-export barrel) is seeded once from the
components directory and then owned by you too. Add or remove
`export { default as ... }` lines as you grow the library — forge
won't fight you.

### How frontends import from it

Templates keep their existing `@/components/ui/...` import sites
unchanged — no rewrite required when flipping workspaces on. The
redirection happens at the tsconfig + bundler level:

```jsonc
// frontends/web/tsconfig.json (workspaces mode)
"paths": {
  "@/components/ui/*": ["../../packages/ui-web/src/components/ui/*"],
  "@/*": ["./src/*"]
}
```

For Vite frontends the same alias is mirrored in `vite.config.ts` so
the bundler resolves to the same paths the type-checker sees.

Next.js reads `tsconfig.json` paths directly through its webpack
config — no extra wiring needed.

### Adding a new component

```bash
# 1. write the component file:
$EDITOR packages/ui-web/src/components/ui/my_widget.tsx

# 2. expose it from the barrel:
$EDITOR packages/ui-web/src/index.ts
#   add: export { default as MyWidget } from "./components/ui/my_widget";
```

Then in a frontend:

```typescript
import MyWidget from "@/components/ui/my_widget";    // path-mapped, default
// or
import { MyWidget } from "@<scope>/ui-web";          // named barrel export
```

### React Native does NOT consume `ui-web`

`packages/ui-web/` is web-targeted (DOM lib enabled, Tailwind
utility classes). React Native frontends use platform-specific
primitives and don't depend on the package. The forge generator
skips the workspace dep when scaffolding RN frontends.

### Why this isn't on npm

`packages/ui-web/` is project-specific scaffolding, not a shared
library. forge seeds a starting set (button, card, data table, etc.)
and gets out of the way — components are yours to fork, restyle, or
rewrite to match your product. Publishing to npm would defeat the
point of giving every project its own forkable design system.

## Adding a new shared package

You can add your own shared packages alongside the forge-generated
`packages/api/`, `packages/hooks/`, and `packages/ui-web/`. Common
examples:

- `packages/types/` — shared TypeScript types not derived from protos.
- `packages/utils/` — shared helpers.
- `packages/ui-mobile/` — if you want a React Native primitives layer
  paralleling `ui-web`.

```bash
mkdir packages/ui
cd packages/ui
pnpm init
# edit package.json:
#   "name": "@my-app/ui"
#   "main": "./src/index.ts"
```

Then in a frontend:

```bash
cd frontends/web
pnpm add @my-app/ui   # resolves to workspace:*
```

Forge will never touch your own packages — only `packages/api/` and
`packages/hooks/` are managed.

## What forge owns vs you

| Path | Owner | Regenerated by `forge generate`? |
| ---- | ----- | -------------------------------- |
| `pnpm-workspace.yaml` | forge (initial), you (after) | only if missing |
| `packages/api/package.json` | forge (initial), you (after) | only if missing |
| `packages/api/src/index.ts` | you | only if missing |
| `packages/api/src/gen/` | forge | every run (buf) |
| `packages/hooks/package.json` | forge (initial), you (after) | only if missing |
| `packages/hooks/src/use-api-*.ts` | forge (initial), you (after) | only if missing |
| `packages/hooks/src/generated/` | forge | every run |
| `packages/ui-web/package.json` | forge (initial), you (after) | only if missing |
| `packages/ui-web/tsconfig.json` | forge (initial), you (after) | only if missing |
| `packages/ui-web/src/components/ui/*.tsx` | forge (initial), you (after) | only if missing |
| `packages/ui-web/src/index.ts` | forge (initial), you (after) | only if missing |
| `frontends/<name>/src/lib/connect.ts` | forge (initial), you (after) | only if missing |

Rule of thumb: the `src/gen/` and `src/generated/` directories are
regenerated every cycle. Everything else is yours to edit once it
lands.

## Why pnpm only

- `workspace:*` is a pnpm-specific protocol. npm and yarn classic use
  different conventions that don't compose with React Native's Metro
  bundler.
- pnpm's content-addressable store means N frontends sharing N copies
  of `react-native` cost the disk space of one copy.
- forge doesn't generate a `package-lock.json` or `yarn.lock`; only
  `pnpm-lock.yaml` is supported in workspace mode.

## See also

- `frontend` skill — single-frontend dev loop, component library,
  React Query patterns.
- `proto` skill — what changes in `proto/services/<svc>/v1/` flow
  through buf into `packages/api/src/gen/`.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.