Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
The PCSTYLE Toast system is a React-based notification library inspired by Sonner, featuring dual-theme support (Cyberpunk and Minimal). It is designed as a lightweight SDK focusing on strict type safety and clean API exports to provide a seamless notification experience in modern web applications.
The system relies on a centralized ToastStore for state management and a ToastProvider component for rendering notifications within the React component tree. It leverages framer-motion for animations and is built using TypeScript to ensure deep type safety across the package.
Prerequisites and Dependencies
The package is built as an ESM (ECMAScript Module) and requires specific peer dependencies to function correctly. It targets modern environments compatible with ES2020.
| Dependency | Version | Type | Description |
|---|---|---|---|
react | >=18 | Peer | Required for UI components and hooks |
react-dom | >=18 | Peer | Required for DOM rendering |
framer-motion | >=10 | Peer | Required for toast entrance/exit animations |
typescript | ^5.0.0 | Dev | Required for compilation and type checking |
Sources: package.json:20-24, package.json:26-31, tsconfig.json:3-16
Build Configuration
The project uses the TypeScript compiler (tsc) to generate the distribution files. The configuration ensures that the library satisfies both ESM and potential CJS consumers through specific export definitions.
- Compiler Target: ES2020
- Module System: ESNext with bundler resolution
- Output Directory:
./dist - JSX:
react-jsx(optimized for React 17+) - Type Safety:
strictmode is enabled, forbiddinganytypes or non-null assertions as per internal project rules.
Sources: tsconfig.json:3-16, package.json:15, cubic.yaml:18-24
Core Architecture
The system follows a singleton store pattern where the UI component subscribes to state changes.
This diagram illustrates the unidirectional data flow between the API, the internal store, and the React provider.
Sources: src/store.ts:21-62, src/provider.tsx:14-20
The Toast Store
The ToastStore manages the active notification queue. It limits visibility to 5 concurrent toasts to prevent UI clutter.
The class diagram shows the internal structure of the state management system.
Sources: src/store.ts:21-30, src/store.ts:40-42
Implementation Steps
1. Configure the Provider
The ToastProvider must be wrapped around the application root. It accepts configuration for the visual theme and the screen position.
| Property | Type | Default | Options |
|---|---|---|---|
theme | string | "cyber" | "cyber", "minimal" |
position | string | "bottom-right" | "top-right", "top-center", "bottom-right", "bottom-center" |
Sources: src/provider.tsx:9-12, src/provider.tsx:14
2. Triggering Notifications
The toast API provides several methods to trigger different types of notifications.
The sequence shows the lifecycle of a standard success notification.
Sources: src/index.ts:13-15, src/store.ts:40-52
3. Handling Promises
The setup includes a promise handler that updates a single toast through its lifecycle (Loading -> Success/Error).
// Example usage derived from src/index.ts
toast.promise(saveData(), {
loading: 'Saving...',
success: (data) => `Saved ${data.name}`,
error: (err) => `Error: ${err.message}`
});
Sources: src/index.ts:37-56
Summary
Setting up @pcstyle/toast involves installing the required peer dependencies (react, framer-motion), wrapping the application with the ToastProvider for theme and position configuration, and utilizing the toast utility for state-driven notifications. The system's strict TypeScript enforcement ensures that all toast interactions are type-safe and consistent with the Cyberpunk or Minimal design language.