BUILD-TROUBLESHOOTING.md•5.41 kB
# Build Troubleshooting Guide
## Issue: TypeScript Compilation Errors
### Problem
When running `build.bat` or `npm run build`, you might encounter TypeScript errors.
---
## ✅ Fixed Issue: test-client.ts Type Errors
**Status:** RESOLVED on 2024-11-13
**Error Messages:**
```
src/test-client.ts:76:10 - error TS18046: 'health' is of type 'unknown'.
src/test-client.ts:89:26 - error TS18046: 'histResult' is of type 'unknown'.
(8 similar errors)
```
**Root Cause:**
- API responses were not properly typed
- TypeScript strict mode couldn't infer response types
**Solution Applied:**
1. Added interface definitions for API responses:
- `HealthResponse`
- `HistoricalQuotesResponse`
- `EvaluationResponse`
- `ReviewResponse`
2. Added type assertions to API calls:
```typescript
const health = await callAPI('/health') as HealthResponse;
const histResult = await callAPI('/mcp/utility/historicalQuotes') as HistoricalQuotesResponse;
const result = await callAPI('/mcp/invoke/evaluateRfpAndDraftQuote', {...}) as EvaluationResponse;
const reviewResult = await callAPI('/mcp/utility/formatReview', {...}) as ReviewResponse;
```
3. Added proper type import:
```typescript
import { QuoteEvaluationResult } from './types';
```
**Result:** All 8 TypeScript errors resolved. Build now completes successfully.
---
## Common Build Issues & Solutions
### Issue 1: "Cannot find module 'express'"
**Cause:** Dependencies not installed
**Solution:**
```bash
npm install
# or run setup.bat option [1]
```
### Issue 2: "tsc is not recognized"
**Cause:** TypeScript not installed globally
**Solution:**
```bash
npm install
# TypeScript is in devDependencies, will be installed locally
```
### Issue 3: Build succeeds but dist/ folder empty
**Cause:** TypeScript config issue or compilation errors
**Solution:**
1. Check `tsconfig.json` exists
2. Verify `outDir` is set to `./dist`
3. Look for any error messages in console
### Issue 4: "Module not found" after building
**Cause:** Missing dependencies or incorrect imports
**Solution:**
```bash
# Clean install
rm -rf node_modules package-lock.json
npm install
npm run build
```
### Issue 5: Type errors in your own code
**Cause:** TypeScript strict mode enabled
**Solution Options:**
1. **Preferred:** Add proper types to your code
2. **Quick fix:** Use type assertions (`as Type`)
3. **Last resort:** Disable strict mode in `tsconfig.json` (not recommended)
---
## Verification Steps
After fixing build issues, verify everything works:
### 1. Build Successfully
```bash
npm run build
```
Should complete with no errors and create `dist/` folder.
### 2. Check Dist Folder
```bash
dir dist
# or
ls dist/
```
Should contain compiled `.js` files matching your `.ts` source files.
### 3. Test Production Start
```bash
npm start
# or run start-prod.bat
```
Server should start on port 3789.
### 4. Run Tests
```bash
# Start server first, then:
npx ts-node src/test-client.ts
# or run quick-test.bat
```
---
## TypeScript Configuration
Our `tsconfig.json` settings:
```json
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
```
**Key settings:**
- `strict: true` - Enables all strict type checking
- `outDir: ./dist` - Where compiled files go
- `rootDir: ./src` - Source files location
---
## Getting Help
### Check Logs
Look at console output for specific error messages.
### Common Error Patterns
**"Cannot find name 'X'"**
- Missing import
- Typo in variable name
- Need to declare type
**"Type 'X' is not assignable to type 'Y'"**
- Type mismatch
- Need type assertion or conversion
- Check interface definitions
**"Property 'X' does not exist on type 'Y'"**
- Wrong type assumed
- Need to update interface
- Use optional chaining (`?.`)
### Still Having Issues?
1. Delete `dist/` folder and rebuild
2. Delete `node_modules/` and reinstall
3. Check for typos in recent changes
4. Compare with working version (git diff)
5. Check Node.js version: `node --version` (need v16+)
---
## Prevention Tips
### Before Committing Code:
1. ✅ Run `npm run build` to check for errors
2. ✅ Add proper types to new functions
3. ✅ Import types from existing interfaces
4. ✅ Use TypeScript's IntelliSense suggestions
5. ✅ Test in both dev and prod modes
### Best Practices:
- Define interfaces for all API responses
- Use type imports instead of `any`
- Enable strict mode in tsconfig
- Add JSDoc comments for complex types
- Use type guards for runtime checks
---
## Quick Reference
### Build Commands
```bash
npm run build # Compile TypeScript
npm run dev # Development mode (auto-reload)
npm start # Production mode (needs build first)
npx tsc # Direct TypeScript compiler
npx tsc --noEmit # Check types without compiling
```
### Batch File Commands
```bash
build.bat # Full rebuild
start-dev.bat # Dev server
start-prod.bat # Prod server (builds first if needed)
setup.bat # Full setup including build
```
---
**Last Updated:** 2024-11-13
**Status:** All known build issues resolved ✅