Philosophy

chowbea-axios is opinionated by design. This page explains the thinking behind those opinions—and the trade-offs you're accepting when you adopt the tool.

Server Types as Source of Truth

When you use ServerModel<"UserDto">, you're intentionally coupling your frontend types to the backend. This isn't a bug—it's the point.

Your API returns a specific shape. Your query layer should reflect that shape exactly.

type User = ServerModel<"UserDto">;
type Business = ServerModel<"BusinessDto">;

These types come directly from your OpenAPI spec. They update automatically when the spec changes. You never write them by hand.

What this gives you:

When UI Needs Different Shapes

Sometimes your UI genuinely needs a different shape than what the server returns. When that happens, create explicit UI types with transformers:

// Server type (from OpenAPI spec)
type User = ServerModel<"UserDto">;

// UI-specific type (defined in your app)
type UserCardUI = {
  id: string;
  displayName: string;
  avatarUrl?: string;
};

// Explicit transformation at the boundary
const toUserCardUI = (user: User): UserCardUI => ({
  id: user.id,
  displayName: `${user.firstName} ${user.lastName}`,
  avatarUrl: user.profile?.avatar,
});

This pattern keeps your boundaries clear:

The rule: Start with server types everywhere. Add a mapping layer only when you genuinely need it.

Built for Builders Who Own Their Stack

If you're a solo developer, indie hacker, or vibe coder who builds their own backend—chowbea-axios was made for you.

Here's why: you control both sides of the contract.

When you own the backend (NestJS, Express, FastAPI, whatever) and the frontend, tight coupling isn't a risk—it's a superpower.

• Instant type sync — Change an endpoint, regenerate, see TypeScript errors immediately
• No coordination overhead — No waiting for another team to update types or documentation
• Rapid iteration — Ship features fast without maintaining two sets of type definitions
• AI-friendly structure — The opinionated patterns help AI tools generate consistent code instead of spaghetti

The workflow is simple:

1. Change your backend endpoint
2. chowbea-axios regenerates types (watch mode)
3. TypeScript shows you what broke
4. Fix it before it ships

No manual type updates. No "oops, forgot to sync the types" bugs in production.

Staying Fast Without Losing Structure

The trap with moving fast is losing structure. Codebases turn into spaghetti. Types drift. AI tools start generating inconsistent patterns.

chowbea-axios gives you guardrails:

• Generated types can't drift — They come from your spec, period
• Consistent patterns — Same file structure, same error handling, everywhere
• Watch mode — Types update automatically as you iterate on your backend

You get to move fast and keep your codebase clean. That's the win.

Trade-offs to Be Aware Of

Every tool makes trade-offs. Here's what you're signing up for—and why we think they're worth it.

Opinionated Design

The tool makes decisions for you: file structure, error handling pattern, client organization. You can't configure your way out of these choices.

The upside: Convention over configuration. Less bikeshedding. Faster onboarding. New team members know exactly where things live.

Server DTOs First

Your components start by consuming server types directly. If your UI needs different shapes, you add a mapping layer yourself.

The upside: You avoid premature abstraction. Most teams discover they need fewer transformations than they expected.

Hands-Off Generated Code

The _generated/ folder gets overwritten on every generation. Your customizations must go in the editable files only.

The upside: You never have merge conflicts with generated code. Regeneration is always safe.

Is This Right for You?

chowbea-axios works best when:

• Your OpenAPI spec is accurate and kept up-to-date
• You want "it just stays synced" behavior without manual type maintenance
• You value convention and structure over maximum flexibility
• You're okay with the Result-based error pattern
• You own your backend (or trust the team that does)

It might not be the best fit if:

• You need extensive customization of the generated output
• Your UI shapes differ significantly from your API responses
• You're consuming an external API you don't control