File Index Tracking

The proxy generator uses inline metadata comments in generated files to enable intelligent cleanup of stale files when commands or queries are removed from your codebase.

Overview

When you rename or delete a command or query from your backend, the corresponding TypeScript proxy file would normally be left behind. File tracking solves this by embedding metadata in each generated file and automatically removing orphaned files that are no longer needed.

How it Works

1. Metadata Comments: Each generated file includes a first-line comment with metadata:

   // @generated by Cratis. Source: MyApp.Commands.CreateOrder. Time: 2024-12-08T12:00:00.0000000Z. Hash: 1E9523083D8C6457F194B1CB045877E19BE204FB42F9F6E5574B77FC79B3ABDA

2. Orphan Detection: When running proxy generation, the generator scans all .ts files in the output directory:

   • Files with the @generated by Cratis marker that weren’t just generated are identified as orphaned
   • These orphaned files represent renamed or deleted types and are automatically removed

3. Index.ts Management: The generator intelligently maintains index.ts files:

   • Only includes exports for files that were actually generated
   • Preserves manual edits (comments, custom imports) in existing index.ts files
   • Automatically removes exports for deleted files
   • Deletes the index.ts file if the directory becomes empty

4. Legacy Support: The .cratis/GeneratedFileIndex.json file is still maintained for backwards compatibility but is superseded by the metadata-based approach.

Configuration

Disabling File Tracking

File tracking is enabled by default. To disable the metadata-based orphan detection, add the following to your .csproj:

<PropertyGroup>
    <CratisProxiesSkipFileIndexTracking>true</CratisProxiesSkipFileIndexTracking>
</PropertyGroup>

Note: This also disables the legacy .cratis/GeneratedFileIndex.json tracking.

Disabling Index Generation

If you prefer to manage index.ts files manually, you can disable automatic index generation:

<PropertyGroup>
    <CratisProxiesSkipIndexGeneration>true</CratisProxiesSkipIndexGeneration>
</PropertyGroup>

When index generation is disabled:

• No index.ts files are created or updated
• Existing index.ts files are left untouched
• You have full control over module exports

This is useful when:

• You have custom export logic in your index.ts files
• You want to selectively export certain files
• You’re integrating with existing manual code organization

CLI Usage

When using the proxy generator CLI directly, you can use these flags:

# Disable metadata-based file tracking
proxygenerator assembly.dll output-path --skip-file-index-tracking

# Disable index.ts generation
proxygenerator assembly.dll output-path --skip-index-generation

# Combine both options
proxygenerator assembly.dll output-path --skip-file-index-tracking --skip-index-generation

You can also specify a custom project directory for the legacy .cratis folder:

proxygenerator assembly.dll output-path --project-directory=/path/to/project

Version Control

Generated Files

The generated TypeScript files should be committed to version control:

commands/

# Do NOT ignore generated proxies - they're part of your frontend codebase
# queries/

Each file is self-documenting with its metadata comment, making it easy to understand:

• What generated the file
• When it was last generated
• The source C# type

Legacy Index File

The .cratis folder contains the legacy GeneratedFileIndex.json file. You can safely add it to .gitignore:

.cratis/

This is recommended because:

• The metadata-based tracking approach is now the primary mechanism
• The index is regenerated on each build
• Different developers may have different build outputs
• CI/CD pipelines will generate fresh indexes

Example Scenario

Consider the following scenario:

1. Initial State: You have CreateOrder.ts and UpdateOrder.ts in your commands folder, both with metadata comments.

2. Change: You rename UpdateOrder to ModifyOrder in your C# code.

3. Build: The proxy generator runs and:

   • Generates CreateOrder.ts with updated timestamp (unchanged logic)
   • Generates ModifyOrder.ts (new file with metadata)
   • Detects UpdateOrder.ts has the @generated marker but wasn’t just generated
   • Identifies it as orphaned and deletes it
   • Updates index.ts to export only CreateOrder and ModifyOrder

4. Result: Your frontend has clean, up-to-date proxies without stale files.

Index.ts File Management

The generator intelligently manages index.ts files to balance automation with flexibility:

Generated Files Only

The index.ts file only includes exports for files that were generated by the proxy generator:

// Manual comment or import you added
import { customHelper } from './helpers';

export * from './CreateOrder';
export * from './UpdateOrder';

If you manually create a file like CustomOrder.ts in the same directory, it won’t be automatically added to index.ts. This prevents the generator from managing files it didn’t create.

Preserving Manual Edits

Any non-export lines (comments, imports, etc.) in your index.ts are preserved:

// This comment will be kept across regenerations
import { something } from 'somewhere';

// Exports are managed automatically
export * from './CreateOrder';
export * from './UpdateOrder';

Disabling Index Generation

If you want complete control over index.ts files, disable automatic generation:

<PropertyGroup>
    <CratisProxiesSkipIndexGeneration>true</CratisProxiesSkipIndexGeneration>
</PropertyGroup>

Behavior When Disabled

When file tracking is disabled (CratisProxiesSkipFileIndexTracking=true):

• No metadata-based orphan detection occurs
• Stale files are not automatically cleaned up
• The legacy .cratis folder and index file are not created
• The CratisProxiesSkipOutputDeletion option becomes more important for managing old files
• You may need to manually delete old proxy files when renaming or removing backend code

When index generation is disabled (CratisProxiesSkipIndexGeneration=true):

• No index.ts files are created or modified
• Existing index.ts files are left completely untouched
• You have full manual control over module exports

Relationship with Output Deletion

Important: By default, the proxy generator deletes the entire output directory on every build (CratisProxiesSkipOutputDeletion=false), which means:

• File index tracking is not strictly necessary when using default settings
• All proxies are regenerated from scratch on every build
• No orphaned files can exist because the directory is wiped clean

File index tracking becomes essential when you enable incremental generation:

<PropertyGroup>
    <!-- Enable incremental generation -->
    <CratisProxiesSkipOutputDeletion>true</CratisProxiesSkipOutputDeletion>
    <!-- File tracking is now critical for cleanup -->
    <CratisProxiesSkipFileIndexTracking>false</CratisProxiesSkipFileIndexTracking>
</PropertyGroup>

With incremental generation enabled, file tracking automatically removes orphaned files when you rename or delete commands/queries, keeping your output directory clean without requiring a full deletion on every build.

Recommendation: Use CratisProxiesSkipOutputDeletion=true with file tracking enabled (default) when proxies are intertwined with your feature code. Use the default full deletion when proxies are in a dedicated folder. See Configuration - Output Deletion Behavior for more details.

Troubleshooting

Files Not Being Cleaned Up

1. Check if tracking is enabled: Ensure CratisProxiesSkipFileIndexTracking is not set to true.

2. Verify metadata comments: Check that generated files have the // @generated by Cratis comment on the first line.

3. Clean and rebuild: Delete the output folder and rebuild to regenerate all files with metadata.

Index.ts Not Updating

1. Check if index generation is enabled: Ensure CratisProxiesSkipIndexGeneration is not set to true.

2. Verify generated files: Only files generated by the proxy generator are included in index.ts.

3. Check for manual files: Files you created manually won’t be added to index.ts.

Legacy Index File Issues

If the legacy .cratis/GeneratedFileIndex.json file causes issues:

1. Delete the .cratis folder
2. Rebuild your project
3. The metadata-based tracking will handle cleanup automatically