Choosing the Right File Structure for Your Project

Swagger to TanStack offers three different file structures: split, group, and group-hooks. Choosing the right one can significantly impact your development experience and code maintainability.

The Three Structures Explained

1. group-hooks (Recommended)

Organizes code by feature with queries and mutations in a single hooks file:

2. group

Separates queries and mutations into different files:

3. split

Each endpoint gets its own file:

When to Use Each Structure

Use group-hooks when:

• You want the simplest, most maintainable structure
• Your team prefers feature-based organization
• You have small to medium-sized APIs (10-50 endpoints per tag)
• You want faster imports and better tree-shaking

Use group when:

• You want clear separation between reads and writes
• Your team follows strict read/write patterns
• You need different access controls for queries vs mutations

Use split when:

• You have very large APIs (100+ endpoints)
• You need maximum modularity and isolation
• Multiple teams work on different endpoints
• You want to lazy-load specific endpoints

Performance Comparison

Migration Between Structures

You can change structure at any time by regenerating:

Recommendation

For most projects, group-hooks provides the best balance of simplicity, performance, and maintainability. Start there and only switch if you have specific needs for separation or extreme modularity.