Adding Components

Problem

The component breaks the entire page with a runtime error when rendering styles based on a prop (e.g., size).

// Error encountered in Switch.tsx
const { track } = sizes[size]; // size is undefined or invalid -> CRASH

// Error encountered in Switch.tsx
const { track } = sizes[size]; // size is undefined or invalid -> CRASH

Root Cause

This usually happens when a prop is passed as undefined (despite TypeScript types) or an invalid string value, and used directly as a key to access an object without validation. In compiled JS, this results in trying to access a property on undefined.

Solution

Always validate keys before using them to access style objects. Implement a "safeguard" or fallback mechanism.

// Design pattern for safe property access
const safeSize = (size && sizes[size]) ? size : 'md';
const { track } = sizes

// Design pattern for safe property access
const safeSize = (size && sizes[size]) ? size : 'md';
const { track } = sizes[safeSize]; // Safe access guaranteed

Symptoms

• Build passes locally but fails on Vercel with generic "Webpack errors".
• Errors pointing to globals.css or css-loader.
• TypeScript errors like TS2742: The inferred type cannot be named.

Solutions

// package.json in the app
"devDependencies": {
  // Tailwind config is bundled within @thesage/ui
}

// package.json in the app
"devDependencies": {
  // Tailwind config is bundled within @thesage/ui
}

// Instead of: const Form = FormProvider;
// Use:
const Form: typeof FormProvider = FormProvider;

// Instead of: const Form = FormProvider;
// Use:
const Form: typeof FormProvider = FormProvider;

// Root package.json
"pnpm": {
  "onlyBuiltDependencies": ["esbuild", "sharp"]
}

// Root package.json
"pnpm": {
  "onlyBuiltDependencies": ["esbuild", "sharp"]
}

Problem

Vercel build fails with error: error: unknown option '--filter=...'

> @ecosystem/web@0.1.0 build
> next build --filter=@ecosystem/web
error: unknown option '--filter=@ecosystem/web'
ELIFECYCLE

> @ecosystem/web@0.1.0 build
> next build --filter=@ecosystem/web
error: unknown option '--filter=@ecosystem/web'
ELIFECYCLE Command failed with exit code 1.

Root Cause

When using pnpm build --filter=... in vercel.json, Vercel runs the build script from package.json and appends the filter flag. This results in next build --filter=..., but Next.js doesn't recognize the --filter flag (it's a Turborepo flag).

{
  "buildCommand": "pnpm build --filter=@ecosystem/web"
}

{
  "buildCommand": "pnpm build --filter=@ecosystem/web"
}

Solution

Use turbo build directly instead of pnpm build. This invokes Turborepo's build orchestration, which will build the design-system package first, then the app.

{
  "buildCommand": "turbo build --filter=@ecosystem/web",
  "installCommand": "pnpm install --frozen-lockfile"
}

{
  "buildCommand": "turbo build --filter=@ecosystem/web",
  "installCommand": "pnpm install --frozen-lockfile"
}

How It Works

1. 1.Turbo reads the dependency graph from turbo.json
2. 2.Sees that web depends on design-system (via dependsOn: ["^build"])
3. 3.Builds @thesage/ui first (runs tsup to generate dist files)
4. 4.Then builds @ecosystem/web (runs next build)

Preventing This Issue

• •Always use turbo directly for monorepo builds in Vercel
• •Test the vercel.json buildCommand locally before deploying
• •Remember: pnpm [script] looks for package.json scripts, turbo [task] uses Turborepo

Problem

• Build fails immediately on Vercel but works locally.
• Error: Module not found: Can't resolve '@thesage/tokens' (or similar workspace package).

Root Cause

The default Vercel build command (or a simple next build) builds only the app. It does not automatically build the upstream workspace dependencies (like design-system or tokens) that the app depends on.

Because the upstream dist/ files don't exist in the CI environment, the app build crashes when trying to resolve them.

Solution

Update the Build Command in Vercel settings to use Turborepo with the dependency-inclusive filter syntax (...).

pnpm turbo build --filter=creative-powerup...

pnpm turbo build --filter=creative-powerup...