React BuildKit

A comprehensive TypeScript utility library for React applications with Capacitor integration for cross-platform mobile development. Provides helper functions, hooks, form validation, storage utilities, and more.

📚 Documentation

• Getting Started Guide - Installation, setup, and first usage
• API Reference - Complete list of all exports with descriptions
• Core Concepts - Understanding the library architecture
• Examples - Real-world usage examples
• Migration Guide - Migrating from ts-react-toolkits
• FAQ - Common questions and troubleshooting

✨ Features

🧩 Utility Functions

• Form Validation - Comprehensive validation rules with Zod integration
• Storage Management - Secure storage using Capacitor Preferences API (never localStorage)
• API Response Formatting - Consistent API response handling
• String Utilities - Text manipulation, ID generation, case conversion
• Data Filtering & Pagination - Built-in data filtering and pagination helpers

🪝 Custom React Hooks

• useZMediaQueryScale - Responsive design hook with scale detection
• useZFormikContext - Enhanced Formik context with TypeScript support
• useZDropzone - File upload management with React Dropzone

📱 Capacitor Integration

• Platform Detection - Detect web, iOS, Android, and hybrid environments
• Native APIs - Toast, Dialog, Browser, Clipboard, Geolocation wrappers
• Permission Management - Check and request permissions
• Cross-platform Storage - Encrypted storage with Capacitor Preferences

📦 Component Wrappers

• ZFormik - Enhanced Formik components with TypeScript
• ZDropzone - File upload with drag-and-drop support
• ZReactStars - Star rating component
• ZClassNames - Conditional class name utility

🔧 Configuration

• configureZRTK - Global configuration for the library
• Environment Constants - API URLs, routes, storage keys
• React Query Options - Pre-configured options for data fetching

🚀 Installation

# Using yarn (recommended)
yarn add react-buildkit

# Using npm
npm install react-buildkit

Peer Dependencies

This package requires the following peer dependencies:

{
  "react": "^18.3.1 | ^19.1.0",
  "@capacitor/core": "^7.4.2",
  "@capacitor/preferences": "^7.0.1",
  "formik": "^2.4.6",
  "zod": "^4.0.5"
}

Install all required dependencies:

yarn add react react-buildkit @capacitor/core @capacitor/preferences formik zod

🎯 Quick Start

1. Configure the Library

import { configureZRTK } from 'react-buildkit';

// Configure at your app's entry point
configureZRTK({
  apiUrl: 'https://api.yourdomain.com',
  environment: 'production',
  enableLogging: true
});

2. Use Storage Utilities

import { STORAGE } from 'react-buildkit';

// Save data securely
await STORAGE.set('user_preferences', { theme: 'dark' });

// Retrieve data
const preferences = await STORAGE.get('user_preferences');

// Remove data
await STORAGE.remove('user_preferences');

3. Form Validation

import { validateField, zValidationRuleE } from 'react-buildkit';

// Validate a single field
const emailError = validateField('[email protected]', [
  { rule: zValidationRuleE.REQUIRED },
  { rule: zValidationRuleE.EMAIL }
]);

// Use with Formik
import { ZFormik, ZFormikForm } from 'react-buildkit';

<ZFormik
  initialValues={{ email: '' }}
  onSubmit={(values) => console.log(values)}
>
  <ZFormikForm>
    {/* Your form fields */}
  </ZFormikForm>
</ZFormik>

4. Platform Detection

import { isCapWeb, isCapMobileApp, isCapIOS, isCapAndroid } from 'react-buildkit';

if (isCapMobileApp) {
  // Mobile-specific code
  if (isCapIOS) {
    // iOS-specific code
  } else if (isCapAndroid) {
    // Android-specific code
  }
} else if (isCapWeb) {
  // Web-specific code
}

5. Native Toasts and Dialogs

import { showToast, showZAlert, showZConfirm } from 'react-buildkit';

// Show a toast
await showToast('Operation successful!', 'success');

// Show an alert
await showZAlert('Warning', 'This action cannot be undone');

// Show a confirmation dialog
const confirmed = await showZConfirm('Delete Item', 'Are you sure?');
if (confirmed) {
  // Perform deletion
}

🔑 Key Principles

1. Capacitor First - Built for cross-platform development with Capacitor
2. Type Safety - Full TypeScript support with comprehensive types
3. Storage Security - Always uses Capacitor Preferences, never localStorage
4. Modular Design - Import only what you need
5. React Best Practices - Follows React patterns and conventions

📖 Advanced Usage

For more advanced usage examples and detailed API documentation, please refer to our comprehensive documentation.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Ahsan Mahmood

• Email: [email protected]
• Website: https://aoneahsan.com
• GitHub: @aoneahsan

🆘 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

🙏 Acknowledgments

Special thanks to all contributors and the open-source community for making this project possible.