A philosophy of simplicity, modularity, consistency, and craft.
Over the past several years, stdlib has grown from a small collection of utilities into a large, highly modular system for scientific computing in JavaScript and on the web. Along the way, we've made thousands of small decisions about APIs, naming, performance, package boundaries, and implementation strategies.
Individually, those decisions may seem minor. Collectively, they define the character of the project.
As the project has grown, it's become increasingly important to make those underlying principles explicit not just for maintainers, but for contributors and users who want to understand how and why stdlib is the way it is.
Today, we're introducing the Zen of stdlib: a set of guiding principles that capture the philosophy behind the project.
Why a "Zen"?
This is not a style guide.
It's not a checklist.
And it's not meant to be followed dogmatically.
Instead, the Zen is a distillation of experience: what has worked, what hasn't, and what tends to scale as a codebase and community grow. It exists to guide decisions, especially in ambiguous situations where there is no obviously "correct" answer.
If you've ever asked questions like:
- Should this be a new package or part of an existing one?
- Is this API too general?
- Should we add another option or compose existing functionality?
- Is this abstraction worth it?
The Zen is meant to help answer those questions.
The Zen of stdlib
Do one thing. Do it well.
Embrace radical modularity.
Favor composition over configuration.
Stability is a feature.
Make it obvious and predictable.
Don't be clever.
Complexity kills.
Push complexity up the stack.
If it's hard to explain, it's a bad idea.
If it's hard to test, it's a bad design.
Failure should be easy to diagnose.
Value consistency above all else.
Except when correctness, safety, or clarity demands otherwise.
Write it like C.
Be explicit. Avoid polymorphism by default.
Automate where it scales; stop where it obscures.
Code is read more than it is written.
Be kind to your future self.
Code is craft.
Tend to the garden.
Mistakes are infectious.
Fix them early.
Simple is beautiful.
What this means in practice
A few themes show up repeatedly throughout stdlib.
Radical modularity
If something can stand on its own, it should.
stdlib is intentionally composed of many small packages rather than a few large ones. This enables reuse, makes testing easier, and allows consumers to include only what they need. It also forces discipline, as each package must have a clear purpose and boundary.
Composition over configuration
We prefer simple building blocks over highly configurable interfaces.
Instead of adding more flags, options, and modes, we aim to provide small primitives that can be composed. This keeps individual APIs predictable and avoids combinatorial complexity.
Pushing complexity up the stack
Lower-level APIs should be simple, predictable, and easy to reason about.
More complex behavior, such as branching logic, multiple modes of operation, and orchestration, belongs in higher-level utilities built on top of those primitives. This separation is critical for both performance and maintainability.
Predictability and consistency
Users should not have to guess what an API does.
Naming conventions, argument ordering, and error behavior should be consistent across the entire project. Consistency reduces cognitive load and makes the system easier to learn and use.
Performance by design
"Write it like C" is less about language and more about mindset.
We favor predictable performance characteristics, monomorphic code paths, and explicit behavior. Hidden allocations, excessive polymorphism, and implicit work tend to introduce both performance and debugging challenges.
Maintainability as a first-class concern
Code is read far more often than it is written.
That reality drives many of the principles in the Zen: clarity over cleverness, simplicity over abstraction, and documentation that explains not just what the code does, but why.
A living document
The Zen of stdlib is not fixed.
As the project evolves, so will our understanding of what works and what doesn't. The Zen may change over time, but changes should be rare, deliberate, and grounded in experience.
For contributors
If you're contributing to stdlib, the Zen is a useful reference point when designing APIs or reviewing code.
It won't answer every question, but it should help you reason about trade-offs and make decisions that align with the broader direction of the project.
When in doubt: prefer simplicity, clarity, and consistency.
Closing
stdlib is an ongoing experiment in what scientific computing in JavaScript and on the web looks like when built around strong principles.
The Zen is an attempt to capture those principles so that the project can continue to grow without losing what makes it coherent.
As always, feedback is welcome.
stdlib is an open source software project dedicated to providing a comprehensive suite of robust, high-performance libraries to accelerate your project's development and give you peace of mind knowing that you're depending on expertly crafted, high-quality software.
If you've enjoyed this post, give us a star 🌟 on GitHub and consider supporting the project. Your contributions and continued support help ensure the project's long-term success and are greatly appreciated!