{"id":11738,"library":"react-kapsule","title":"React Kapsule Wrapper","description":"react-kapsule is a utility library designed to integrate Kapsule-style web components into React applications. It provides a higher-order component, `fromKapsule`, which acts as a bridge, transforming a Kapsule component definition (often a closure-based functional component following Mike Bostock's reusable charts pattern) into a standard React component. The current stable version is 2.5.7, with the last publish being approximately a year ago, indicating a mature and stable library rather than one with frequent, breaking updates. It ships with TypeScript types, ensuring robust type checking for consumers. Its core utility lies in abstracting the imperative nature of Kapsule components, allowing them to be declaratively used within React's component tree, handling prop updates and method invocations transparently. This enables developers to leverage existing Kapsule components or build new ones with Kapsule, while still utilizing React for their main application UI.","status":"active","version":"2.5.7","language":"javascript","source_language":"en","source_url":"https://github.com/vasturiano/react-kapsule","tags":["javascript","react","wrapper","kapsule","web","component","typescript"],"install":[{"cmd":"npm install react-kapsule","lang":"bash","label":"npm"},{"cmd":"yarn add react-kapsule","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-kapsule","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React component integration; required for rendering in a React application.","package":"react","optional":false}],"imports":[{"note":"`fromKapsule` is the default export of the 'react-kapsule' package.","wrong":"import { fromKapsule } from 'react-kapsule';","symbol":"fromKapsule","correct":"import fromKapsule from 'react-kapsule';"},{"note":"For CommonJS environments, `fromKapsule` is the default export when requiring the package.","wrong":"const { fromKapsule } = require('react-kapsule');","symbol":"fromKapsule (CJS)","correct":"const fromKapsule = require('react-kapsule');"},{"note":"While react-kapsule wraps Kapsule components, Kapsule itself is typically imported from the 'kapsule' package, where it is also a default export.","wrong":"import { Kapsule } from 'kapsule';","symbol":"Kapsule (from parent library)","correct":"import Kapsule from 'kapsule';"}],"quickstart":{"code":"import React, { useRef, useEffect } from 'react';\nimport ReactDOM from 'react-dom/client';\nimport Kapsule from 'kapsule';\nimport fromKapsule from 'react-kapsule';\n\n// Define a simple Kapsule component\nconst myKapsuleComponent = Kapsule({\n  props: {\n    message: { default: 'Hello' },\n    count: { default: 0 }\n  },\n  methods: {\n    increment: function(state) { state.count++; },\n    setMessage: function(state, msg) { state.message = msg; }\n  },\n  init(domNode, state) {\n    state.container = document.createElement('div');\n    domNode.appendChild(state.container);\n  },\n  update(state) {\n    state.container.innerHTML = `<span>${state.message} from Kapsule! Count: ${state.count}</span>`;\n  }\n});\n\n// Wrap the Kapsule component for React\nconst MyReactKapsuleComponent = fromKapsule(myKapsuleComponent, {\n  methodNames: ['increment', 'setMessage'] // Expose Kapsule methods as React component methods\n});\n\nfunction App() {\n  const kapsuleRef = useRef(null);\n\n  useEffect(() => {\n    const interval = setInterval(() => {\n      if (kapsuleRef.current) {\n        (kapsuleRef.current as any).increment(); // Call exposed Kapsule method\n      }\n    }, 1000);\n    return () => clearInterval(interval);\n  }, []);\n\n  return (\n    <div>\n      <h1>React Kapsule Example</h1>\n      <MyReactKapsuleComponent\n        ref={kapsuleRef}\n        message=\"Greetings\"\n        count={10}\n      />\n      <button onClick={() => (kapsuleRef.current as any)?.setMessage('New message!')}>\n        Change Message\n      </button>\n    </div>\n  );\n}\n\nconst rootElement = document.getElementById('root');\nif (rootElement) {\n  const root = ReactDOM.createRoot(rootElement);\n  root.render(<App />);\n} else {\n  console.error(\"Root element not found\");\n}","lang":"typescript","description":"This quickstart demonstrates wrapping a Kapsule component with `fromKapsule`, passing initial props, exposing Kapsule methods, and interacting with them via a React ref to update the component imperatively."},"warnings":[{"fix":"Ensure that props intended for dynamic updates are NOT listed in `initPropNames`. Only use `initPropNames` for static, initial configuration values.","message":"Props specified in `options.initPropNames` are only used during the initial instantiation of the Kapsule component. Modifying these props after the component has mounted will have no effect on the underlying Kapsule component's configuration.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `useRef` or `createRef` to get a reference to the `MyReactKapsuleComponent`. Call methods like `myRef.current.myMethod()` instead of trying to pass them as props.","message":"Methods of the underlying Kapsule component, when exposed via `options.methodNames`, are accessible only through a React ref to the wrapped component instance. They are not directly available as props.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your project's `react` and `react-dom` versions satisfy the peer dependency requirement by upgrading to `react@^16.13.1` or newer (e.g., `npm install react@^16.13.1 react-dom@^16.13.1`).","message":"This package lists 'react' as a peer dependency, requiring `react@>=16.13.1`. Using an incompatible version of React (e.g., older than 16.13.1) can lead to unexpected behavior or runtime errors.","severity":"breaking","affected_versions":"<16.13.1 (for React)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the import statement to `import fromKapsule from 'react-kapsule';` (removing the curly braces).","cause":"Attempting to import `fromKapsule` as a named export instead of a default export in an ES module environment.","error":"TypeError: (0, react_kapsule__WEBPACK_IMPORTED_MODULE_0__.fromKapsule) is not a function"},{"fix":"Install the package using your package manager: `npm install react-kapsule` or `yarn add react-kapsule`. Ensure it's listed in `package.json`.","cause":"The 'react-kapsule' package is not installed or incorrectly referenced in your project's dependencies.","error":"Module not found: Can't resolve 'react-kapsule'"},{"fix":"Ensure the ref is correctly attached to the `MyReactKapsuleComponent` and checked for `null` or `undefined` before attempting to call methods. Methods are only available after the component has mounted.","cause":"Attempting to call a Kapsule method (e.g., `increment`) on the wrapped React component without a valid ref, or before the ref has been assigned (e.g., during initial render before mount).","error":"Cannot read properties of undefined (reading 'increment')"}],"ecosystem":"npm"}