Field Notes

Dependency Catalogue

Curated package selections grouped by purpose, with alternatives and usage guidance.

A curated list of packages grouped by purpose. Each entry reflects real project experience — packages that have proven reliable, well-maintained, and composable. This is a starting point, not a mandate.

Build and Tooling

PackagePurposeWhen to UseAlternative
turboMonorepo task orchestration and cachingAny multi-package reponx
typescriptType-safe JavaScriptEvery project
eslintCode linting and static analysisEvery projectbiome
prettierCode formattingEvery projectbiome
huskyGit hook managementProjects with pre-commit checkssimple-git-hooks
lint-stagedRun linters on staged files onlyPaired with husky

Framework

PackagePurposeWhen to UseAlternative
nextFull-stack React frameworkWeb apps needing SSR, API routes, or ISRremix
reactUI component libraryAny React-based projectpreact (smaller bundle)
viteDev server and build toolSPAs, prototypes, Storybook
@vitejs/plugin-reactReact support for ViteVite + React projects@vitejs/plugin-react-swc

UI and Components

PackagePurposeWhen to UseAlternative
@radix-ui/react-*Accessible, unstyled UI primitivesWhen you need accessible building blocks without opinionated styling@headlessui/react
lucide-reactIcon library (tree-shakeable SVGs)Any project needing icons@phosphor-icons/react
cvaClass variance authority — variant management for className-based stylingComponents with multiple visual variantsHand-written conditional classNames
clsxConditional className compositionAny project joining classNamescn utility (clsx + tailwind-merge)

Data and API

PackagePurposeWhen to UseAlternative
zodRuntime schema validation and type inferenceAPI boundaries, form validation, environment variable parsingvalibot (smaller bundle)
@supabase/supabase-jsSupabase client (auth, database, storage, realtime)Projects using SupabaseDirect pg client
@sanity/clientSanity CMS clientProjects using Sanity as editorial CMScontentlayer
@tanstack/react-queryServer state management with cachingAny app fetching remote dataswr

Email

PackagePurposeWhen to UseAlternative
resendTransactional email APIProjects needing reliable email delivery@sendgrid/mail
@react-email/componentsReact components for email templatesWhen emails need consistent branding and layoutmjml

Charting and Visualization

PackagePurposeWhen to UseAlternative
rechartsDeclarative React chartsDashboards, reports, standard chart types@nivo/core
d3Low-level data visualizationCustom visualizations, maps, complex interactionsvisx (React + D3)

Testing

PackagePurposeWhen to UseAlternative
vitestUnit and integration testingVite-based projectsjest
@testing-library/reactReact component testing utilitiesAny React test suiteenzyme (deprecated)
playwrightCross-browser E2E testingCritical user journeyscypress
mswAPI mocking via service workersTests and development with mock APIsnock

Animation

PackagePurposeWhen to UseAlternative
gsapHigh-performance animation libraryComplex sequences, scroll-driven animations, timeline controlanime.js
framer-motionDeclarative React animationComponent transitions, layout animations, gesturesreact-spring

Versioning Policy

Pin major versions. Use ^ (caret) ranges in package.json to allow patch and minor updates while preventing breaking changes. Run pnpm outdated monthly.

  • Update regularly. Apply minor/patch updates in a dedicated PR with a passing CI build.
  • Audit before adding. Before adding a new dependency, check: Is there already a package in the repo that does this? Is the package actively maintained? What is the bundle size impact?

Lock files are sacred. Always commit pnpm-lock.yaml (or equivalent). Never delete it to "fix" install issues — investigate the root cause.

Anti-Patterns

  • Duplicate functionality. Two packages solving the same problem (e.g., both axios and fetch wrappers).
  • Abandoned packages. Dependencies with no updates in 12+ months and open security advisories.
  • Kitchen-sink imports. Importing an entire utility library for one function. Prefer tree-shakeable packages or copy the single function.
  • Transitive dependency reliance. Using a package that is only available because another package depends on it. Always add explicit dependencies for packages you import directly.

See Also

On this page