How toss/suspensive works
Project Type and Purpose
• This is an open-source monorepo of TypeScript/JavaScript libraries (“Suspensive”) providing utilities and integration points to use React Suspense easily across React, React DOM, React Native, React Query (v4 & v5), Jotai, plus codemods.
• It also includes a Next.js-based documentation website (docs/suspensive.org) and several example consumer apps under examples/.
• Tooling is centralized via pnpm workspaces and Turborepo; builds use tsup; tests use Vitest/Jest; CI/CD runs via GitHub Actions; publishing targets the npm registry.
File Structure Analysis
Top-level directories:
• .github/, ci.yml, etc. → CI/CD and repository automation
• configs/ → shared ESLint, tsconfig, tsup configurations packaged for intra-repo reuse
• packages/ → eight workspace packages (codemods, jotai, react-dom, react-native, react-query-4, react-query-5, react-query, react) each with src/, tests, build configs
• docs/suspensive.org/ → Next.js website with MDX pages, components, static assets
• examples/ → example consumer projects demonstrating usage patterns
• Root scripts & config: pnpm-workspace.yaml, turbo.json, package.json, lint/staged, husky, commitlint, Codecov, Dependabot, etc.
Key README Insights
• “All in one for React Suspense” – the monorepo produces multiple related packages.
• Documentation is delivered via suspensive.org (Next.js site under docs/).
• CI badges (Codecov, GitHub Actions workflows for lint, test, graph, release).
A. Workspace Manager
• pnpm workspaces & Turborepo orchestrate installation and task pipelines.
B. Shared Configuration Packages (configs/)
• ESLint configs, tsconfig presets, tsup configs → consumed by each package, example, docs.
C. Library Packages (packages/*)
• codemods
• jotai
• react
• react-dom
• react-native
• react-query-4 & react-query-5 & react-query (CLI tooling)
– Each package: src/ → build (tsup) → dist/ → published to npm.
D. Documentation Site (docs/suspensive.org)
• Next.js app → MDX content + React components → hosted on suspensive.org
• Imports versioned packages, example code embeds.
E. Example Applications (examples/*)
• Next.js examples, React Native playground, Vite/React example → install workspace packages → showcase features.
F. CI/CD & Publishing
• GitHub Actions workflows trigger on push/PR:
– Lint & typecheck → tests → code coverage → graph dependencies → knip (unused imports)
– On release tag: Turborepo publishes packages to npm, updates docs site.
• External services: GitHub, Codecov, npm registry, Discord link.
Relationships & Data Flows:
1. Developer commits → Husky + lint-staged + commitlint validate code locally.
2. Push triggers GitHub Actions → Turborepo runs tasks in workspace.
3. Package build → tsup bundles each package → Vitest/Jest picks up tests → Codecov collects coverage.
4. On release: packages published to npm; docs site deployed.
5. Examples & docs npm install pull from local workspace during development or from npm in CI.
Architectural Patterns & Principles
• Monorepo with Workspace Isolation: shared config, enforced by pnpm + Turborepo caching.
• Modular Design: each package is standalone, versioned, tested, and published independently.
• Reuse of Shared Config: ESLint, tsconfig, tsup configs are themselves packages under configs/.
• Consumer-Driven Documentation & Examples: docs site and examples import directly from workspace during dev, ensuring up-to-date demos.
• CI as Code: GitHub workflows defined centrally under .github/.