handoff-app 2.0.0 → 2.0.1

package/AGENTS.md

@@ -1,7 +1,96 @@
-# Instructions
+# AGENTS.md
+
+## Local instructions
 
 Before starting work, check whether `AGENTS.local.md` exists in the repository root.
 
 If it exists, read and follow its instructions in addition to this file. Treat `AGENTS.local.md` as developer-specific local guidance.
 
 If it does not exist, proceed normally.
+
+## Project
+
+`handoff-app` is an npm package (CLI + library) that turns design tokens (fetched from Figma), components, patterns, and Markdown pages into a Next.js documentation app and distributable artifacts. User-facing docs: [README.md](README.md), [RECIPES.md](RECIPES.md), [docs/cli.md](docs/cli.md), [docs/api.md](docs/api.md), [UPGRADE.md](UPGRADE.md).
+
+Requires Node.js >= 22 and npm >= 10.
+
+## Commands
+
+```bash
+npm run build     # tsc: compiles src/ (except src/app) to dist/
+npm run lint      # next lint over src/app
+npm test          # alias for lint; there is no unit test suite
+npx tsc -p src/app/tsconfig.json --noEmit   # typecheck the Next.js app (root tsc excludes src/app);
+                                            # errors under a stale src/app/.next/types are not real
+npx drizzle-kit generate                    # generate a registry migration after editing src/registry/db/schema.ts
+```
+
+The CLI (`dist/cli.js`, bin `handoff-app`) always runs against a **working directory**: the directory that holds `handoff.config.ts` (or `HANDOFF_WORKING_PATH`). This repo is not a Handoff project, so to exercise a change, build here and run the CLI from a consumer project that uses this build (`start`, `dev`, `build`, `fetch`, `publish`, `checkout`, ...). Verify behavior there; `npm run lint` and the two `tsc` runs are the only checks in this repo.
+
+Formatting: Prettier (config in `package.json`: 140 cols, single quotes, `es5` trailing commas, Tailwind class sorting) and `.editorconfig` (2 spaces, LF).
+
+## Architecture
+
+### Runtime modes
+
+- **Workspace** (default): local files are the source of truth; no database. It is the **only** place that builds content.
+- **Registry**: a deployed catalog backed by PostgreSQL (Drizzle). It serves only what a workspace publishes. It never builds and never reads workspace source.
+- A **connected workspace** publishes to / checks out from a registry; it is not a third mode.
+
+`runtime.mode` selects the mode; `build --target registry` sets registry mode in the generated app. Keep registry-only dependencies (Drizzle/Postgres) out of the workspace and static paths — e.g. `src/store/index.ts` deliberately does not re-export the registry store; registry consumers import `@handoff/store/registry` lazily.
+
+### Two TypeScript programs
+
+- **`src/` (minus `src/app`)** — the Node CLI/library, CommonJS, compiled by root `tsconfig.json` to `dist/`. `src/index.ts` holds the `Handoff` class (`fetch`, `build`, `publish`, `checkout`, `start`, `dev`); `src/cli.ts` registers the yargs commands in `src/commands/`.
+- **`src/app/`** — the Next.js (pages router) documentation app. It is not compiled by `tsc`; at build/start time `src/app-builder` stages it into `.handoff/<projectId>/` under the package and runs `next build` / `next dev`. It imports the core via the `@handoff/*` alias (→ `src/*`). It also hosts the APIs: docs API, registry API, MCP endpoint (`/api/mcp`), auth, and the AI assistant (`src/app/lib/*`, `src/app/pages/api/*`).
+
+### Main flows
+
+- **fetch**: `src/pipeline` — Figma auth → extract → fonts → token transformers; output goes to the working directory's `exported/`.
+- **build/start**: `src/config` loads `handoff.config.*` + profile sidecar + env, then `initRuntimeConfig()` normalizes catalog declarations (`src/catalog`) into component/pattern records; `src/transformers` builds previews with Vite/esbuild per renderer (React, Handlebars, CSF); `src/cache` skips unchanged components (`.handoff/.cache/build-cache.json`, bypass with `--force`); `src/app-builder` builds the app (static → `out/static`, registry → `out/registry`, `--package vercel` → `.vercel/output`). Watch mode uses chokidar + a WebSocket reload server with diff-aware rebuilds.
+- **publish/checkout**: `src/registry` (`publish/`, `checkout/`, `transfer.ts`, `tokens/`, `assets/`, `auth/`) against the registry API in `src/app/lib/registry-api`. Storage is abstracted by `src/store` (filesystem vs. registry implementations of the same interfaces). Asset blobs go through a pluggable storage provider; email and AI providers are also pluggable custom server modules (`handoff-app/providers`).
+- **Migrations**: SQL in `drizzle/` ships with the package and is applied by `handoff-app db:migrate`.
+
+### Config and server-module rules
+
+- **Baked vs. request-time values.** For a `fromEnv('NAME')` value, the build keeps only the variable name, and a deployed registry reads the value at request time. Secrets must use `fromEnv()`. These settings change the shape of the build and are baked, so a change needs a rebuild: `runtime.mode`, `runtime.mcp`, `runtime.ai.enabled`, the database driver, the asset storage and email providers, and every custom server module. A new or changed setting must fit one of these two categories.
+- **Custom server modules** (asset storage, email, AI providers) are `.js`/`.mjs` files, relative to the working directory, that import their define helper from `handoff-app/providers`. The registry build stops when a module imports `handoff-app`. The build copies each module and the packages it imports into the registry bundle.
+
+Package entry points (`handoff-app`, `/react`, `/handlebars`, `/pattern`, `/providers`) map to `src/index.ts`, `src/react.ts`, `src/handlebars.ts`, `src/pattern.ts`, `src/providers.ts`. Adding a renderer touches several `Record<RendererKind, …>` maps — see [src/catalog/README.md](src/catalog/README.md).
+
+Most `src/<module>/` directories have a `README.md` describing their files and flow. Read it before changing a module, and update it when the module's contract changes.
+
+## Conventions
+
+- **Breaking changes** get migration steps in [UPGRADE.md](UPGRADE.md), per major version.
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md) follows Keep a Changelog + SemVer. Entries are written during release prep on the release branch. Do not add or edit entries in feature or fix work unless asked.
+- **Docs style**: README/RECIPES/CHANGELOG use short, plain, imperative sentences (Simplified Technical English style).
+
+### Branches and releases
+
+- **Branch names**: `<category>/<kebab-case-topic>`, e.g. `feature/config-profiles`, `bugfix/code-toc-md`, `docs/readme-rewrite`, `chore/remove-mdx`. Categories in use: `feature/`, `bugfix/`, `docs/`, `chore/`, `release/`.
+- **Release branches**: each release has a `release/X.Y.Z` branch. Feature and fix branches start from it and merge back into it through a PR, not into `main`. A major release can first collect work in a long-running `integration/X.Y.Z` branch, from which `release/X.Y.Z` is cut (as for 2.0.0).
+- **Prereleases and final version**: `np` (`npm run release`) runs on the release branch. It publishes prereleases (`X.Y.Z-N`) and then the final `X.Y.Z`; each creates a commit whose message is the bare version and a `vX.Y.Z[-N]` tag. Do not write these commits by hand. Release prep (changelog entries and date, last fixes) is committed directly on the release branch.
+- **`main`** receives only release merges: a PR from `release/X.Y.Z` into `main` ships the release.
+
+### Commit messages
+
+Use a Conventional Commit subject with no scope and, normally, no body:
+
+```
+<type>: <description>
+```
+
+- Types: `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `build`, `ci`, `perf`, `style`.
+- Description: lowercase, imperative, no trailing period. State what the change achieves for the user, not how the code does it; omit file names and implementation details unless needed for clarity.
+- Several distinct changes in one commit: one imperative clause each, separated by `; `. Supporting changes belong to the change they support and are not listed separately.
+- No fixed length limit; the purpose sets the length.
+
+Examples from history:
+
+```
+fix: use plain JSON Schema for MCP tool inputs
+feat: move Figma settings to integrations.figma
+refactor: rename define entry point and storage adapter to providers
+feat: accept fromEnv() references in asset storage options and resolve them at request time; remove providerId and record blobs as database or custom
+```

package/CHANGELOG.md

@@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## \[2.0.1] - 2026-11-01
+
+This release makes catalog items smaller to publish and reports packages that
+are too large for the registry.
+
+### Changed
+
+* Client bundles of interactive React previews use the minified production
+  build of React. This reduces each bundle by about 1 MB, so components and
+  patterns publish within the registry request limit more often. In the local
+  workspace, previews no longer show React development warnings. To get them
+  back, set `minify: false` and a development `process.env.NODE_ENV` in
+  `hooks.clientBuildConfig`, then rebuild with `--force`.
+
+### Fixed
+
+* `publish` stops before the upload when a package is larger than the 4.5 MB
+  registry limit and names the largest files.
+* A `413` response from the registry now shows a clear "too large" message.
+
 ## \[2.0.0] - 2026-10-16
 
 Handoff 2.0 adds a shared registry to the local workspace. You write content in

package/CLAUDE.md

@@ -1,7 +1,98 @@
-# Instructions
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Local instructions
 
 Before starting work, check whether `AGENTS.local.md` exists in the repository root.
 
 If it exists, read and follow its instructions in addition to this file. Treat `AGENTS.local.md` as developer-specific local guidance.
 
 If it does not exist, proceed normally.
+
+## Project
+
+`handoff-app` is an npm package (CLI + library) that turns design tokens (fetched from Figma), components, patterns, and Markdown pages into a Next.js documentation app and distributable artifacts. User-facing docs: [README.md](README.md), [RECIPES.md](RECIPES.md), [docs/cli.md](docs/cli.md), [docs/api.md](docs/api.md), [UPGRADE.md](UPGRADE.md).
+
+Requires Node.js >= 22 and npm >= 10.
+
+## Commands
+
+```bash
+npm run build     # tsc: compiles src/ (except src/app) to dist/
+npm run lint      # next lint over src/app
+npm test          # alias for lint; there is no unit test suite
+npx tsc -p src/app/tsconfig.json --noEmit   # typecheck the Next.js app (root tsc excludes src/app);
+                                            # errors under a stale src/app/.next/types are not real
+npx drizzle-kit generate                    # generate a registry migration after editing src/registry/db/schema.ts
+```
+
+The CLI (`dist/cli.js`, bin `handoff-app`) always runs against a **working directory**: the directory that holds `handoff.config.ts` (or `HANDOFF_WORKING_PATH`). This repo is not a Handoff project, so to exercise a change, build here and run the CLI from a consumer project that uses this build (`start`, `dev`, `build`, `fetch`, `publish`, `checkout`, ...). Verify behavior there; `npm run lint` and the two `tsc` runs are the only checks in this repo.
+
+Formatting: Prettier (config in `package.json`: 140 cols, single quotes, `es5` trailing commas, Tailwind class sorting) and `.editorconfig` (2 spaces, LF).
+
+## Architecture
+
+### Runtime modes
+
+- **Workspace** (default): local files are the source of truth; no database. It is the **only** place that builds content.
+- **Registry**: a deployed catalog backed by PostgreSQL (Drizzle). It serves only what a workspace publishes. It never builds and never reads workspace source.
+- A **connected workspace** publishes to / checks out from a registry; it is not a third mode.
+
+`runtime.mode` selects the mode; `build --target registry` sets registry mode in the generated app. Keep registry-only dependencies (Drizzle/Postgres) out of the workspace and static paths — e.g. `src/store/index.ts` deliberately does not re-export the registry store; registry consumers import `@handoff/store/registry` lazily.
+
+### Two TypeScript programs
+
+- **`src/` (minus `src/app`)** — the Node CLI/library, CommonJS, compiled by root `tsconfig.json` to `dist/`. `src/index.ts` holds the `Handoff` class (`fetch`, `build`, `publish`, `checkout`, `start`, `dev`); `src/cli.ts` registers the yargs commands in `src/commands/`.
+- **`src/app/`** — the Next.js (pages router) documentation app. It is not compiled by `tsc`; at build/start time `src/app-builder` stages it into `.handoff/<projectId>/` under the package and runs `next build` / `next dev`. It imports the core via the `@handoff/*` alias (→ `src/*`). It also hosts the APIs: docs API, registry API, MCP endpoint (`/api/mcp`), auth, and the AI assistant (`src/app/lib/*`, `src/app/pages/api/*`).
+
+### Main flows
+
+- **fetch**: `src/pipeline` — Figma auth → extract → fonts → token transformers; output goes to the working directory's `exported/`.
+- **build/start**: `src/config` loads `handoff.config.*` + profile sidecar + env, then `initRuntimeConfig()` normalizes catalog declarations (`src/catalog`) into component/pattern records; `src/transformers` builds previews with Vite/esbuild per renderer (React, Handlebars, CSF); `src/cache` skips unchanged components (`.handoff/.cache/build-cache.json`, bypass with `--force`); `src/app-builder` builds the app (static → `out/static`, registry → `out/registry`, `--package vercel` → `.vercel/output`). Watch mode uses chokidar + a WebSocket reload server with diff-aware rebuilds.
+- **publish/checkout**: `src/registry` (`publish/`, `checkout/`, `transfer.ts`, `tokens/`, `assets/`, `auth/`) against the registry API in `src/app/lib/registry-api`. Storage is abstracted by `src/store` (filesystem vs. registry implementations of the same interfaces). Asset blobs go through a pluggable storage provider; email and AI providers are also pluggable custom server modules (`handoff-app/providers`).
+- **Migrations**: SQL in `drizzle/` ships with the package and is applied by `handoff-app db:migrate`.
+
+### Config and server-module rules
+
+- **Baked vs. request-time values.** For a `fromEnv('NAME')` value, the build keeps only the variable name, and a deployed registry reads the value at request time. Secrets must use `fromEnv()`. These settings change the shape of the build and are baked, so a change needs a rebuild: `runtime.mode`, `runtime.mcp`, `runtime.ai.enabled`, the database driver, the asset storage and email providers, and every custom server module. A new or changed setting must fit one of these two categories.
+- **Custom server modules** (asset storage, email, AI providers) are `.js`/`.mjs` files, relative to the working directory, that import their define helper from `handoff-app/providers`. The registry build stops when a module imports `handoff-app`. The build copies each module and the packages it imports into the registry bundle.
+
+Package entry points (`handoff-app`, `/react`, `/handlebars`, `/pattern`, `/providers`) map to `src/index.ts`, `src/react.ts`, `src/handlebars.ts`, `src/pattern.ts`, `src/providers.ts`. Adding a renderer touches several `Record<RendererKind, …>` maps — see [src/catalog/README.md](src/catalog/README.md).
+
+Most `src/<module>/` directories have a `README.md` describing their files and flow. Read it before changing a module, and update it when the module's contract changes.
+
+## Conventions
+
+- **Breaking changes** get migration steps in [UPGRADE.md](UPGRADE.md), per major version.
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md) follows Keep a Changelog + SemVer. Entries are written during release prep on the release branch. Do not add or edit entries in feature or fix work unless asked.
+- **Docs style**: README/RECIPES/CHANGELOG use short, plain, imperative sentences (Simplified Technical English style).
+
+### Branches and releases
+
+- **Branch names**: `<category>/<kebab-case-topic>`, e.g. `feature/config-profiles`, `bugfix/code-toc-md`, `docs/readme-rewrite`, `chore/remove-mdx`. Categories in use: `feature/`, `bugfix/`, `docs/`, `chore/`, `release/`.
+- **Release branches**: each release has a `release/X.Y.Z` branch. Feature and fix branches start from it and merge back into it through a PR, not into `main`. A major release can first collect work in a long-running `integration/X.Y.Z` branch, from which `release/X.Y.Z` is cut (as for 2.0.0).
+- **Prereleases and final version**: `np` (`npm run release`) runs on the release branch. It publishes prereleases (`X.Y.Z-N`) and then the final `X.Y.Z`; each creates a commit whose message is the bare version and a `vX.Y.Z[-N]` tag. Do not write these commits by hand. Release prep (changelog entries and date, last fixes) is committed directly on the release branch.
+- **`main`** receives only release merges: a PR from `release/X.Y.Z` into `main` ships the release.
+
+### Commit messages
+
+Use a Conventional Commit subject with no scope and, normally, no body:
+
+```
+<type>: <description>
+```
+
+- Types: `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `build`, `ci`, `perf`, `style`.
+- Description: lowercase, imperative, no trailing period. State what the change achieves for the user, not how the code does it; omit file names and implementation details unless needed for clarity.
+- Several distinct changes in one commit: one imperative clause each, separated by `; `. Supporting changes belong to the change they support and are not listed separately.
+- No fixed length limit; the purpose sets the length.
+
+Examples from history:
+
+```
+fix: use plain JSON Schema for MCP tool inputs
+feat: move Figma settings to integrations.figma
+refactor: rename define entry point and storage adapter to providers
+feat: accept fromEnv() references in asset storage options and resolve them at request time; remove providerId and record blobs as database or custom
+```

package/README.md

@@ -938,6 +938,11 @@ npm run publish -- all --dry-run
 npm run publish -- catalog --no-build
 ```
 
+A publish sends each catalog item or page in one request of at most 4.5 MB.
+An item's package contains its rendered previews, its client bundle, and the
+shared stylesheet and script. A pattern also contains the artifacts of the
+components it uses.
+
 After a publish, reload the registry to see the published items and
 foundations.
 

package/dist/cli.js

@@ -30,7 +30,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-    return 'Handoff App - 2.0.0';
+    return 'Handoff App - 2.0.1';
 };
 /**
  * Define a CLI error

package/dist/registry/publish/errors.js

@@ -4,6 +4,10 @@ exports.describePublishError = exports.describeUploadFailure = void 0;
 const client_1 = require("../client");
 /** Map registry error codes to the actionable messages used by publish commands. */
 const describeUploadFailure = (error, registryUrl, rejectedPayload) => {
+    // An oversized body is rejected by the platform or body parser, so the response has no error envelope.
+    if (error.status === 413) {
+        return `The registry at ${registryUrl} rejected the ${rejectedPayload} as too large (413). Reduce the size of its largest files and publish again.`;
+    }
     switch (error.code) {
         case 'runtime_mode_conflict':
             return `The registry at ${registryUrl} is not running in registry mode, so it cannot accept publishes: ${error.message}`;

package/dist/registry/publish/index.js

@@ -160,6 +160,7 @@ const publishEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, f
     }
     const pkg = yield (0, package_1.buildPublishPackage)(handoff, kind, id);
     (0, package_1.assertRequiredArtifactsPresent)(pkg);
+    (0, package_1.assertPackageWithinUploadLimit)(kind, id, pkg);
     const contents = `${pkg.artifacts.length} artifact(s), ${pkg.files.length} source file(s)`;
     if (!client) {
         logger_1.Logger.info(`Would publish ${kind} "${id}" (${contents}).`);
@@ -251,6 +252,7 @@ const uploadEntities = (handoff, transport, kind, ids) => __awaiter(void 0, void
         try {
             const pkg = yield (0, package_1.buildPublishPackage)(handoff, kind, id);
             (0, package_1.assertRequiredArtifactsPresent)(pkg);
+            (0, package_1.assertPackageWithinUploadLimit)(kind, id, pkg);
             const remoteHash = remoteHashById.get(id);
             const localHash = entityHash(pkg.build);
             if (!handoff.force && remoteHash && localHash && remoteHash === localHash) {

package/dist/registry/publish/package.d.ts

@@ -23,5 +23,11 @@ export declare class PublishPackageError extends Error {
  * upload, so a publish fails locally (no network call) on a missing required artifact.
  */
 export declare const assertRequiredArtifactsPresent: (pkg: TransferPackage) => void;
+/**
+ * The largest publish request body the registry accepts. Vercel rejects a larger function body with
+ * `413 FUNCTION_PAYLOAD_TOO_LARGE`, and the transfer route's `bodyParser.sizeLimit` matches it.
+ */
+export declare const MAX_PUBLISH_BODY_BYTES = 4500000;
+export declare const assertPackageWithinUploadLimit: (kind: TransferEntityKind, id: string, pkg: TransferPackage) => void;
 /** Assemble the publish package for an entity from the generated `public/api` artifacts. */
 export declare const buildPublishPackage: (handoff: Handoff, kind: TransferEntityKind, id: string) => Promise<TransferPackage>;

package/dist/registry/publish/package.js

@@ -37,7 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildPublishPackage = exports.assertRequiredArtifactsPresent = exports.PublishPackageError = void 0;
+exports.buildPublishPackage = exports.assertPackageWithinUploadLimit = exports.MAX_PUBLISH_BODY_BYTES = exports.assertRequiredArtifactsPresent = exports.PublishPackageError = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const source_files_1 = require("../../store/source-files");
@@ -269,6 +269,26 @@ const assertRequiredArtifactsPresent = (pkg) => {
     }
 };
 exports.assertRequiredArtifactsPresent = assertRequiredArtifactsPresent;
+/**
+ * The largest publish request body the registry accepts. Vercel rejects a larger function body with
+ * `413 FUNCTION_PAYLOAD_TOO_LARGE`, and the transfer route's `bodyParser.sizeLimit` matches it.
+ */
+exports.MAX_PUBLISH_BODY_BYTES = 4500000;
+const formatMegabytes = (bytes) => `${(bytes / 1000000).toFixed(1)} MB`;
+const assertPackageWithinUploadLimit = (kind, id, pkg) => {
+    const size = Buffer.byteLength(JSON.stringify(pkg));
+    if (size <= exports.MAX_PUBLISH_BODY_BYTES)
+        return;
+    const largest = [...pkg.artifacts, ...pkg.files]
+        .map((entry) => ({ path: entry.path, size: Buffer.byteLength(entry.content) }))
+        .sort((a, b) => b.size - a.size)
+        .slice(0, 3)
+        .map((entry) => `  - ${entry.path} (${formatMegabytes(entry.size)})`)
+        .join('\n');
+    throw new PublishPackageError(`The ${kind} "${id}" package is ${formatMegabytes(size)}; the registry accepts at most ` +
+        `${formatMegabytes(exports.MAX_PUBLISH_BODY_BYTES)} per publish. Largest entries:\n${largest}`);
+};
+exports.assertPackageWithinUploadLimit = assertPackageWithinUploadLimit;
 /** Assemble the publish package for an entity from the generated `public/api` artifacts. */
 const buildPublishPackage = (handoff, kind, id) => kind === 'component'
     ? buildComponentPackage(handoff, id)

package/dist/transformers/utils/build.d.ts

@@ -15,6 +15,10 @@ export declare const STYLE_IMPORT_LOADERS: Record<string, esbuild.Loader>;
 export declare const DEFAULT_SSR_BUILD_CONFIG: esbuild.BuildOptions;
 /**
  * Default esbuild configuration for client builds
+ *
+ * Production React, minified: each client bundle carries its own React copy, and a publish uploads it
+ * with the component and with every pattern that uses it. A development build quickly pushes a pattern
+ * past serverless request body limits.
  */
 export declare const DEFAULT_CLIENT_BUILD_CONFIG: esbuild.BuildOptions;
 /** Apply after a consumer hook: a hook that replaces `loader` would otherwise drop these. */

package/dist/transformers/utils/build.js

@@ -45,6 +45,10 @@ exports.DEFAULT_SSR_BUILD_CONFIG = {
 };
 /**
  * Default esbuild configuration for client builds
+ *
+ * Production React, minified: each client bundle carries its own React copy, and a publish uploads it
+ * with the component and with every pattern that uses it. A development build quickly pushes a pattern
+ * past serverless request body limits.
  */
 exports.DEFAULT_CLIENT_BUILD_CONFIG = {
     bundle: true,
@@ -53,7 +57,8 @@ exports.DEFAULT_CLIENT_BUILD_CONFIG = {
     platform: 'browser',
     jsx: 'automatic',
     sourcemap: false,
-    minify: false,
+    minify: true,
+    define: { 'process.env.NODE_ENV': '"production"' },
     loader: exports.STYLE_IMPORT_LOADERS,
 };
 /** Apply after a consumer hook: a hook that replaces `loader` would otherwise drop these. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",

package/src/cli.ts

@@ -21,7 +21,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-  return 'Handoff App - 2.0.0';
+  return 'Handoff App - 2.0.1';
 };
 
 /**

package/src/registry/publish/errors.ts

@@ -8,6 +8,10 @@ export const describeUploadFailure = (
   registryUrl: string,
   rejectedPayload: RejectedPublishPayload
 ): string => {
+  // An oversized body is rejected by the platform or body parser, so the response has no error envelope.
+  if (error.status === 413) {
+    return `The registry at ${registryUrl} rejected the ${rejectedPayload} as too large (413). Reduce the size of its largest files and publish again.`;
+  }
   switch (error.code) {
     case 'runtime_mode_conflict':
       return `The registry at ${registryUrl} is not running in registry mode, so it cannot accept publishes: ${error.message}`;

package/src/registry/publish/index.ts

@@ -21,7 +21,7 @@ import { loginCommandHint, resolveAuthenticatedRegistryConnection, unusedLoginNo
 import type { EntitySummary, TransferEntityKind } from '../transfer';
 import { quoteIds, selectIds, splitCatalogIds } from '../selection';
 import { describePublishError, describeUploadFailure } from './errors';
-import { assertRequiredArtifactsPresent, buildPublishPackage, PublishPackageError } from './package';
+import { assertPackageWithinUploadLimit, assertRequiredArtifactsPresent, buildPublishPackage, PublishPackageError } from './package';
 
 /** A connected-workspace configuration or precondition failure surfaced to the CLI. */
 export class PublishError extends Error {
@@ -173,6 +173,7 @@ export const publishEntity = async (handoff: Handoff, kind: TransferEntityKind,
 
   const pkg = await buildPublishPackage(handoff, kind, id);
   assertRequiredArtifactsPresent(pkg);
+  assertPackageWithinUploadLimit(kind, id, pkg);
 
   const contents = `${pkg.artifacts.length} artifact(s), ${pkg.files.length} source file(s)`;
   if (!client) {
@@ -274,6 +275,7 @@ const uploadEntities = async (handoff: Handoff, transport: PublishTransport, kin
     try {
       const pkg = await buildPublishPackage(handoff, kind, id);
       assertRequiredArtifactsPresent(pkg);
+      assertPackageWithinUploadLimit(kind, id, pkg);
 
       const remoteHash = remoteHashById.get(id);
       const localHash = entityHash(pkg.build);

package/src/registry/publish/package.ts

@@ -285,6 +285,30 @@ export const assertRequiredArtifactsPresent = (pkg: TransferPackage): void => {
   }
 };
 
+/**
+ * The largest publish request body the registry accepts. Vercel rejects a larger function body with
+ * `413 FUNCTION_PAYLOAD_TOO_LARGE`, and the transfer route's `bodyParser.sizeLimit` matches it.
+ */
+export const MAX_PUBLISH_BODY_BYTES = 4_500_000;
+
+const formatMegabytes = (bytes: number): string => `${(bytes / 1_000_000).toFixed(1)} MB`;
+
+export const assertPackageWithinUploadLimit = (kind: TransferEntityKind, id: string, pkg: TransferPackage): void => {
+  const size = Buffer.byteLength(JSON.stringify(pkg));
+  if (size <= MAX_PUBLISH_BODY_BYTES) return;
+
+  const largest = [...pkg.artifacts, ...pkg.files]
+    .map((entry) => ({ path: entry.path, size: Buffer.byteLength(entry.content) }))
+    .sort((a, b) => b.size - a.size)
+    .slice(0, 3)
+    .map((entry) => `  - ${entry.path} (${formatMegabytes(entry.size)})`)
+    .join('\n');
+  throw new PublishPackageError(
+    `The ${kind} "${id}" package is ${formatMegabytes(size)}; the registry accepts at most ` +
+      `${formatMegabytes(MAX_PUBLISH_BODY_BYTES)} per publish. Largest entries:\n${largest}`
+  );
+};
+
 /** Assemble the publish package for an entity from the generated `public/api` artifacts. */
 export const buildPublishPackage = (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<TransferPackage> =>
   kind === 'component'

package/src/transformers/utils/build.ts

@@ -31,6 +31,10 @@ export const DEFAULT_SSR_BUILD_CONFIG: esbuild.BuildOptions = {
 
 /**
  * Default esbuild configuration for client builds
+ *
+ * Production React, minified: each client bundle carries its own React copy, and a publish uploads it
+ * with the component and with every pattern that uses it. A development build quickly pushes a pattern
+ * past serverless request body limits.
  */
 export const DEFAULT_CLIENT_BUILD_CONFIG: esbuild.BuildOptions = {
   bundle: true,
@@ -39,7 +43,8 @@ export const DEFAULT_CLIENT_BUILD_CONFIG: esbuild.BuildOptions = {
   platform: 'browser',
   jsx: 'automatic',
   sourcemap: false,
-  minify: false,
+  minify: true,
+  define: { 'process.env.NODE_ENV': '"production"' },
   loader: STYLE_IMPORT_LOADERS,
 };