​

🔍 Troubleshooting

​

Common Issues

​

”Cannot find module” errors

npx @anonymous-dev/firetype generate --input=./schemas --output=./types

​

Schema validation errors

• Ensure schema files export a schema constant: export const schema = z.object({...})
• Check that schema files are named exactly schema.ts
• Verify the directory structure matches your Firestore collections

​

CLI not found

• Use npx @anonymous-dev/firetype instead of firetype
• Check that the package is installed: npm list @anonymous-dev/firetype
• For local installation, ensure your PATH includes node_modules/.bin

​

Type errors in generated code

• Update to the latest version: npm update @anonymous-dev/firetype
• Regenerate types after schema changes
• Check that your Zod schemas are valid

​

Validation not working

// Enable validation
const collectionRef = firetype.users.getCollectionRef(true);
const documentRef = firetype.users.getDocumentRef('id', true);

​

Import errors

• Check the output path in your generation command
• Ensure the generated file exists: ls types/index.ts
• Use correct relative imports: import { createFireTypeAdmin } from "../types"

​

Schema Issues

​

Schema not generating types

1. File naming: Ensure files are named exactly schema.ts
2. Export syntax: Must be export const schema = z.object({...})
3. Directory structure: Should match your Firestore collection structure
4. CLI paths: Verify --input path points to the correct directory

✅ Correct:
schemas/database/users/schema.ts
export const schema = z.object({...})

❌ Incorrect:
schemas/database/users/userSchema.ts
export const userSchema = z.object({...})

​

Type safety not working

1. Regenerate types after schema changes
2. Check Zod schema validity - invalid schemas may generate any types
3. Verify import paths in generated file
4. Update TypeScript to latest version

​

Complex schema types

// ✅ Correct discriminated union
export const schema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('a'), value: z.string() }),
  z.object({ type: z.literal('b'), value: z.number() }),
]);

// ❌ Incorrect - missing discriminator
export const schema = z.union([
  z.object({ type: z.literal('a'), value: z.string() }),
  z.object({ type: z.literal('b'), value: z.number() }),
]);

​

Runtime Issues

​

Validation errors not descriptive

try {
  await collectionRef.add(data);
} catch (error) {
  if (error instanceof z.ZodError) {
    const formattedErrors = error.errors.map((err) => ({
      field: err.path.join('.'),
      code: err.code,
      message: err.message,
      received: err.received,
    }));
    console.error('Validation failed:', formattedErrors);
  }
}

​

Firestore permission errors

1. Check Firestore rules - ensure rules allow the operations
2. Verify authentication - user must be authenticated for secured operations
3. Test with admin SDK - bypasses security rules for testing

​

Performance issues

1. Disable validation in production:
   const collectionRef = firetype.users.getCollectionRef(false); // No validation
   
2. Use batch operations for multiple writes:
   const batch = db.batch();
   // Add multiple operations to batch
   await batch.commit();
   
3. Optimize queries with proper indexes

​

CLI Issues

​

Command not found in CI/CD

1. Add to package.json:
   {
     "scripts": {
       "generate-types": "firetype generate --input=./schemas --output=./types"
     },
     "devDependencies": {
       "@anonymous-dev/firetype": "^1.2.0"
     }
   }
   
2. Use npm script: npm run generate-types
3. Cache node_modules in CI to avoid reinstallation

​

Debug mode

DEBUG=firetype npx @anonymous-dev/firetype generate --input=./schemas --output=./types

​

Getting Help

​

Issue Reporting

• Version: Firetype version (npm list @anonymous-dev/firetype)
• Environment: Node.js, TypeScript, Firebase SDK versions
• Steps to reproduce: Minimal code example
• Expected vs actual behavior
• Schema structure (anonymized)

​

Minimal Reproduction

mkdir firetype-debug
cd firetype-debug
npm init -y
npm install @anonymous-dev/firetype zod firebase-admin
mkdir schemas
# Add minimal schema and reproduction code

​

Community Support

• GitHub Issues: For bugs and feature requests
• GitHub Discussions: For questions and general help
• Stack Overflow: Tag with firetype and firestore

​

Advanced Debugging

​

Type Inspection

// Check what types are generated
type UserType = Parameters<typeof createFireTypeAdmin>[0] extends Firestore
  ? Awaited<
      ReturnType<ReturnType<typeof createFireTypeAdmin>['users']['getCollectionRef']>
    >['_documentType']
  : never;

​

Runtime Type Checking

import { z } from 'zod';

// Debug helper
function validateSchema<T>(schema: z.ZodSchema<T>, data: unknown): T {
  try {
    return schema.parse(data);
  } catch (error) {
    console.error('Schema validation failed:', error);
    throw error;
  }
}

// Use in your operations
const validData = validateSchema(userSchema, inputData);
await collectionRef.add(validData);

​

Performance Profiling

const start = performance.now();
const result = await firetype.users.getCollectionRef().get();
const end = performance.now();
console.log(`Query took ${end - start} milliseconds`);