@techstuff-dev/foundation-api-utils

Cross-platform React/React Native utility library providing shared API services, Redux store configuration, and platform utilities.

Features

• 🌐 Cross-platform: Works seamlessly across Next.js, React Native, and tvOS
• 🏪 Redux Toolkit: Pre-configured store with RTK Query for API management
• 🔐 Authentication: AWS Amplify integration with automatic token refresh
• 💾 Persistence: Platform-specific storage (localStorage/AsyncStorage)
• 🎯 Type-safe: Full TypeScript support with comprehensive types
• 📦 Tree-shakeable: Platform-conditional exports for optimized bundles
• 🧪 Well-tested: Jest testing infrastructure with comprehensive coverage

Installation

yarn add @techstuff-dev/foundation-api-utils

Peer Dependencies

yarn add react@^19.1.0 react-redux@^9.2.0

# For React Native projects:
yarn add react-native@^0.81.0 @react-native-async-storage/[email protected]

Usage

Main Export (Shared Utilities)

import { 
  // API Services
  authApi,
  contentApi,
  paymentsApi,
  ordersApi,
  
  // State Slices
  cartSlice,
  
  // Hooks
  useLoggedIn,
  
  // Utilities
  formatUserPayload,
  isWeb,
  isReactNative,
  getPlatform,
  runOnPlatform
} from '@techstuff-dev/foundation-api-utils';

Platform-Specific Store

The store automatically resolves to the correct platform implementation:

import { store, makeStore } from '@techstuff-dev/foundation-api-utils/store';

// Web: uses localStorage with redux-persist
// React Native: uses AsyncStorage with redux-persist

Platform-Specific Hooks

import { useAppDispatch, useAppSelector } from '@techstuff-dev/foundation-api-utils/hooks';

function MyComponent() {
  const dispatch = useAppDispatch();
  const user = useAppSelector((state) => state.auth.user);
  // ...
}

Platform Detection

import { isWeb, isReactNative, getPlatform, runOnPlatform } from '@techstuff-dev/foundation-api-utils';

// Check platform
if (isWeb()) {
  console.log('Running on web');
} else if (isReactNative()) {
  console.log('Running on React Native');
}

// Get platform string
const platform = getPlatform(); // 'web' | 'native' | 'unknown'

// Execute platform-specific code
const result = runOnPlatform({
  web: () => 'Web implementation',
  native: () => 'React Native implementation',
  default: () => 'Fallback implementation'
});

Environment Variables

Next.js (Web)

All environment variables must be prefixed with NEXT_PUBLIC_:

NEXT_PUBLIC_API_PREFIX=https://api.example.com
NEXT_PUBLIC_API_AUTH_PREFIX=https://auth.example.com
NEXT_PUBLIC_API_PAYMENTS_PREFIX=https://payments.example.com
NEXT_PUBLIC_API_ORDERS_PREFIX=https://orders.example.com

React Native

Uses react-native-config with no prefix required:

API_PREFIX=https://api.example.com
API_AUTH_PREFIX=https://auth.example.com
API_PAYMENTS_PREFIX=https://payments.example.com
API_ORDERS_PREFIX=https://orders.example.com

API Services

Authentication

import { authApi, useLoginMutation } from '@techstuff-dev/foundation-api-utils';

function LoginForm() {
  const [login, { isLoading }] = useLoginMutation();
  
  const handleLogin = async () => {
    await login({ username, password });
  };
  // ...
}

Content, Payments, Orders

All services follow RTK Query patterns with automatic caching and rehydration:

import { 
  useGetContentQuery,
  useCreatePaymentMutation,
  useGetOrdersQuery 
} from '@techstuff-dev/foundation-api-utils';

Cart Management

import { cartSlice } from '@techstuff-dev/foundation-api-utils';
import { useAppDispatch } from '@techstuff-dev/foundation-api-utils/hooks';

function ProductPage() {
  const dispatch = useAppDispatch();
  
  const addToCart = (item) => {
    dispatch(cartSlice.actions.addItem(item));
  };
  // ...
}

Architecture

Cross-Platform Design

The library uses platform-conditional exports in package.json:

• Main: Shared utilities, services, and hooks
• Store: Platform-specific Redux store with appropriate persistence
• Hooks: Platform-specific typed hooks for Redux

Platform Detection System

Robust multi-check detection using:

• React Native global checks
• Metro bundler detection
• Next.js environment detection
• Navigator API checks

Build Output

• CommonJS: dist/cjs/ - For legacy module systems
• ESM: dist/esm/ - For modern bundlers
• Types: dist/types/ - TypeScript declarations

Development

Commands

# Build the library
yarn build

# Run tests
yarn test
yarn test:watch
yarn test:coverage

# Linting
yarn lint
yarn lint:fix

# Type checking
yarn tsc

Testing

The library includes a comprehensive Jest setup with:

• TypeScript support via ts-jest
• jsdom environment for DOM testing
• React Native module mocks
• Coverage reporting

yarn test

Contributing

This library uses:

• Semantic versioning: Automated via semantic-release
• Conventional commits: Required for version bumps
• ESLint v9: Flat config format with TypeScript support
• Yarn 4.6.0: Package manager

Commit Format

feat: add new feature
fix: resolve bug
chore: update dependencies
docs: update documentation

License

ISC

Links

• WARP.md - Comprehensive development guide
• NPM Package

TEST

• bump version