How to Validate TypeScript Compilation for Generated Components: A Complete Guide

The stitch-build react-components skill provides a built-in validator that parses TypeScript files with SWC and walks the AST to enforce coding conventions, exiting with status 0 for valid components or status 1 for violations.

The google-labs-code/stitch-skills repository includes a lightweight validation mechanism specifically designed to validate TypeScript compilation for generated components without the overhead of a full tsc execution. Located in the stitch-build → react-components skill, this validator performs syntactic health checks by leveraging the SWC compiler to parse and analyze your TSX files.

How the Validator Works

The validation script resides at plugins/stitch-build/skills/react-components/scripts/validate.js. It utilizes @swc/core to parse each TypeScript file into an Abstract Syntax Tree (AST), then traverses the nodes to enforce two critical conventions:

1. Props Interface Enforcement – Every component must export a TypeScript interface ending with Props (e.g., ButtonProps, CardProps). This ensures a typed contract for component properties.
2. Hex Color Detection – The scanner flags inline Tailwind or utility class values containing raw hex color literals (#RRGGBB), encouraging the use of design tokens or Tailwind theme values instead.

If both checks pass, the script exits with status 0. If violations exist, it prints detailed error messages and exits with status 1, providing a "compile-time-like" validation step suitable for CI integration.

Prerequisites and Dependencies

The validator requires @swc/core as a dependency, which is already declared in the skill's package.json at plugins/stitch-build/skills/react-components/package.json. Ensure your environment has Node.js installed, then install dependencies:

cd plugins/stitch-build/skills/react-components
npm install

Running the Validator

Manual Execution

Invoke the validator directly by passing the path to a generated component file:

node plugins/stitch-build/skills/react-components/scripts/validate.js \
    plugins/stitch-build/skills/react-components/examples/gold-standard-card.tsx

Successful output:

🔍 Scanning AST...
--- Validation for: gold-standard-card.tsx ---
✅ Props declaration found.
✅ No hardcoded hex values found.

✨ COMPONENT VALID.

Failed output:

❌ MISSING: Props interface (must end in 'Props').
❌ STYLE: Found 2 hardcoded hex codes.
   - #ff0000
   - #00ff00

🚫 VALIDATION FAILED.

NPM Script Integration

Add the validator to your package.json scripts for easier access:

{
  "scripts": {
    "validate": "node plugins/stitch-build/skills/react-components/scripts/validate.js"
  }
}

Then run:

npm run validate -- path/to/YourComponent.tsx

Git Pre-commit Hooks

Prevent invalid components from entering your repository by adding the validator to your Git hooks. Create or edit .git/hooks/pre-commit:

#!/usr/bin/env sh
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.tsx\?$')
for f in $STAGED_FILES; do
  node plugins/stitch-build/skills/react-components/scripts/validate.js "$f" || exit 1
done

This hook aborts the commit if any staged TypeScript file fails validation.

Validation Rules Explained

Props Interface Requirement

As implemented in plugins/stitch-build/skills/react-components/resources/component-template.tsx, every generated component must export an interface named with the Props suffix. The validator walks the AST to detect TSInterfaceDeclaration nodes and verifies the identifier ends with "Props". This convention guarantees that consuming applications have explicit type contracts for component props.

No Hard-Coded Hex Colors

The validator scans string literals and template expressions for hexadecimal color patterns (#[0-9A-Fa-f]{6}). When found, the script reports the specific hex values and their locations. This rule ensures design system consistency by forcing developers to use Tailwind's theme configuration or CSS variables rather than arbitrary color values.

Extending the Validator

You can customize the validation logic by editing plugins/stitch-build/skills/react-components/scripts/validate.js. For example, to enforce a default export requirement, add detection inside the walk function:

if (node.type === 'ExportDefaultDeclaration') hasDefaultExport = true;

Then update the final status check:

if (!hasDefaultExport) console.error('❌ MISSING: default export.');

This extensibility allows teams to add project-specific conventions without modifying the underlying component generation logic.

Summary

• The stitch-build react-components validator uses SWC AST parsing to check TypeScript files without invoking tsc.
• It enforces two primary conventions: Props interfaces (ending in Props) and no hard-coded hex colors.
• The script exits with status 0 for valid components and status 1 for violations, making it ideal for CI/CD pipelines.
• Integration options include manual execution, NPM scripts, and Git pre-commit hooks.
• The validator is fully extensible via the walk function in validate.js to support custom team standards.

Frequently Asked Questions

What is the difference between this validator and running tsc?

The validator performs convention-based checks using SWC's fast AST parser rather than full TypeScript compilation. While tsc verifies type correctness and emits JavaScript, this tool specifically checks for coding standards (Props interfaces, hex color usage) and executes significantly faster, making it suitable for pre-commit hooks and rapid CI feedback.

How do I add custom validation rules?

Edit plugins/stitch-build/skills/react-components/scripts/validate.js and add detection logic inside the AST walk function. Track state variables (like hasDefaultExport) and report errors in the final status check section. The modular structure allows you to insert new checks without modifying existing validation logic.

Can I use this validator for non-React TypeScript files?

Yes, though the built-in rules specifically target React component conventions (Props interfaces). The SWC-based parser in validate.js can analyze any TypeScript or TSX file. You would need to modify the validation rules to match your specific file patterns, as the default checks assume component-specific structures found in component-template.tsx.

What exit codes does the validator return?

The script returns exit code 0 when all checks pass (Props interface exists, no hex colors found) and exit code 1 when any validation fails or when the file cannot be parsed. These standard exit codes integrate seamlessly with shell scripting, CI systems, and Git hooks to control workflow execution based on validation results.

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