These tenets define the core principles that guide every TanStack library and product. They serve as both a quality bar for what developers can expect from our tools and as a reference for evaluating contributions, features, and ideas.
These tenets complement our organizational ethos, which covers our business values and independence. Together, they ensure that TanStack remains committed to building tools that make the web better for developers—on your terms, without compromise.
1. Open, Independent, Technology-Agnostic
Every TanStack library starts with a provider-agnostic core, ensuring that developers are never locked into a specific vendor, platform, or ecosystem. Integrations are layered on top as optional adapters—never as the foundation.
- Neutral core, optional integrations: Every TanStack library starts with a provider-agnostic core (framework, runtime, vendor, or service), with integrations layered on top as optional adapters—never as the foundation.
- Portability over deep lock-in: We design APIs so that swapping providers, platforms, or runtimes is feasible without rewriting business logic; any provider-specific behavior is clearly cordoned off.
- Uniform abstractions across providers: Where multiple vendors/services solve similar problems, we provide a consistent abstraction that makes them interchangeable from the developer's perspective.
- We don't chase every niche feature: We intentionally avoid modeling every bespoke feature of every vendor; we focus on the shared, high-leverage capabilities that most teams actually need.
- Graceful degradation, not fragmentation: When a provider offers extra capabilities, they plug into extension points or optional layers rather than fragmenting the core abstraction or dictating its shape.
What this rules out:
- Vendor-biased APIs or partner-driven features in core
- Contributions that introduce platform bias or "we're all-in on X vendor" assumptions
- Features that require committing to a specific cloud provider or deployment model
2. Composable, Platform-Aligned Primitives
We build focused, composable primitives that embrace the platform rather than hiding it. Every library should be adoptable incrementally, without requiring rewrites or creating hard dependencies on other TanStack tools.
- Primitives before frameworks: We ship focused, composable building blocks rather than all-inclusive "one framework to rule them all" abstractions.
- Embrace the platform: We leverage the web, HTTP, JS/TS, and servers instead of hiding them behind opaque layers of magic.
- Progressive adoption: Every library should be adoptable one piece at a time, without rewrites or hard coupling to the rest of TanStack.
- Escape hatches by design: It must always be possible to drop down a level, integrate with existing systems, or bypass our abstractions when necessary.
What this rules out:
- Designs that require full rewrites or "all-in" commitments
- Heavy global singletons or hard dependencies between TanStack libraries
- Abstractions that hide platform capabilities without clear escape routes
3. Pragmatic, Production-Grade Quality
We design around real-world production use-cases, edge cases, and long-lived applications—not just happy-path demos. Performance and scalability are requirements, not nice-to-haves.
- Real products as the bar: We design around real-world workloads, edge cases, and long-lived apps—not just happy-path demos.
- "Ship today" quality: Features are not done until we'd be comfortable running them in our own revenue-critical applications.
- Performance and scale as requirements: Rendering, caching, and network behavior must hold up under scale; performance is not a nice-to-have.
- DX that earns its cost: API ergonomics, tooling, and docs should measurably improve developer outcomes, not add clever ceremony.
What this rules out:
- Demo-only features that don't hold up under real-world load
- Magic that's impossible to debug or reason about when something goes wrong
- Changes that optimize for benchmarks over real-world reliability
4. Predictable, Explicit, Type-Safe Behavior
We minimize magic and maximize clarity. State, side effects, and data flow should be understandable from code, not guessed from hidden behavior. Type safety should guide correct usage without drowning users in generics.
- Minimal magic, maximum clarity: State, side effects, and data flow must be understandable from code, not guessed from hidden behavior.
- Explicit over implicit: Important behaviors are explicit in APIs and configuration, with surprising defaults treated as a bug.
- Type safety as leverage, not dogma: TypeScript support should guide correct use and catch real bugs without drowning users in generics.
- Stable APIs and migrations: We evolve carefully, with clear changelogs and migration paths; breakage for style or hype is unacceptable.
What this rules out:
- Hidden global state or surprising side effects that aren't obvious from the API
- Backwards-incompatible API churn without clear migration paths
- Type signatures that are technically correct but unusable in practice
How to Use These Tenets
These tenets serve multiple purposes for different audiences:
- For developers evaluating TanStack: These tenets define what you can expect from our libraries—quality, portability, and a commitment to your freedom to compose and deploy however you see fit.
- For contributors: When proposing features or changes, consider how they align with these tenets. If your idea conflicts with a tenet, explicitly address why and how the conflict is justified.
- For maintainers and reviewers: Use these tenets as a checklist when evaluating PRs, feature requests, and architectural decisions. If something threatens a tenet, it needs strong justification or should be rejected.
- For partners: These tenets ensure that our libraries remain neutral and developer-focused. Partner integrations must respect these principles and cannot bias core APIs toward specific platforms or vendors.
These tenets work alongside our organizational ethos, which covers our business independence, sustainability, and commitment to the open web. Together, they ensure TanStack remains true to its mission: building tools that make the web better for developers, on your terms.
