webamp/docs/typescript-checking.md

TypeScript Checking Convention

This document describes the TypeScript checking convention established for the Webamp monorepo.

Current Status

Each TypeScript-enabled package in the monorepo now has a consistent type-check script that performs type checking without emitting files.

Progress: 4 out of 5 packages now passing! 🎉

Package Status

✅ Passing Packages

• webamp: Clean TypeScript compilation
• ani-cursor: Clean TypeScript compilation
• skin-database: Clean TypeScript compilation (fixed JSZip types, Jest types, and Buffer compatibility issues)
• webamp-docs: Clean TypeScript compilation

❌ Failing Packages (Need fixes)

• webamp-modern: 390+ TypeScript errors (conflicting type definitions, target issues)

Convention

Package-level Scripts

Each TypeScript package should have:

{
  "scripts": {
    "type-check": "tsc --noEmit"
  }
}

Important: Always use tsc --noEmit to avoid accidentally creating JavaScript files in source directories.

Root-level Script

The root package.json contains a centralized script that runs type checking for all currently passing packages:

{
  "scripts": {
    "type-check": "pnpm --filter webamp type-check && pnpm --filter ani-cursor type-check && pnpm --filter skin-database type-check && pnpm --filter webamp-docs type-check"
  }
}

CI Integration

The CI workflow (.github/workflows/ci.yml) runs the centralized type-check command:

- name: Lint
  run: |
    pnpm lint
    pnpm type-check

Adding New Packages

When adding a new TypeScript package to the type-check convention:

1. Add the type-check script to the package's package.json
2. Ensure the package passes type checking: pnpm --filter <package-name> type-check
3. Add the package to the root type-check script
4. Test the full suite: pnpm type-check

Fixing Failing Packages

Common Issues

1. Missing Jest types (Fixed in skin-database):

   • Install @types/jest and configure proper Jest setup
   • Ensure test files are properly configured

2. Missing package types (Fixed in skin-database):

   • Install missing dependencies like jszip, react-redux, express
   • Install corresponding @types/ packages where needed
   • Note: Some packages like JSZip provide their own types

3. Buffer compatibility issues (Fixed in skin-database):

   • Newer TypeScript versions require explicit casting for fs.writeFileSync
   • Use new Uint8Array(buffer) instead of raw Buffer objects

4. Conflicting type definitions (webamp-modern):

   • Multiple versions of @types/node causing conflicts
   • Target configuration issues (ES5 vs ES2015+)
   • Dependency type mismatches

Recommended Fix Strategy

1. Start with packages that have fewer errors
2. Focus on one category of errors at a time
3. Update TypeScript compiler target if needed (many errors require ES2015+)
4. Ensure proper dependency management to avoid type conflicts

Benefits

• Consistency: All packages use the same type-checking approach
• CI Integration: Automatic type checking prevents type errors from being merged
• Developer Experience: Simple pnpm type-check command for full project validation
• Incremental: Only includes packages that currently pass, allowing gradual improvement

Future Work

• Fix remaining packages to include them in the type-check suite
• Consider stricter TypeScript configurations for better type safety
• Investigate automated type checking in development workflow