cli-spinners: the product is a JSON file, and the random example shows the wrong spinner

The payload is one JSON file and the module is a wrapper

The readme is unusually direct about what this package is. The list of spinners is just a JSON file, and it can be used wherever. Three lines later it tells you that you probably want to use one of these spinners through another package, which is the same author's terminal spinner module. So the useful artefact is a data file, and the npm package exists to give that data a name, a version and a type declaration. The manifest confirms the shape: only three files are published, the module, its type declaration and the JSON. There is no build step in the shipped output and no runtime dependency list at all, which is why the page can say the data can be used wherever without hedging. For anyone not writing Node, the honest reading is that you are welcome to copy the JSON into your own project and skip the package entirely.

npm install cli-spinners

Two fields per spinner, and timing is part of the design

Every entry has the same two fields, and the readme explains each in a sentence. The interval is the intended time per frame, in milliseconds. The frames are the array of characters to show in sequence. That is the whole schema, and the worked example makes the point better than the prose does: the spinner named for dots consists of ten frames drawn from the braille block, recommended to run at eighty milliseconds per frame. The braille characters matter, because they are what let a single cell cycle through ten shapes without the line jumping, which is why a spinner built from ordinary letters looks ragged and one built from braille does not. The tagline claims seventy or more spinners, and since each is a handful of characters and a number, the whole data file is small enough that reading it end to end is a reasonable way to choose one.

The random example prints a named spinner's output

There are two code examples, and the second one has a copy and paste error that is worth catching before you rely on it. The first shows how to log a named spinner and then displays the shape of the result as a comment. The second shows how to get a random spinner and logs it, but the comment underneath showing the output is character for character the same object as the first example, down to the same ten frames at the same interval. A random pick returning the specific spinner used as the deterministic example above it is unlikely, so the comment is a copy rather than a real result. The shape it shows is still correct, which is why the mistake survives: it teaches the right structure while claiming to demonstrate randomness.

Six ports, and that is the argument for the data-only design

The related section lists a same-language module by the author and then six ports maintained by other people. There is a Swift port, a Python port, a Rust port, a Go port, a Bash port and a Neovim plugin. Six implementations across five languages, none of them a dependency of this package. That list is the practical argument for shipping plain JSON: a port does not have to reimplement an animation loop, a terminal abstraction or a stream writer, because the hard part of a spinner is the frames and the timing, and those are data. It also explains the recommendation to use the author's other module for Node, since the interesting code in that package is the part this one deliberately leaves out.

import {randomSpinner} from 'cli-spinners';

console.log(randomSpinner());

The linter is a script whose name comments itself out

The scripts section has two test entries and the trick is in the names. One is called test and runs the test runner followed by a type check of the declaration file. The other is called with two forward slashes in front of the word test, and runs the linter first, then the same two steps. A script whose name begins with a slash is not something anybody can type by accident, so this is a way of keeping the full pipeline available and documented while making sure the command a developer reaches for first does not lint. The reasoning is sound, since linting on every local test run is a common irritation, but the mechanism is unusual enough that a contributor will not find it without reading the manifest. The same section records a script that records a terminal cast of all the spinners, and its title is singular where the package is plural.

An empty centred paragraph where the animation was

Under the tagline there is a centred paragraph element containing three line breaks and nothing else. It is the shape markdown leaves behind when an image is removed from between the tags, and it is a small piece of evidence about how the page is maintained. The preview section then admits that the header animation is outdated and sends you to a live demonstration hosted on a code playground instead. The repository carries both a GIF and an SVG of the same spinner, so the outdated artefact is still committed alongside a vector version of it. None of this affects the package. It does mean the page's most prominent visual is one the author has flagged as wrong, and that the live version lives on a third-party site whose longevity nobody controls.

Node 18.20, no homepage, and a licence file with no extension

The manifest is small enough to read as a description of the project's priorities. The engine requirement is Node 18.20 or above, which is a precise floor rather than a vague recent version. The package is marked as having no side effects, so a bundler can drop it if it decides the import is unused. There is no homepage field, and the repository metadata carries no homepage either, so the only durable addresses are the repository itself and a funding link. The licence file at the root is named with no extension at all, which several automated licence scanners will not find, though the manifest declares the licence as MIT in the usual way. The readme is also in lower case, which is the npm convention and not what a generic tool expects. All three are conventions that work and that a first-time contributor can trip over.

Editorial conclusion

cli-spinners is worth using directly if you are writing something in any language and want a vetted set of terminal animations, because the data is plain JSON and the module around it is three lines of import. Take it for the frames rather than for the package, and read the interval alongside the frames, since the recommended timing is part of what makes a spinner look right rather than frantic. Use the author's spinner module for Node if you want the terminal handling done for you, and copy the JSON if you are not in Node at all. Ignore the random picker example in the readme when you are checking the shape of the output, because it prints a named spinner's result. And pin the package, since it is three files and a data file, and therefore trivial to vendor if it ever stops being published.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sindresorhus/cli-spinners on GitHub