When is a TypeScript File Too Large? Lessons from Claude Code's 800KB main.tsx
The 800KB TypeScript File
When I looked at the leaked Claude Code source, one thing caught my attention immediately:
main.tsx: 803,924 bytes (4,683 lines)print-utility.ts: 5,594 linesmessage-handler.ts: 5,512 linesSix files exceed 4,000 lines each. The main entry point is nearly a megabyte of TypeScript.
I had two reactions:
- “This is technical debt waiting to happen”
- “Wait, it works for them”
This got me thinking: when is a TypeScript file actually too large?
The Standard Advice
Most style guides say something like:
- “Files should be under 200 lines”
- “Maximum 500 lines per file”
- “Keep it small enough to understand in one sitting”
Robert C. Martin suggests files should be small enough that you can see the whole thing without scrolling. That’s maybe 50-100 lines.
But here’s the problem: these numbers are arbitrary. They don’t account for team size, project type, or code complexity.
Why Claude Code Can Have 4,000-Line Files
Claude Code is built by a small, tight-knit team at Anthropic. I estimate 2-5 developers work on it actively.
For this context:
┌──────────────┬─────────────────┐│ Team Size │ File Threshold │├──────────────┼─────────────────┤│ 1-3 devs │ 500-1,000 lines ││ 4-10 devs │ 300-500 lines ││ 11-20 devs │ 200-300 lines ││ 20+ devs │ 100-200 lines │└──────────────┴─────────────────┘Why does team size matter so much?
Communication overhead. In a 2-person team, you can walk over and ask “where’s the function that handles messages?” In a 20-person team, that question gets asked 100 times per week.
Merge conflicts. With 20 developers, if everyone touches the same 4,000-line file, you get constant conflicts. With 2 developers, this rarely happens.
Code review fatigue. A 500-line diff is intimidating. Reviewers skim. Bugs slip through. But with 2 developers who know every line of the codebase, a 500-line diff is still reviewable.
When Large Files Become Unmaintainable
I’ve worked on projects where large files became real problems. Here are the warning signs I’ve seen:
1. Search frequency
If I’m constantly searching for “where is that function?” in the same file, that file is too large for me. I should be able to find things by scanning, not by grep.
2. Review fatigue
When I see a PR with 400+ lines changed in a single file, I sigh. I know I’ll need 30 minutes to review it properly. So I put it off. Or I skim.
3. Merge conflicts
$ git pullCONFLICT (content): Merge conflict in src/services/UserService.tsAutomatic merge failed; fix conflicts and then commit the result.If I see this weekly for the same file, that file is too large.
4. New hire struggles
A new developer asks “where do I add this feature?” and the answer is “it depends, look at the 3,000-line file first.” That’s a smell.
5. IDE performance
When opening a file takes 5 seconds and syntax highlighting flickers, the file has grown beyond what my tools handle well.
Strategic File Splitting Patterns
When you decide to split, here are patterns that work:
Feature Modules
src/├── features/│ ├── auth/│ │ ├── components/│ │ ├── hooks/│ │ ├── utils/│ │ └── index.ts│ ├── dashboard/│ └── settings/└── shared/Each feature has its own directory. The index.ts exports a clean public API.
Domain-Driven Splitting
src/├── user/│ ├── UserService.ts│ ├── UserRepository.ts│ └── UserTypes.ts├── order/│ ├── OrderService.ts│ ├── OrderProcessor.ts│ └── OrderTypes.ts└── payment/Each domain gets its own directory. Related code stays together.
Utility Separation
export function truncate(str: string, length: number): string { if (str.length <= length) return str; return str.slice(0, length - 3) + '...';}
export function capitalize(str: string): string { return str.charAt(0).toUpperCase() + str.slice(1);}Pure utilities move to separate files. They’re easy to test and easy to find.
When NOT to Split
I’ve also seen teams split files prematurely or incorrectly. Here’s when splitting makes things worse:
Premature splitting
A 200-line file with three functions doesn’t need to become three files. You’ve added import complexity for no benefit.
Splitting by type
src/├── components/│ ├── Button.tsx│ ├── Card.tsx│ └── Modal.tsx├── hooks/│ ├── useAuth.ts│ └── useTheme.ts└── utils/This organizes by technical category. But when I’m working on a feature, I need to touch all three directories. Feature-based organization is usually better.
Over-abstracting
Creating a “generic reusable component” when you only have one use case. Now you have abstraction overhead for no reason.
Ignoring team dynamics
Splitting a file that only one person edits anyway. The split adds complexity without reducing communication overhead.
Signals to Keep the File Together
Sometimes a large file is the right choice:
Tight coupling
If functions A, B, and C always change together, keeping them in one file makes sense. Splitting them means touching multiple files for every change.
Single owner
If one developer owns the entire module and others rarely touch it, the coordination cost of a large file is zero.
Frequent cross-editing
If a typical change touches 60%+ of the functions in a file, splitting will increase your workload.
Stable codebase
If the file hasn’t changed significantly in 6 months, maybe it doesn’t matter how large it is.
The Reddit Discussion
The leaked Claude Code source sparked interesting reactions:
"This is normal for complex CLI tools. Navigation is faster for one team."- pro-large-files
"How do you find anything? This looks like technical debt."- anti-large-files
"Context matters. For Anthropic's team size, this might be right."- middle-groundI agree with the middle-ground view. The anti-large-files reaction assumes enterprise dynamics: multiple teams, rotating developers, strict code review processes. But Claude Code isn’t that.
A Practical Decision Framework
Before splitting a large file, I ask these questions:
- Who maintains this? One person? One team? Multiple teams?
- How often does it change? Daily? Weekly? Monthly?
- What’s our team size? 2? 10? 50?
- Is current structure hurting productivity? Be honest. If no, leave it.
- What’s the cost of splitting? Time, risk, learning curve.
┌─────────────────────────────────────┐│ Is the file causing problems? ││ (conflicts, confusion, slow review) │└──────────────────┬──────────────────┘ │ ┌────────┴────────┐ ▼ ▼ Yes No │ │ ▼ ▼┌─────────────────┐ ┌─────────────────┐│ Team size > 5? │ │ Leave it alone │└────────┬────────┘ └─────────────────┘ │ ┌─────┴─────┐ ▼ ▼ Yes No │ │ ▼ ▼┌────────┐ ┌────────┐│ Split │ │ Can ││ by │ │ wait. ││ feature │ │ Focus ││ or │ │ on real││ domain │ │ issues.│└────────┘ └────────┘Summary
In this post, I examined when TypeScript files become too large. The key point is that file size limits depend on team context, not arbitrary line counts.
Claude Code’s 4,000-line files work for a 2-5 person team with strong ownership. The same files would be a disaster in a 50-person enterprise.
The rule isn’t “files must be small.” The rule is “files must be maintainable by your team.” Before splitting, ask: who maintains this? How often does it change? What’s our team size? Is the current approach actually hurting productivity?
If the answers don’t reveal a problem, your large file might be just fine.
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
- 👨💻 Clean Code by Robert C. Martin
- 👨💻 Monolith vs Microservices - Perforce
- 👨💻 Reddit Discussion: Claude Code Leaked Source
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments