Two Cultures, One Craft: Lessons From Authoring Modern Open-Source Libraries
Modern open-source authoring is rarely a single, repeatable formula. Community-driven projects and company-backed efforts each come with distinct rhythms, incentives, and constraints. Drawing from experience building TresJS as a community project and working on the SDK ecosystem at Storyblok, the useful lessons are often about navigating those differences rather than avoiding them.
From Personal Itch to Community Project
Many open-source libraries begin as a solution to a personal problem. For TresJS, the initial goal was simply adding 3D to a personal Nuxt portfolio. At the time, VueJS lacked a maintained, feature-rich alternative to React Three Fiber. The library launched, and the portfolio remained unfinished—but the project took on a life of its own.
As a project gains traction, its focus must evolve. Idea velocity rises as users file issues and propose pull requests. TresJS, for example, accumulated roughly 531 issues and 936 pull requests, with about 90% of those PRs eventually merged. The challenge shifts from building initial momentum to protecting the original vision. That often means declining genuinely good ideas to keep scope and purpose intact.
Sustained contributors naturally become core team members, distributing responsibility for the growing ecosystem. With that growth, delegation becomes essential. Empowering contributors means providing the tools they need to work effectively—clear CI workflows, sensible conventions, and clean package structure—so that new collaboration can focus on advancing the project rather than deciphering it.
The Company-Driven Counterweight
At Storyblok, open source serves to make a commercial product as easy to adopt as possible across frameworks. The goal is consistency: the same developer experience whether a customer is using Vue, React, or another flavor. That objective comes with its own set of trade-offs.
Resource availability is the standout advantage of company-driven OSS. Dedicated engineering time, reliable infrastructure, and access to internal design, QA, and product teams are often out of reach for individual maintainers. But that support is not without friction. Legacy codebases are frequent obstacles—usually written by engineers unfamiliar with open-source conventions. Aligning those projects with community standards takes substantial refactoring before best practices can take hold.
Expectation management sits close behind. The community often wants fast fixes and features, while a company must balance requests against broader priorities like stability, scalability, and strategic integrations. Clear communication and disciplined prioritization keep both sides aligned, even when wishes outpace timelines.
Borrowing Across the Spectrum
The line between community and company projects is not a boundary; it is a spectrum that most projects move along. TresJS started fully community-driven but, over time, adopted more structured decision-making as the core team defined shared goals and vision to support scalability.
The reverse direction can be just as productive. Work on TresJS filtered practical innovations into Storyblok’s ecosystem. For example, adopting pnpm workspaces for dependency management improved dev workflows like playgrounds and e2e testing—a pattern later adapted for Storyblok’s multi-package setup. Similar momentum pushed the migration from Jest to Vitest for performance and developer experience, and the shift from Prettier to ESLint's v9 flat configuration with auto-fix, consolidating linting and formatting into a single workflow.
CI modernization also moved across the spectrum. TresJS’s release pipeline was reworked from a single monolith into distinct steps for linting, testing, and building. That modular approach became a blueprint for Storyblok's own pipelines. The continuous release practice inspired by pkg.pr.new also found a home, enabling faster delivery of incremental changes and real-world package testing before merging pull requests.
Some of those benefits flowed back toward TresJS. Mature Storyblok workflows informed the integration of Dependabot for dependency upkeep and auto-merge for minor updates, reducing manual overhead. An automatic release pipeline built on GitHub Actions, modeled on Storyblok’s practices, made releases more reliable for the TresJS ecosystem.
Handling Breaking Change
Hype-driven development may be engaging, but it is risky when building reliable software meant for enterprise use. Users expect current tooling, yet stability and compatibility are not optional. Semantic versioning helps structure expectations, but it is not a substitute for discipline.
The core work is balancing innovation with stability, and breaking an existing API is rarely avoidable. The lesson worth repeating is the value of clear communication. Changelogs, migration guides, and deprecation warnings are not editorial overhead; they are the mechanisms that let users move forward with confidence.
Take @storyblok/richtext, a library for rich-text processing that now sees roughly 172k monthly downloads. Transitioning users from the prior rich-text implementation to this new library—one that would become a dependency of the foundational JS SDK and then propagate to every framework SDK—demanded a plan measured in months. The rollout used a retro-compatible period before the major release, paired with communication campaigns and thorough documentation to minimize disruption.
Mistakes still happened. At points during that transition, updates lagged or documentation fell out of sync, creating understandable confusion in the community. Responding with timely support on GitHub and Discord proved as important as the original migration plan. Even with semantic versioning, modular architecture, and careful forethought, OSS authoring is never perfectly executed—that reality is less a failure than a condition of the work.
