| name | jotai |
| description | Primitive and flexible state management for React using atoms. |
Skill: Jotai
Category: Frontend Engineering
Priority: High
Description
Primitive and flexible state management for React using atoms.nn
Purpose
Reduce implementation risk and accelerate development by applying the correct patterns, configuration, and integration steps for Jotai. The goal is to produce code that is performant, maintainable, and aligned with the official documentation.
Trigger
Use this skill when:
- Building a feature that depends on Jotai.
- Deciding whether Jotai is the right tool for the current architecture.
- Reviewing, debugging, or refactoring code that uses Jotai.
- Integrating Jotai with other pmndrs libraries or React patterns.
- Setting up a new project or adding the library to an existing project.
- Evaluating performance, accessibility, or SSR implications of Jotai.
Context
- Project framework, version, and build tooling.
- Target devices and performance budgets (desktop, mobile, VR/AR).
- Related libraries already in use (React, Three.js, state managers, animation libraries).
- Client-only versus SSR constraints.
- Existing component structure and coding standards.
- Need for TypeScript types, tests, and documentation.
- License and compatibility requirements.
Workflow
- Confirm the problem or feature that requires Jotai.
- Review the official documentation and the data files in this skill.
- Install the library using the recommended package manager and version.
- Configure the library according to the project setup and constraints.
- Build a minimal working example that proves the integration.
- Expand the example into production-ready components with error handling.
- Run the verification checklist, including performance and accessibility checks.
- Document decisions, trade-offs, and any deviations from the official docs.
- Clean up temporary code, remove unused imports, and ensure proper disposal.
Examples
Good: Minimal usage
`js
// See data/readme.md and data/docs/ for exact API details.
import * as Lib from 'jotai'
// Initialize the library according to its documented pattern.
const instance = Lib.createSetup()
// Use it within a React component or module.
`
Bad: Unverified copy-paste
js // Do not copy examples without confirming they match your project version and setup. const instance = Lib.createSetup({ wrongOption: true })
Anti-patterns
- Using Jotai without understanding its primary use case and trade-offs.
- Combining it with incompatible libraries or conflicting state patterns.
- Skipping cleanup, ignoring SSR constraints, or leaking resources on unmount.
- Ignoring performance implications on low-end or mobile devices.
- Copying examples from documentation without adapting them to the project.
- Hardcoding configuration that should be environment-specific or shared.
- Neglecting error handling, loading states, and fallback behavior.
Common Mistakes
- Installing the wrong version or missing peer dependencies.
- Forgetting to wrap client-only code in the appropriate lifecycle hooks.
- Creating new instances inside render loops or event handlers without memoization.
- Not testing on target devices or with reduced-motion preferences enabled.
- Mixing multiple solutions from the same domain without clear ownership.
Verification
Cross Skill References
- Frontend Engineering: React lifecycle, component structure, responsive design.
- Performance Optimization: Profiling, budgets, and optimization.
- React Three Drei: When building 3D scenes with pmndrs tools.
- Scrollytelling: When scroll-driven experiences need 3D or animation.
- Documentation: Recording decisions, ADRs, and performance results.
- Quality Audit: Validating this skill and any assets produced with it.
References
- Repository: https://github.com/pmndrs/jotai
- data/readme.md  latest README from Jotai
- data/docs/  latest documentation from Jotai
- LICENSE  license of Jotai
