Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fromKapsule
✓ import fromKapsule from 'react-kapsule';
✗ import { fromKapsule } from 'react-kapsule';
`fromKapsule` is the default export of the 'react-kapsule' package.
fromKapsule (CJS)
✓ const fromKapsule = require('react-kapsule');
✗ const { fromKapsule } = require('react-kapsule');
For CommonJS environments, `fromKapsule` is the default export when requiring the package.
Kapsule (from parent library)
✓ import Kapsule from 'kapsule';
✗ import { Kapsule } from 'kapsule';
While react-kapsule wraps Kapsule components, Kapsule itself is typically imported from the 'kapsule' package, where it is also a default export.
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.
import React, { useRef, useEffect } from 'react';
import ReactDOM from 'react-dom/client';
import Kapsule from 'kapsule';
import fromKapsule from 'react-kapsule';
// Define a simple Kapsule component
const myKapsuleComponent = Kapsule({
props: {
message: { default: 'Hello' },
count: { default: 0 }
},
methods: {
increment: function(state) { state.count++; },
setMessage: function(state, msg) { state.message = msg; }
},
init(domNode, state) {
state.container = document.createElement('div');
domNode.appendChild(state.container);
},
update(state) {
state.container.innerHTML = `<span>${state.message} from Kapsule! Count: ${state.count}</span>`;
}
});
// Wrap the Kapsule component for React
const MyReactKapsuleComponent = fromKapsule(myKapsuleComponent, {
methodNames: ['increment', 'setMessage'] // Expose Kapsule methods as React component methods
});
function App() {
const kapsuleRef = useRef(null);
useEffect(() => {
const interval = setInterval(() => {
if (kapsuleRef.current) {
(kapsuleRef.current as any).increment(); // Call exposed Kapsule method
}
}, 1000);
return () => clearInterval(interval);
}, []);
return (
<div>
<h1>React Kapsule Example</h1>
<MyReactKapsuleComponent
ref={kapsuleRef}
message="Greetings"
count={10}
/>
<button onClick={() => (kapsuleRef.current as any)?.setMessage('New message!')}>
Change Message
</button>
</div>
);
}
const rootElement = document.getElementById('root');
if (rootElement) {
const root = ReactDOM.createRoot(rootElement);
root.render(<App />);
} else {
console.error("Root element not found");
}
Debug
Known issues
gotchaProps 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.fixEnsure that props intended for dynamic updates are NOT listed in `initPropNames`. Only use `initPropNames` for static, initial configuration values.
affects: >=1.0.0
gotchaMethods 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.fixUse `useRef` or `createRef` to get a reference to the `MyReactKapsuleComponent`. Call methods like `myRef.current.myMethod()` instead of trying to pass them as props.
affects: >=1.0.0
breakingThis 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.fixEnsure 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`).
affects: <16.13.1 (for React)
Errors
Common errors & fixes
TypeError: (0, react_kapsule__WEBPACK_IMPORTED_MODULE_0__.fromKapsule) is not a function
Attempting to import `fromKapsule` as a named export instead of a default export in an ES module environment.
fixChange the import statement to `import fromKapsule from 'react-kapsule';` (removing the curly braces).
Module not found: Can't resolve 'react-kapsule'
The 'react-kapsule' package is not installed or incorrectly referenced in your project's dependencies.
fixInstall the package using your package manager: `npm install react-kapsule` or `yarn add react-kapsule`. Ensure it's listed in `package.json`.
Cannot read properties of undefined (reading 'increment')
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).
fixEnsure 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.
Audit
Dependencies
reactrequiredPeer dependency for React component integration; required for rendering in a React application.