toss avatar

react-simplikit

GitHub stars
361

Install

/plugin install react-simplikit@react-simplikit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add toss/react-simplikit.

Contents

Discovered from source

Skills 2

react-simplikit-codemod

When to use this

The project imports @react-simplikit/mobile, which is deprecated. Every export of that package now ships from the react-simplikit root entry.

Do not run this when the project has no @react-simplikit/mobile dependency, or when the user only asked a question about the migration — answer from this file instead.

Preconditions

  • The working tree is committed or stashed. This command rewrites files in place and has no undo of its own.

Commands

Preview first — this writes nothing:

npx react-simplikit-codemod mobile-to-root --dry-run --json

Apply:

npx react-simplikit-codemod mobile-to-root

Limit it to one directory:

npx react-simplikit-codemod mobile-to-root src

Skip paths, or leave manifests alone:

npx react-simplikit-codemod mobile-to-root --ignore 'legacy/**' --ignore '**/e2e/**'
npx react-simplikit-codemod mobile-to-root --no-package-json

--debug puts stack traces in the report and on stderr, including for files that could not be processed. The command never prompts and is safe to run twice, so it fits non-interactive and CI use.

JSON output

--json writes only this object to stdout. Everything else goes to stderr.

{
  "transform": "mobile-to-root",
  "dryRun": false,
  "scanned": 128,
  "changed": [
    {
      "kind": "source",
      "file": "src/a.tsx",
      "changes": [{ "line": 3, "kind": "import" }]
    },
    {
      "kind": "manifest",
      "file": "package.json",
      "dependencies": [
        {
          "field": "dependencies",
          "removed": "@react-simplikit/mobile",
          "added": "^0.2.0"
        }
      ]
    }
  ],
  "manual": [
    {
      "file": "src/a.tsx",
      "line": 4,
      "reason": "Left on its own line: `isIOS` already refers to a different import here..."
    },
    {
      "file": "package.json",
      "reason": "\"overrides\" still pins @react-simplikit/mobile..."
    }
  ],
  "failed": []
}

The object always carries these six keys.

changed[].kind is source or manifest, and it decides the rest of the entry: a source entry carries changes, a manifest entry carries dependencies. Neither key appears on the other kind, so branch on kind rather than testing an array for emptiness.

changes[].kind is one of import, export, require, dynamic-import, import-type, mock, merge.

dependencies[].added is null in two cases: the existing react-simplikit range already satisfies the floor and was left as it was, or no registry range could be written at all because the old dependency was pinned by a workspace:/catalog:/file: protocol. The second case always carries a manual note naming the field.

manual[].line is present only for a note about a specific import; manifest notes have no line.

failed[] holds the files that could not be read, parsed, or written. It is always present and usually empty.

After the run

  1. Act on every entry in manual by hand. Entries with a line mark an import the codemod deliberately left on its own — read the reason before merging it yourself, because merging it by hand can change what a name binds.
  2. Run a bare npm install (or the equivalent) so the lockfile drops the old package. Do not run npm install react-simplikit — it would overwrite the range the codemod just wrote.
  3. Run the project's formatter or linter fix (eslint --fix, say) on the changed files. Import-order rules place react-simplikit differently from @react-simplikit/mobile, so a sorted import block is usually out of order after the run.
  4. Require react-simplikit@0.2.0 or newer — the first release re-exporting the SafeAreaInset type from the root entry. An existing range below that floor is raised automatically; a workspace:/catalog:/file: protocol is kept and reported instead.

Failure handling

Exit codeWhat to do
2The invocation was wrong. stderr names the bad path or flag. Fix it and rerun
1Some files could not be processed. They are listed in failed (or under Could not be processed); every other file was migrated. Fix those and rerun
0Done. Review the diff

react-simplikit

Zero-dependency React hooks, components and utils in one package, react-simplikit. Alongside state/logic and browser-event hooks it covers the mobile-web problems — on-screen keyboard, safe-area insets, visual viewport, body scroll lock — that usually get hand-written.

