4.2 KiB
4.2 KiB
Package Catalog And Decision Notes
Purpose
Track package decisions in one place:
- what is already used
- why it is used
- when to keep/remove/replace
- which packages are candidates for later MVPs
This file is decision support, not a lockfile replacement.
Current Core Stack (Used Now)
Runtime and App Foundation
bun: workspace package manager + runtime for scripts and local dev.next+react+react-dom: app framework foradminandweb.typescript: typed contracts across apps/packages.
Data and Validation
prisma+@prisma/client+pg+@prisma/adapter-pg: DB schema/migrations + typed DB access on PostgreSQL.zod: shared runtime validation for domain schemas and CRUD inputs.
Auth, State, Data Fetching
better-auth: admin auth/session + role metadata baseline.zustand: lightweight client state (e.g. locale/UI state).@tanstack/react-query: async state/query cache patterns for admin/public app data fetching.@tanstack/react-formand@tanstack/react-table: form/table primitives in admin workflows.
UI and Styling
tailwindcss+@tailwindcss/postcss: utility-first styling baseline.class-variance-authority,clsx,tailwind-merge: component variant + class composition in@cms/ui.
Testing and Quality
vitest,@testing-library/react,@testing-library/jest-dom,@testing-library/user-event,msw,jsdom: unit/integration tests + UI interaction + API mocking.@playwright/test: end-to-end tests.@biomejs/biome: lint/format/check baseline.turbo: monorepo task orchestration.
Docs and Release Governance
vitepress: docs site.conventional-changelog-cli: changelog generation from conventional commits.@commitlint/cli+@commitlint/config-conventional: commit message schema enforcement.
Media and Color Processing Notes
Why sharp is typically the default choice
sharp is usually the best baseline for server-side image processing because:
- strong performance and memory behavior
- reliable resize/crop/format conversion pipeline
- robust support for production workloads
- good integration in Node/Bun server contexts
Use cases for this CMS:
- generate artwork renditions (thumb/card/full/custom)
- normalize uploads and output formats
- create banner/promo safe-size outputs
- optional watermark compositing pipeline
Color extraction package options
node-vibrant
- Best for: quick dominant palette extraction for UI accents and tagging.
- Tradeoff: less control over advanced color science.
colorthief
- Best for: simple dominant-color extraction with minimal setup.
- Tradeoff: more limited output and tuning compared to richer libraries.
culori/chroma-js(supporting libs, often combined with extractor)
- Best for: color manipulation, conversion, contrast checks, palette normalization.
- Tradeoff: not a full image extractor by itself.
Recommended approach:
- MVP2 start with
sharp+node-vibrant+culori - keep extraction pipeline behind an internal adapter so replacement is easy
Candidate Packages For Later (Not Installed Yet)
File Upload and Storage Abstraction
@aws-sdk/client-s3(+ presign utilities): for S3/R2/object storage adapters and signed upload/download flows.uploadthingor custom presigned-upload implementation: faster admin upload UX with secure direct-to-storage path.
Rich Text / Page Builder
tiptap: rich editorial experience for pages/news.@dnd-kit/core: drag-and-drop block ordering/page-builder interactions.
Media Pipelines / Jobs
bullmq+ioredis: background job queue for heavy media transforms (watermark/video/etc).
Commissions and CRM Extensions
@tanstack/react-virtual: large admin tables (requests/customers) without rendering bottlenecks.
Observability / Reliability
@sentry/nextjs: app error monitoring.pino: structured logs for services/workflows.
Add/Remove Decision Rules
When adding a package, document:
- problem it solves
- why existing stack is insufficient
- expected maintenance/runtime cost
- fallback/exit plan
When removing/replacing:
- list impacted modules
- verify tests and migration path
- update this catalog and related ADR/docs