FlowerKit 🌸 TypeScript Utilities for Browser APIs, DOM Events, and SSR

100+ typed, tree-shakable utilities for frontend applications. FlowerKit combines DOM and browser helpers with the array, object, string, date, function, and network utilities that application code uses every day.

Why FlowerKit?

• Browser-focused helpers for DOM events, observers, storage, cookies, network requests, and CSS
• SSR-safe fallbacks for utilities that normally depend on window or document
• TypeScript types for every public function, including exported argument and return types
• Tree-shakable ESM subpath imports, CommonJS support, and sideEffects: false
• Cancelable debounce and throttle controls, typed request errors, and explicit listener cleanup
• Runtime input validation and 100+ colocated test suites

Install

npm i @web3r/flowerkit

Also works with pnpm add @web3r/flowerkit and yarn add @web3r/flowerkit.

Quick start

Handle clicks outside an element

import { onClickOutside } from "@web3r/flowerkit/evt";

const menu = document.querySelector("[data-menu]");

if (menu) {
  const outside = onClickOutside(menu, () => menu.removeAttribute("open"));

  // Call this from your framework's unmount hook.
  const disposeMenu = () => outside.removeListener();
}

Debounce with lifecycle controls

import { getDebouncedFn } from "@web3r/flowerkit/fn";

const search = getDebouncedFn((query: string) => {
  console.log(query);
}, 300);

search("flower");
search("flowerkit");

search.pending(); // true
search.flush();   // run the pending call immediately
search.cancel();  // or discard a pending call during cleanup

Use typed, SSR-safe storage

import { createStorage } from "@web3r/flowerkit/user";

const settings = createStorage<{
  locale: "en" | "ru";
  theme: "dark" | "light";
}>({ namespace: "settings" });

settings.set("theme", "dark");
const theme = settings.get("theme", "light");

Handle typed request failures

import { getFromServer } from "@web3r/flowerkit/net";
import type { TGetFromServerError } from "@web3r/flowerkit/net";

try {
  const user = await getFromServer<{ id: number; name: string }>({
    url: "/api/user/1",
  });
  console.log(user.name);
} catch (error) {
  if (error instanceof Error && error.name === "GetFromServerError") {
    const requestError = error as TGetFromServerError;
    console.error(requestError.kind, requestError.status);
  }
}

Imports

Prefer kit subpaths so bundlers can include only the utilities that are used:

// ESM
import { getUniqueBy } from "@web3r/flowerkit/arr";
import { onIntersection, onSwipe } from "@web3r/flowerkit/evt";

// Namespace kits
import { arrKit, evtKit } from "@web3r/flowerkit";

// CommonJS
const { getUniqueBy } = require("@web3r/flowerkit/arr");

// Public types
import type { TOnSwipeArgs, TOnSwipeReturn } from "@web3r/flowerkit/evt";

Compatibility

| Environment | Support | | --- | --- | | Node.js | 22 and 24, verified in CI | | Browser output | Compiled against the package's browserslist configuration | | Server-side rendering | SSR-safe entry points verified without browser globals | | Modules | ESM and CommonJS | | TypeScript | Bundled declarations for the root package and every kit subpath |

FlowerKit is framework-independent and can be used with React, Vue, Svelte, other frameworks, or vanilla TypeScript.

Bundle-size checks

Representative imports are bundled, minified, compressed with gzip, and checked against regression budgets in CI:

| Import | Minified | Minified + gzip | CI limit (gzip) | | --- | ---: | ---: | ---: | | getDebouncedFn | 0.71 kB | 0.37 kB | 0.49 kB | | onClickOutside | 1.78 kB | 0.84 kB | 1.07 kB | | createStorage | 1.42 kB | 0.63 kB | 0.83 kB | | getFromServer | 6.68 kB | 2.70 kB | 3.42 kB |

Run npm run size to print the current measured values. Run npm run verify:size to enforce the budgets.

Kits

| Import path | Purpose | | --- | --- | | @web3r/flowerkit/arr | Arrays, iterables, grouping, sets, and async mapping | | @web3r/flowerkit/css | CSS values, variables, selectors, media queries, and transforms | | @web3r/flowerkit/date | Date validation, arithmetic, formatting, and differences | | @web3r/flowerkit/dom | DOM nodes, HTML parsing, siblings, wrappers, and cleanup | | @web3r/flowerkit/evt | DOM lifecycle events, outside clicks, swipe, resize, media, and intersection observers | | @web3r/flowerkit/fn | Async pools, curry, debounce, throttle, memoization, retry, and timing | | @web3r/flowerkit/json | JSON parsing and validation | | @web3r/flowerkit/net | Typed fetch, query parameters, FormData, and external scripts | | @web3r/flowerkit/num | Clamping, formatting, ranges, rounding, minimum, and maximum | | @web3r/flowerkit/obj | Deep clone, equality, merge, fallback, pick, omit, and cleanup | | @web3r/flowerkit/str | Case conversion, slugging, escaping, truncation, IDs, and formatting | | @web3r/flowerkit/user | SSR-safe storage, clipboard, cookies, devices, and viewport helpers |

See the complete API reference and the generated reference for each kit.

Quality and package verification

Current coverage from the built-in Node.js coverage runner:

| Metric | Current | Enforced minimum | | --- | ---: | ---: | | Lines | 93.71% | 90% | | Branches | 85.15% | 80% | | Functions | 94.93% | 90% |

The current npm artifact is approximately 254 kB compressed and 977 kB unpacked. CI limits the artifact to 280,000 compressed bytes, 1,050,000 unpacked bytes, and 650 files so packaging regressions require an explicit decision.

Every pull request is checked with:

• ESLint and strict TypeScript type checking
• the Node.js test runner in Node.js 22 and 24
• browser-global-free SSR import tests
• ESM, CommonJS, declaration, and subpath smoke tests against the actual npm tarball
• production dependency audit
• representative bundle-size regression budgets

The package tarball is restricted to runtime output and project documentation. Run npm run verify:package to install the packed artifact into a temporary consumer project and verify all public entry points.

Contributing

Bug reports, use cases, documentation improvements, and focused utility proposals are welcome. Read CONTRIBUTING.md before opening a pull request. Security issues should follow SECURITY.md.

Before opening a pull request, run:

npm run lint
npm run typecheck
npm test
npm run build
npm run verify:package

License

MIT © Yuri Moskvin