shellback

Every CLI tool that does something async needs a spinner. Every long operation needs a progress bar. Yet most developers either reach for heavy dependencies or copy-paste the same spinner code between projects.

shellback is my take on terminal animations: a lightweight TypeScript library with ocean-themed defaults built in. The name comes from the naval "shellback" tradition — sailors who've crossed the equator — and also references the hard shell on a lobster's back. It felt right for something that protects you from the tedium of watching a cursor blink.

The library provides spinners with names like "wave", "tide", "bubbles", "lobster", and "fish", plus progress bars with presets like "reef" and "anchor". Use the defaults for instant ocean vibes, or customize everything for your own aesthetic. Either way, your CLIs will look better.

The main challenge was keeping the library truly lightweight while still providing a good DX. Many terminal animation libraries pull in dependencies for things like color support or terminal detection. shellback handles colors with simple ANSI codes and trusts that modern terminals support them.

Another consideration was the dual ESM/CommonJS build. The JavaScript ecosystem is still transitioning, and a library needs to work in both worlds. tsup made this relatively painless, but getting the package.json exports right required some iteration.

This project reminded me that libraries have different constraints than applications. An app can have opinions; a library should have sensible defaults but stay flexible. shellback's ocean theme is the default, but every spinner and progress bar can be customized — because your CLI might not be lobster-themed (though it should be).

I also learned that the best way to test terminal animations is to build a demo that actually runs them. Unit tests can verify the logic, but you need to watch the spinners spin to know if they look right.