mizumi25/nagare

Nagare is a JavaScript library for React that gives interactive behaviors their own place in your code. In a typical frontend project, a single button hover triggers a cascade: the lift effect is in CSS, the glow is in an animation library, the state update is in a store, and the logic is in an event handler. Nagare argues that a hover is one thing and should live in one place. The library works around two main ideas: a soul (which represents a DOM element) and a behavior (which is a detector that watches for something happening, like a click, hover, scroll, or the network dropping). When a behavior fires, it runs through a lifecycle with three stages: start, update, and end. Inside each stage, you write CSS (plain CSS, not camelCase objects), Tailwind classes, or JavaScript, all together in the same block. To use it in React, you call the useSoul hook and define your souls and their behaviors inside it. The hook handles registering your definitions, binding them to elements, watching for new elements that appear later, and cleaning up when the component unmounts. In your JSX, you mark elements with a data-soul attribute to connect them to their definitions. The JSX itself stays free of class name logic, inline styles, and event handlers. Nagare ships over twenty built-in behaviors including tap, press, swipe with direction info, drag with live position, scroll, resize, focus, visibility detection, idle detection, and network change detection. You can define reusable style snippets called templates and reusable lifecycle definitions called presets to share across multiple souls. State is per-soul and you can reference it directly in CSS blocks using conditional logic. The library also provides a TypeScript plugin for editors like VS Code that adds autocomplete inside Tailwind and CSS string values, including keyword completions. Nagare handles attaching and reacting to behaviors, it does not do animation interpolation or tweening, which you delegate to libraries like GSAP.