antoniandre/splitpanes: a Vue pane splitter with a bug list worth reading

Two packages, one repository, and they are not interchangeable

The install instructions are the first thing that tells you how this project is organised. For Vue 3 you take splitpanes, and for Vue 2 you take a different package under the same name with a dist-tag:

npm i splitpanes

and, for Vue 2,

npm i splitpanes@legacy

That is two separate builds from one source tree, not one build with a compatibility shim, and the release notes explain when the split happened. Version 3.0.0 is the entry that says Vue 3 support, with the instruction to use the legacy package for Vue 2, and two versions later, at 3.2.0, the internals were rewritten against the Composition API. So a Vue 2 project pinned to the legacy package is running code from before that rewrite and will not receive the same fixes unless the maintainer backports them, which the notes do not mention. That is the central trade in this project: broad version coverage, at the cost of two maintenance lines. If your application is on Vue 3, which is the current default, the decision is easy. If you are on Vue 2, you are choosing between a maintained package for a different framework version and a stagnant one, and the release notes are the only evidence about which state the legacy line is in.

Version 4.1.1 is a list of everything that went wrong

Most changelogs report features. This one reports failures, and it is the most useful document in the repository. Version 4.1.1 fixes a crash on fast drag, minimum and maximum size enforcement, a size jump, the cursor disappearing, a size of 0 being overridden, text selection in Firefox, a flash on initialisation, panel order, and nested transitions. Read that as a specification of how a splitter fails, because each item is a bug class rather than a typo. A crash on fast drag is an event-rate problem, where the pointer moves faster than the layout can settle. A size jump is a rounding or measurement problem, where the pane snaps when a computed value disagrees with the rendered one. The cursor disappearing is the classic document-level style side effect of starting a drag, where the component sets a cursor and never restores it. Text selection in Firefox is the same problem in a different costume, since a drag across a label selects it. Init flash is a paint-order issue, and panel order and nested transitions are the two you only discover when you nest splitters inside splitters, which is the feature that makes a splitter component hard. None of this is exotic, and all of it is the difference between a component that feels finished and one that needs a week.

What the earlier versions tell you about the API's stability

Going down the release notes is instructive because the API has moved repeatedly. At 4.0.0 the dblclick event was emitted and dblClickSplitter was renamed to maximizePanes, along with a refactor of the emitted events, so a major version bought a rename and an event cleanup. At 4.0.5 TypeScript definitions arrived, with null pointer safeguards and a fallthrough attributes fix, meaning for four minor versions before that the library had no types at all. Going back further, 2.0.0 fixed reactivity issues and 1.3.0 made slots reactive so panes could be added and removed on the fly. From 1.0.0 to 1.14.0 the entries are almost all features: default size, minimum size, maximum size, emitting events, watching slots, pushing other panes while dragging, persisting pane size after slot changes, double click to maximise, programmatic sizing, right-to-left support at 2.3.0. The shape of that list tells you something true about component libraries. The first fourteen releases were additive and safe. Everything after 2.0.0 is corrections, and a project upgrading across a major version should expect to read the intervening entries rather than the version number.

Packaging that ships types out of src, and one escape hatch in exports

The package manifest is small and a couple of choices are worth naming. The main and module fields both point at a single ESM build, and unpkg and jsdelivr both point at a UMD build, so a script tag gets the older format without a separate file name. The types field points into the source tree rather than into dist, at ./src/components/splitpanes/index.d.ts, and the files array ships both dist and that source directory to make it work. The exports map then repeats the arrangement with types, import and require conditions, plus one entry for package.json and a pattern entry for ./dist/*. That last pattern is the notable one, because it reopens the dist directory to consumers, which is what lets people reach a specific build artefact. It also means the published surface is wider than the component. A component library that exposes its whole build directory invites imports the maintainer does not support. Nothing here is wrong, and shipping source for type resolution is a common approach, but the exports map is the place where a library's public contract is decided and here it is permissive.

No test script, and a release that is one command

The scripts in package.json are dev, build, build-bundle, serve and release. There is no test script, and no test framework appears among the development dependencies, which are eslint and its plugins, the Vue Vite plugin, autoprefixer, postcss, sass, pug, an icon font and a Rollup plugin for deleting files. So the interaction behaviours that the 4.1.1 entry enumerates were found and fixed by hand, and the regression risk is exactly the kind that a pointer-driven component is exposed to: a change to how drag events are handled can reintroduce a fast-drag crash, and nothing in the build would notice. The release script deserves the same attention. It is a single chain: run build-bundle, add everything to git, commit with the message Release., push, then push the tag. The bundle variant is selected by setting an environment variable in the script, so the normal build and the distributable build are one toggle apart. There is no version bump step, because the version lives in package.json and the human editing it owns that, and no changelog step, which is consistent with the release notes being maintained by hand in the README. It is a workable process for a single maintainer and a small component, and it is not a process that survives two people.

Accessibility arrived in 4.1.0, and the browser claim goes back to IE 10

Two claims in the README bracket the project's range. The browser support table lists current Chrome, Firefox, Safari, Opera and Edge as supported on their latest versions, and Internet Explorer 10 and above. The other is the 4.1.0 entry, which made splitters focusable, added a keyboard-step prop, and added ARIA attributes. Both are recent positions. Keyboard operability of a splitter is not a detail, because a pane splitter is a control and a control that only responds to a pointer is unusable without a mouse, so its arrival in 4.1.0 means everything before that version, including all of the 3.x line, fails that basic test. If you are on an older release and care about this, the upgrade is the fix. The IE 10 line is a different kind of statement, and it is best read as a description of the build target rather than as a test result, since the repository contains a browserslist configuration and no test suite to confirm it. One more thing belongs in any assessment of this project: the README asks for sponsorship and specifically asks commercial users to back the project, tying that to keeping it maintained. That is a fair funding model for a dependency this small, and it is also a signal that one person is carrying it.

Editorial conclusion

Adopt splitpanes if you need draggable panes in Vue and want the interaction details already solved, because the 4.1.1 entry lists the failures you would otherwise spend a week on: crashes on fast drag, size jumps, the cursor disappearing, a size of 0 being ignored, Firefox selecting text mid-drag, and a flash on first paint. Do not adopt it expecting a tested component, because the package.json scripts contain no test command and no test framework appears in the development dependencies, so every behaviour listed in the release notes was verified by hand. Two things to check first. Confirm your Vue version, since Vue 2 needs splitpanes@legacy and the two packages are separate builds, not one build with a shim. And read the release notes rather than the version, because the package.json says 4.1.2 while the notes in the README stop at 4.1.1, and the release script is a single build-and-push command with no changelog step. For anything accessibility-sensitive, note that keyboard support and ARIA attributes only arrived in 4.1.0.

Frequently asked questions

Official sources

1. antoniandre/splitpanes on GitHub
2. Issues
3. License: MIT
4. Project website
5. README