How to Troubleshoot Astryx Build Errors: A Complete Developer Guide

The most effective way to troubleshoot Astryx build errors is to systematically check the Node version, clean the workspace, run type checks across all packages, validate StyleX output, and use debug logging to isolate the failing layer.

Astryx is a Facebook open-source monorepo that uses pnpm workspaces, TypeScript, Vitest, and StyleX to build a design-system library and accompanying tooling. Build failures typically originate from one of six distinct layers, and understanding how to diagnose each layer will save hours of debugging time.

Recognize the Error Layer

Build failures in Astryx fall into predictable categories. Identifying which layer produces your error message is the first step toward resolution.

Package Manager Errors

pnpm workspace resolution is the foundation of Astryx. When this layer fails, you'll see messages like ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL or missing lockfile warnings.

These errors live in pnpm-workspace.yaml, pnpm-lock.yaml, and each package's package.json. Run this diagnostic:

pnpm install --frozen-lockfile

Inspect the output for "cannot resolve" messages that indicate which workspace package cannot find its dependency.

TypeScript Compilation Errors

Type-checking failures appear as TS2307: Cannot find module … or mismatched tsconfig settings across packages. The source configuration lives in tsconfig.json and each package's tsconfig.*.json.

Run the workspace-wide type check to isolate the first error (subsequent errors usually cascade from it):

pnpm -r exec -- tsc --noEmit

This command compiles every workspace package in isolation and reports exact file paths and line numbers.

StyleX Generation Failures

CSS-in-JS compilation fails with stylex: unknown token or runtime ReferenceError for generated CSS. The StyleX definitions reside in packages/*/src/**/*.stylex.ts and the scanner logic is in internal/stylex-capabilities/scan.mjs.

Re-run the StyleX validator to catch missing markers:

pnpm run verify-exports

This executes scripts/verify-exports.mjs, which checks that every exported component has corresponding StyleX definitions.

Vitest Test Suite Failures

Test runner errors manifest as ERR_MODULE_NOT_FOUND, snapshot mismatches, or CI hangs. Configuration lives in vitest.config.ts and vitest.global-setup.node.mjs.

Execute tests locally to capture the full stack trace:

pnpm test

The stack trace will point directly to the offending import or mock configuration.

CLI and Build Script Errors

Build script failures occur when running $ASTRYX build, showing node:internal/modules/cjs/loader: Cannot find module …. The entry point is packages/cli/clients/cli/bin/astryx.mjs with supporting scripts in scripts/.

Enable verbose debug logging:

DEBUG=astryx:* pnpm build

This output shows precisely which package is being processed when the error occurs.

Environment and Node Version Errors

Runtime syntax errors like SyntaxError: Unexpected token … for optional-chaining indicate Node version mismatches. The required version is specified in .nvmrc (currently v20).

Verify your environment:

node -v
cat .nvmrc

Follow the Systematic Troubleshooting Workflow

This sequence isolates build errors from most to least frequent causes.

Step 1: Verify Node Runtime

Mismatched Node versions cause syntax errors in modern TypeScript output. Check the specification and switch versions:

nvm use $(cat .nvmrc)

Step 2: Clean the Workspace

Stale caches create phantom module-resolution failures:

pnpm clean && pnpm install --frozen-lockfile

Step 3: Run Workspace-Wide Type Check

pnpm -r exec -- tsc --noEmit

Fix the first error reported; later errors typically cascade from it.

Step 4: Execute StyleX Validation

pnpm run verify-exports

This validates that every exported component in packages/core/src/stylex/ has proper marker definitions.

Step 5: Build the Library

pnpm build

If this fails, the console shows which package script (packages/<pkg>/scripts/build.mjs) exited with non-zero status. Examine that script to see the exact build command—typically vite build or rollup.

Step 6: Run the Test Suite

pnpm test

Failing tests often reveal regressions that broke the build. Watch for expect(...).toMatchSnapshot() mismatches.

Step 7: Consult Release Documentation

The docs/release.md file contains the exact sequence of steps that CI uses. Compare your local steps against this reference to identify deviations.

Fix Common Error Messages

Error	Cause	Solution
ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL	Workspace package prepare script failure	Delete node_modules in the offending package: pnpm -C packages/<pkg> remove node_modules then reinstall
TS2307: Cannot find module '@astryxdesign/core'	Core package not built before dependent import	Run pnpm -r exec -- pnpm build starting with @astryxdesign/core (order defined in pnpm-workspace.yaml)
stylex: unknown token "var(--astryx-color-primary)"	Missing CSS variable definition	Add to packages/core/src/theme/vars.stylex.ts and re-run pnpm stylex:scan
ReferenceError: process is not defined	Node globals in browser build	Guard with if (typeof process !== 'undefined') or move to server-only module
Vitest: Could not resolve import …	Path alias (~) misconfigured	Add alias in vitest.config.ts under test: { resolve: { alias: { '~': path.resolve(__dirname, 'src') } } }

Essential Commands for CI Debugging

# Re-install exact versions

pnpm install --frozen-lockfile

# Full type-check across workspaces

pnpm -r exec -- tsc --noEmit

# Validate StyleX output

pnpm run verify-exports

# Build everything (skip verification)

pnpm -r run build --no-verify

# Run specific failing test

pnpm test -- <test-file>

Key Source Files for Deep Debugging

• pnpm-workspace.yaml — Declares workspace packages and dependency order
• scripts/verify-exports.mjs — StyleX scanner and export validation
• vitest.config.ts — Test runner configuration with path aliasing
• packages/cli/clients/cli/bin/astryx.mjs — CLI entry point for build commands
• packages/core/src/stylex/ — StyleX marker definitions and theme variables

Summary

• Always verify Node version against .nvmrc before any other debugging step
• Clean installs with --frozen-lockfile eliminate most package manager issues
• Type-check first with tsc --noEmit to find root-cause errors before cascading failures
• StyleX validation via verify-exports catches CSS generation problems early
• Debug logging with DEBUG=astryx:* reveals exactly which build script fails
• Match CI behavior by following the sequence in docs/release.md

Frequently Asked Questions

Why does Astryx fail to find workspace packages after a fresh clone?

The monorepo requires pnpm's workspace resolution to link internal dependencies. Run pnpm install --frozen-lockfile from the repository root, not npm install or yarn. The pnpm-workspace.yaml file defines which directories contain packages, and pnpm creates symlinks between them during installation.

How do I rebuild only the core package when debugging @astryxdesign/core imports?

Run pnpm -C packages/core build to build just the core package, then verify dependents compile with pnpm -r exec -- tsc --noEmit. The workspace build order in pnpm-workspace.yaml ensures core builds before packages that depend on it, but manual intervention helps when iterating on core changes.

What causes StyleX "unknown token" errors in production builds but not development?

Production builds run the full StyleX scanner via scripts/verify-exports.mjs, which validates all CSS variable references against packages/core/src/theme/vars.stylex.ts. Development may skip this validation. Add missing variables to the theme file and re-run pnpm stylex:scan to regenerate the CSS definition map.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}