Adding a new workspace

GlassKit ships four workspaces: app/, companion/, packages/glasses-ui/, packages/backend/. Eventually you'll want to add a fifth: a mobile app, an admin panel, a shared component library, an internal CLI. This doc walks the conventions so the new workspace plays nicely with everything already wired.

The two kinds of workspace

GlassKit's structure treats them differently:

Pick by intent:

Both kinds are pnpm workspaces; the only difference is discoverability + the convention of "what people expect to find where."

The contract every workspace satisfies

To play with turbo + pnpm + the existing tooling, your new workspace needs:

"dependencies": {
  "@glasskit/glasses-ui": "workspace:*",
  "@glasskit/backend": "workspace:*"
}

The workspace globs in pnpm-workspace.yaml already cover both locations:

packages:
  - app
  - companion
  - packages/*

Add a directory at the right location and pnpm picks it up on the next pnpm install.

Walkthrough: adding an admin web app

Concrete example. You want an internal admin panel: Next.js, deploys to a separate Vercel project, reads the same Convex backend.

mkdir admin
cd admin

{
  "name": "@glasskit/admin",
  "version": "0.1.0",
  "private": true,
  "description": "Internal admin panel — user / billing / feature-flag tools.",
  "scripts": {
    "dev": "next dev --port 3001",
    "build": "next build",
    "start": "next start --port 3001",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@clerk/nextjs": "^7.0.0",
    "@glasskit/backend": "workspace:*",
    "convex": "^1.39.0",
    "next": "16.2.6",
    "react": "19.2.4",
    "react-dom": "19.2.4"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "@types/react": "^19.2.0",
    "@types/react-dom": "^19.2.0",
    "typescript": "^5.7.3"
  }
}

pnpm --filter @glasskit/admin dev   # runs admin only
pnpm dev                             # runs everything (admin included)
pnpm --filter @glasskit/admin build  # builds admin only

"use client";
import { ClerkProvider } from "@clerk/nextjs";
import { ConvexProviderWithClerk } from "convex/react-clerk";
import { ConvexReactClient } from "convex/react";
import { useAuth } from "@clerk/nextjs";

const convex = new ConvexReactClient(env.NEXT_PUBLIC_CONVEX_URL);

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <ClerkProvider>
      <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
        {children}
      </ConvexProviderWithClerk>
    </ClerkProvider>
  );
}

Walkthrough: adding a shared package

Concrete example. You realize both app/ and companion/ need the same date-formatting helpers. Extract into packages/format/.

mkdir -p packages/format/src
cd packages/format

{
  "name": "@glasskit/format",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  },
  "devDependencies": {
    "typescript": "^5.7.3",
    "vitest": "catalog:"
  }
}

// app/package.json
"dependencies": {
  "@glasskit/format": "workspace:*"
}

// companion/package.json
"dependencies": {
  "@glasskit/format": "workspace:*"
}

// anywhere in app/ or companion/
import { formatDate } from "@glasskit/format";

How turbo handles your new workspace

Two things to know:

Task discovery is automatic

Turbo reads pnpm-workspace.yaml + each workspace's package.json scripts. If your new workspace declares a build script, pnpm turbo run build includes it. Same for typecheck, lint, test, dev. No turbo.json changes needed.

Dependency-aware ordering

turbo.json declares "dependsOn": ["^build"] for the build task. This means turbo builds shared packages (packages/*) BEFORE the surfaces that depend on them. If your new shared package needs to be built before consumers, declare its own build script and the dependency chain takes care of the rest.

For workspaces that have no real build step (TypeScript-only shared packages), omit the build script. Turbo will still typecheck them in dependency order via the typecheck task.

Workspace dependencies + pnpm catalog

pnpm-workspace.yaml has a catalog: section that pins versions shared across workspaces:

catalog:
  vitest: ^3.0.0
  zod: ^3.24.0
  "@t3-oss/env-core": ^0.13.0
  "@t3-oss/env-nextjs": ^0.13.0

Workspaces reference these as "<pkg>": "catalog:":

{
  "devDependencies": {
    "vitest": "catalog:"
  }
}

What NOT to add as a workspace

A complete checklist for a new surface

• Directory at the right location (repo root for surfaces, packages/ for libraries)
• package.json with @glasskit/<name> name, private: true, scripts matching turbo's task pipeline
• tsconfig.json extending a sibling's config
• env.ts if the surface needs env vars
• .env.example documenting those vars
• Bootstrap-import the env file from your config (next.config.ts, vite.config.ts, etc.)
• If deploying to Vercel, add a "Deploy to Vercel" button to the boilerplate README
• If sharing code, add workspace:* deps in the consumers' package.jsons and run pnpm install from the root
• If using shared deps already in the catalog (vitest, zod, @t3-oss/env-*), reference as "<pkg>": "catalog:" instead of pinning a version