@appswave/react-sdk

A reusable React SDK containing hooks and utilities for AppsWave projects.

Installation

npm install @appswave/react-sdk
# or
yarn add @appswave/react-sdk
# or
pnpm add @appswave/react-sdk

Peer Dependencies

This package requires React 18+ or 19+. Some hooks require additional peer dependencies:

Required

• react ^18.0.0 || ^19.0.0
• react-dom ^18.0.0 || ^19.0.0

Optional (for specific hooks)

• @tanstack/react-query ^5.0.0 - Required for React Query hooks
• @tanstack/react-table ^8.0.0 - Required for data table hooks
• nuqs ^2.0.0 - Required for URL state management hooks
• zod ^3.0.0 - Required for validation utilities
• html-to-image ^1.0.0 - Required for PDF utilities
• jspdf ^3.0.0 - Required for PDF utilities
• clsx ^2.0.0 - Required for Tailwind utilities
• tailwind-merge ^2.0.0 - Required for Tailwind utilities

Usage

Import Hooks

import { useDebounce, useClipboard, useStorage } from '@appswave/react-sdk';

Import Utilities

import { cn, persistData, getPersistentData } from '@appswave/react-sdk';

Import Types

import type { ExtendedSortingState, ResultDto } from '@appswave/react-sdk';

Hooks

Shared Hooks

useDebounce

Debounces a value, returning the latest value after a delay.

import { useDebounce } from '@appswave/react-sdk';

function MyComponent() {
  const [search, setSearch] = useState('');
  const debouncedSearch = useDebounce(search, 500);
  
  useEffect(() => {
    // Perform search with debouncedSearch
  }, [debouncedSearch]);
}

useClipboard

Hook for copying text to clipboard.

import { useClipboard } from '@appswave/react-sdk';

function MyComponent() {
  const { copied, copy } = useClipboard({
    timeout: 2000,
    onSuccess: () => console.log('Copied!'),
  });
  
  return (
    <button onClick={() => copy('Hello World')}>
      {copied ? 'Copied!' : 'Copy'}
    </button>
  );
}

useStorage

Hook for managing localStorage.

import { useStorage } from '@appswave/react-sdk';

function MyComponent() {
  const [value, setValue] = useStorage<string>('my-key', 'default');
  
  return (
    <input
      value={value}
      onChange={(e) => setValue(e.target.value)}
    />
  );
}

useMediaQuery

Hook for responsive breakpoint detection.

import { useMediaQuery } from '@appswave/react-sdk';

function MyComponent() {
  const { matchDownMD, matchUpLG, recalc } = useMediaQuery();
  
  return (
    <div>
      {matchDownMD && <p>Mobile view</p>}
      {matchUpLG && <p>Desktop view</p>}
    </div>
  );
}

useInfiniteScroll

Hook for infinite scroll functionality.

import { useInfiniteScroll } from '@appswave/react-sdk';

function MyComponent() {
  const loadMoreRef = useInfiniteScroll({
    onLoadMore: () => fetchMore(),
    hasMore: hasMore,
    isLoading: isLoading,
  });
  
  return <div ref={loadMoreRef}>Loading...</div>;
}

usePageVisibility

Hook to track page/tab visibility.

import { usePageVisibility } from '@appswave/react-sdk';

function MyComponent() {
  const { isTabActive } = usePageVisibility();
  
  return <div>{isTabActive ? 'Tab is active' : 'Tab is inactive'}</div>;
}

useShortcuts

Hook for keyboard shortcuts.

import { useShortcuts } from '@appswave/react-sdk';

function MyComponent() {
  useShortcuts({
    'ctrl+s': () => save(),
    'ctrl+z': () => undo(),
  });
}

Utility Hooks

useIsFetchingQuery

Hook to check if a React Query is currently fetching.

import { useIsFetchingQuery } from '@appswave/react-sdk';

function MyComponent() {
  const { isLoading } = useIsFetchingQuery('users');
  
  return isLoading ? <Spinner /> : <Content />;
}

useIsLoadingMutation

Hook to check if a React Query mutation is currently loading.

import { useIsLoadingMutation } from '@appswave/react-sdk';

function MyComponent() {
  const { isLoading } = useIsLoadingMutation('createUser');
  
  return (
    <button disabled={isLoading}>
      {isLoading ? 'Creating...' : 'Create User'}
    </button>
  );
}

Utilities

Tailwind Utilities

cn

Merge Tailwind CSS classes.

import { cn } from '@appswave/react-sdk';

<div className={cn('base-class', condition && 'conditional-class')} />

Storage Utilities

persistData

Persist data to localStorage.

import { persistData } from '@appswave/react-sdk';

persistData('key', { name: 'John' });

getPersistentData

Get persistent data from localStorage.

import { getPersistentData } from '@appswave/react-sdk';

const data = getPersistentData<{ name: string }>('key', { name: 'Default' });

API Utilities

pathBuilder

Build a path with parameters.

import { pathBuilder } from '@appswave/react-sdk';

const path = pathBuilder({
  path: '/users/:id/posts/:postId',
  pathParams: { id: 1, postId: 2 },
  queryParams: 'sort=desc',
});
// Returns: '/users/1/posts/2?sort=desc'

constructPlainRoutes

Construct plain routes from nested route objects.

import { constructPlainRoutes } from '@appswave/react-sdk';

const routes = {
  users: {
    list: '/users',
    detail: '/users/:id',
  },
};

const plainRoutes = constructPlainRoutes(routes);
// Returns: { users: { list: '/users', detail: '/users' } }

Media Utilities

downloadBlob

Download a blob as a file.

import { downloadBlob } from '@appswave/react-sdk';

const blob = new Blob(['content'], { type: 'text/plain' });
await downloadBlob(blob, 'file.txt');

Tree Shaking

This package supports tree-shaking. You can import specific hooks or utilities:

// ✅ Good - tree-shakeable
import { useDebounce } from '@appswave/react-sdk';

// ✅ Also good - tree-shakeable
import { useDebounce } from '@appswave/react-sdk/hooks';

// ❌ Avoid - imports everything
import * as SDK from '@appswave/react-sdk';

TypeScript

This package is written in TypeScript and includes type definitions. All exports are fully typed.

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.