Critical rules

  • Check the catalog before hand-writing debounce, throttle, toggle, counter, list/map/set state, interval, timeout, previous-value, stable-callback, click-outside, long-press, intersection/visibility or storage-persisted-state logic. If a matching entry exists, use it. Reimplementing these is the most common mistake this skill exists to prevent.
  • Never guess a signature. Before using an entry, read references/<name>.md — it has the parameter table, return shape and a working example.
  • One import path, named imports only: import { useDebounce, useKeyboardHeight } from 'react-simplikit'. There is no subpath and no default export.
  • SSR: never branch server-rendered markup on a value that comes from a browser API hook. Use useIsClient for client-only rendering instead of typeof window checks.
  • Do not wrap or re-export these hooks in the consumer project just to rename them; use them directly so upgrades stay mechanical.

Common needs → use

Backticks in this table mark catalog entries only.

NeedUse
Debounce a callback (search input, resize)useDebounce / useDebouncedCallback
Throttle a callback (scroll, pointer move)useThrottle / useThrottledCallback
Boolean on/off, flip onlyuseToggle
Boolean on/off with explicit set-true / set-falseuseBooleanState
Numeric state with bounds/stepuseCounter
Array / Map / Set state with immutable helpersuseList / useMap / useSet
State persisted in localStorage / sessionStorageuseStorageState
Declarative setInterval / setTimeoutuseInterval / useTimeout
Stable callback identity without stale closuresusePreservedCallback
Skip re-renders when an object is deep-equalusePreservedReference
Run an async function in an effectuseAsyncEffect
Effect that runs only when a condition holdsuseConditionalEffect
Side effect tied to a DOM ref (attach/detach)useRefEffect
Click / tap outside an element (close menu, modal)useOutsideClickEffect
Long press / double clickuseLongPress / useDoubleClick
Element enters or leaves the viewportuseIntersectionObserver
How long an element stayed visible (impression tracking)useImpressionRef / ImpressionArea
React to tab / page visibility changes with a callbackuseVisibilityEvent
Read the current tab / page visibility as stateusePageVisibility
Device locationuseGeolocation
Combine multiple refs into onemergeRefs
Controlled-or-uncontrolled component stateuseControlledState
Input onChange boilerplateuseInputState
Render one of several components by keySwitchCase
Put a separator between childrenSeparated
Create a Context + Provider + hook without boilerplatebuildContext
Merge props objects (handlers chained, className joined)mergeProps
Client-only rendering guarduseIsClient
Fixed-bottom element must avoid the on-screen keyboard (mobile web)useAvoidKeyboard
Keyboard height / visibility (mobile web)useKeyboardHeight, isKeyboardVisible
Notch / home-indicator insets (mobile web)useSafeAreaInset, getSafeAreaInset
Lock body scroll while a sheet/modal is open (mobile web)useBodyScrollLock

Workflow

  1. Match the need against the table above, then confirm in the full catalog.
  2. Read references/<name>.md for the signature and example. Do not rely on memory.
  3. Import from react-simplikit.
  4. If nothing matches, write plain React — do not stretch a hook past its documented purpose.

Catalog

hooks

