How masaudahmod/your-toast works
1. Project type and boundary
- This is a client-side React toast notification library, not an application. Its architecture is centered around exposing a small public API that drives an internal toast state store and a rendering provider.
2. Public entrypoint
- src/index.ts is the package surface. It likely re-exports the provider, toast API, hook, and shared types so consumers can import from your-toast directly.
- The published package is built into dist/index.js, indicating a compiled library distribution rather than a runtime app.
3. Core command API
- src/core/toast.ts appears to implement the imperative API used by consumers: toast(), variant helpers like toast.success/error/loading, toast.promise, plus control methods such as update and dismiss.
- This layer is the main orchestration point between user calls and the internal store.
4. Variant model
- src/core/variants.ts likely defines the supported toast kinds: default, success, error, loading, and action.
- Variants are a key architectural boundary because they determine both behavior and presentation.
5. Shared state store
- src/store/toastStore.ts is the central state container. It likely holds the active toast list, stack/limit behavior, and subscriber notifications.
- This store is what makes the library controllable from outside React component trees and supports updates/dismissals by id.
6. Provider and rendering layer
- src/components/YourToastProvider.tsx is the UI boundary that connects the store to React rendering.
- Consumers wrap their app with this provider so toast state changes can be observed and rendered as visible notifications.
7. Hook-based access
- src/hooks/useToast.ts is the React-friendly access point for components that want to trigger toasts without using the global imperative import directly.
- This separates “triggering” from “rendering,” while still using the same underlying store.
8. Type contracts
- src/types/toast.ts defines the data model for toast objects and options.
- These types are the contract between the public API, store, and UI components, ensuring the same shape is used throughout the system.
9. Main data flow
- A consumer calls toast(...) or toast.promise(...).
- The core API creates or updates a toast record in the store.
- YourToastProvider subscribes to store changes and renders the active toast stack.
- User actions or timers then call back into the store for dismiss/update behavior.
10. Build and packaging
- tsconfig.json and tsup.config.ts show a TypeScript library build pipeline.
- tsup is the packaging tool, which is typical for a reusable NPM package because it emits distributable JS from the src/ tree into dist/.
11. Architectural shape
- The repo is organized into a clean separation of API orchestration (core), state management (store), presentation (components), React integration (hooks), and shared contracts (types).
- That separation is the main thing to capture in an architecture diagram: user-facing calls go into core/store, and the provider is the rendering endpoint.
Main entry points: index.ts index · toast.ts toast API · toastStore.ts toast store · YourToastProvider.tsx ToastProvider
Components 10
Public API
Package surface exported to consumers.
- index · Package entry that re-exports the public surface.
src/index.ts - toast types · Shared toast and option data shapes used across the package.
src/types/toast.ts
Toast Runtime
Imperative API and shared state that manage toast lifecycle.
- toast API · Imperative toast creation, update, dismiss, and promise helpers.
src/core/toast.ts - variants · Supported toast kinds and variant behavior.
src/core/variants.ts - toast store · Central toast state, subscriptions, and lifecycle coordination.
src/store/toastStore.ts
React UI
Provider and hook that connect state to rendering and component use.
- ToastProvider · Subscribes to toast store and renders active notifications.
src/components/YourToastProvider.tsx - useToast · Hook-based access to the toast API for components.
src/hooks/useToast.ts
Build & Dist
TypeScript library build and published output.
- dist build · Published bundled JavaScript output.
dist/index.js - tsup config · Library bundling and packaging configuration.
tsup.config.ts - tsconfig · TypeScript compilation settings for the library build.
tsconfig.json
Connections 15
- index → toast API: re-exports · Package consumers import the command API from the entrypoint.
- index → ToastProvider: re-exports · Entry point exposes the provider component.
- index → useToast: re-exports · Entry point exposes the hook API.
- index → toast types: re-exports · Entry point exposes shared types.
- toast API → toast store: writes · Commands create, update, dismiss, and resolve toast records through the store.
- toast API → variants: uses · Variant helpers and special-case behavior are defined by supported toast kinds.
- toast API → toast types: depends on · Public API shapes are typed by shared contracts.
- toast store → toast types: stores · Store state is composed of the toast data model.
- ToastProvider → toast store: subscribes · Provider observes store changes to render active toasts.
- ToastProvider → variants: renders · Presentation varies by toast kind.
- useToast → toast API: calls · Hook provides ergonomic access to the imperative API.
- useToast → toast store: reads · Hook may coordinate with the shared store for toast state.
- dist build → index: built from · Distribution output is compiled from the source entrypoint.
- tsup config → dist build: produces · Bundler configuration emits the distributable build.
- tsconfig → tsup config: supports · TypeScript settings support the build pipeline.