Preserving User Modifications
Learn how swagger-to-tanstack intelligently detects and preserves your custom modifications to prevent accidental overwrites.
update and watch commands automatically preserve your modifications.How It Works
When you use --preserve-modified flag or the update command, swagger-to-tanstack analyzes your files before overwriting them. If modifications are detected, the file is skipped.
Detection Methods
1. Comment Markers (Explicit)
Add special comments to explicitly mark a file as modified. This is the most reliable method.
Supported Markers
Any of these comments will protect your file:
Single-line comments:
Multi-line comments:
2. Heuristic Detection (Automatic)
Even without explicit markers, the tool detects probable modifications through heuristics:
Too Many Imports
Files with more than 10 imports are considered modified (you probably added custom dependencies).
Custom Exports
Files with exports starting with "custom" are automatically preserved.
Usage Examples
With update Command
The update command ALWAYS preserves modifications by default:
With generate Command
Use the --preserve-modified flag:
With watch Command
Watch mode automatically preserves modifications:
Best Practices
✅ DO: Use Comment Markers
Always add a marker comment when you modify generated files. It's explicit and reliable.
✅ DO: Use update Command
When you have custom modifications, always use update instead of generate.
✅ DO: Create Separate Custom Files
For extensive customizations, create separate files:
⚠️ AVOID: Modifying Without Markers
While heuristics work, they're not 100% reliable. Always use comment markers for safety.
❌ DON'T: Rely Only on Heuristics
Small modifications might not trigger heuristics. Use explicit markers.
Console Output
When a file is skipped due to modifications, you'll see:
Force Regeneration
If you want to force regeneration and overwrite everything:
Without --preserve-modified, all files will be overwritten, regardless of modifications.
generate without --preserve-modified will overwrite ALL files, including your modifications. Use version control!Quick Reference
| Command | Preserves Modifications | Use Case |
|---|---|---|
generate | ❌ No (overwrites all) | Fresh generation, first time |
generate --preserve-modified | ✅ Yes | Regenerate with safety |
update | ✅ Yes (always) | Update after spec changes |
watch | ✅ Yes (always) | Development workflow |
Summary
- - Add comment markers (
// CUSTOM,// MODIFIED, etc.) to your modified files - - Use
updatecommand when you have modifications - - Use
watchmode during development (safe by default) - - Create separate custom files for extensive modifications
- - Be cautious with
generatecommand - it overwrites everything - - Always use version control (Git) to track changes