NameDescription
useAsyncEffectuseAsyncEffect is a React hook for handling asynchronous side effects in React components.
useAvoidKeyboarduseAvoidKeyboard is a React hook that helps fixed-bottom elements avoid the on-screen keyboard.
useBodyScrollLockuseBodyScrollLock is a React hook that locks body scroll while the component is mounted.
useBooleanStateuseBooleanState is a React hook that simplifies managing a boolean state.
useCallbackOncePerRenderuseCallbackOncePerRender is a React hook that ensures a callback function is executed only once, regardless of how many times it's called.
useConditionalEffectuseConditionalEffect is a React hook that conditionally executes effects based on a predicate function.
useControlledStateuseControlledState is a React hook that allows you to control both controlled and uncontrolled states.
useCounteruseCounter is a React hook that manages a numeric counter state with increment, decrement, and reset capabilities.
useDebounceuseDebounce is a React hook that returns a debounced version of the provided callback function.
useDebouncedCallbackuseDebouncedCallback is a React hook that returns a debounced version of the provided callback function.
useDebouncedValueuseDebouncedValue is a React hook that returns a debounced copy of the given value.
useDoubleClickuseDoubleClick is a React hook that differentiates between single and double click events.
useGeolocationuseGeolocation is a React hook that retrieves and tracks the user's geographical location.
useImpressionRefuseImpressionRef is a React hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport.
useInputStateuseInputState is a React hook that manages an input state with optional value transformation.
useIntersectionObserveruseIntersectionObserver is a React hook that detects whether a specific DOM element is visible on the screen.
useIntervaluseInterval is a React hook that executes a function at a specified interval.
useIsClientuseIsClient is a React hook that returns true only in the client-side environment.
useIsomorphicLayoutEffectuseIsomorphicLayoutEffect is a React hook that runs useLayoutEffect in the browser without triggering its warning during server-side rendering (SSR).
useKeyboardHeightuseKeyboardHeight is a React hook that tracks the on-screen keyboard height.
useListA React hook that manages an array as state.
useLoadinguseLoading is a React hook that simplifies managing the loading state of a Promise.
useLongPressuseLongPress is a React hook that detects when an element is pressed and held for a specified duration.
useMapA React hook that manages a key-value Map as state.
useNetworkStatususeNetworkStatus is a React hook that provides access to the Network Information API.
useOutsideClickEffectuseOutsideClickEffect is a React hook that triggers a callback when a click event occurs outside the specified container(s).
usePageVisibilityusePageVisibility is a React hook that detects page visibility changes.
usePreservedCallbackusePreservedCallback is a React hook that maintains a stable reference to a callback function while ensuring it always has access to the latest state or props.
usePreservedReferenceusePreservedReference is a React hook that helps maintain the reference of a value when it hasn't changed, while ensuring you can safely use the latest state.
usePrevioususePrevious is a React hook that returns the previous value of the input state.
useRefEffectuseRefEffect is a React hook that helps you set a reference to a specific DOM element and execute a callback whenever the element changes.
useSafeAreaInsetuseSafeAreaInset is a React hook that tracks safe area inset changes.
useScrollDirectionuseScrollDirection is a React hook that detects scroll direction.
useSetA React hook that manages a Set as state.
useStorageStateuseStorageState is a React that functions like useState but persists the state value in browser storage.
useThrottleuseThrottle is a React hook that creates a throttled version of a callback function.
useThrottledCallbackuseThrottledCallback is a React hook that returns a throttled version of the provided callback function.
useThrottledValueuseThrottledValue is a React hook that returns a throttled copy of the given value.
useTimeoutuseTimeout is a React hook that executes a callback function after a specified delay.
useToggleuseToggle is a React hook that simplifies managing a boolean state.
useVisibilityEventuseVisibilityEvent is a React hook that listens to changes in the document's visibility state and triggers a callback.
useVisualViewportuseVisualViewport is a React hook that tracks Visual Viewport changes.

components

NameDescription
ImpressionAreaImpressionArea is a component that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport.
SeparatedSeparated is a component that inserts a specified component between each child element.
SwitchCaseSwitchCase is a component that allows you to declaratively render components based on a given value, similar to a switch-case statement.

utils

NameDescription
buildContextbuildContext is a helper function that reduces repetitive code when defining React Context.
disableBodyScrollLockdisableBodyScrollLock is a utility function that unlocks the body scroll.
enableBodyScrollLockenableBodyScrollLock is a utility function that locks the body scroll.
getKeyboardHeightgetKeyboardHeight is a utility function that returns the current on-screen keyboard height in pixels.
getSafeAreaInsetgetSafeAreaInset is a utility function that returns all safe area insets in pixels as an object.
isAndroidisAndroid is a utility function that detects whether the current device is running Android.
isIOSisIOS is a utility function that detects whether the current device is running iOS or iPadOS.
isKeyboardVisibleisKeyboardVisible is a utility function that checks whether the on-screen keyboard is currently visible.
isServerisServer is a utility function that checks if the code is running on the server.
mergePropsmergeProps is a utility function that merges multiple props objects into a single object.
mergeRefsThis function takes multiple refs (RefObject or RefCallback) and returns a single ref that updates all provided refs.
subscribeKeyboardHeightsubscribeKeyboardHeight is a utility function that subscribes to changes in the on-screen keyboard height.

Learn more

Sponsors

Details

Marketplace
toss/react-simplikit
Source
packages/plugin
Category
Community