Vibra React

A lightweight, type-safe React integration for Vibra state management.

Documentation • Storybook • Report Bug • Request Feature

✨ Features

• 🎯 Type-Safe: Full TypeScript support with proper type inference
• 🚀 Lightweight: Minimal bundle size with no external dependencies
• 🧪 Tested: Comprehensive test coverage with Jest and React Testing Library
• 📚 Documented: Detailed documentation with Storybook
• 🛠 Developer Experience: Hot reload, TypeScript support, and comprehensive tooling

📦 Installation

# Using npm
npm install vibra-react vibra

# Using yarn
yarn add vibra-react vibra

# Using pnpm
pnpm add vibra-react vibra

# Using bun
bun add vibra-react vibra

🔨 Core API

VibraInitializer

A React component that initializes Vibra stores with their initial values.

import { VibraInitializer } from 'vibra-react';
import vibra from 'vibra';

// Create your stores
const counterStore = vibra<number>(0);
const userStore = vibra<{ name: string; age: number }>({ name: '', age: 0 });

function App() {
  return (
    <VibraInitializer
      stores={[
        [counterStore, 42],
        [userStore, { name: 'John', age: 30 }]
      ]}
    />
  );
}

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | stores | [ReturnType<typeof vibra<T>>, T][] | Yes | Array of tuples containing store and initial value pairs |

useVibra Hook

A React hook that provides a type-safe way to subscribe to Vibra stores.

import { useVibra } from 'vibra-react';

function Counter() {
  const count = useVibra(counterStore);
  
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => counterStore.set(count + 1)}>
        Increment
      </button>
    </div>
  );
}

🚀 Quick Start

1. Create your stores

   // stores/counter.ts
   import vibra from 'vibra';
      
   export const counterStore = vibra<number>(0);
      
   // stores/user.ts
   import vibra from 'vibra';
      
   export interface User {
     name: string;
     age: number;
   }
      
   export const userStore = vibra<User>({ name: '', age: 0 });

2. Initialize stores in your app

   // App.tsx
   import { VibraInitializer } from 'vibra-react';
   import { counterStore, userStore } from './stores';
      
   function App() {
     return (
       <VibraInitializer
         stores={[
           [counterStore, 0],
           [userStore, { name: 'John', age: 30 }]
         ]}
       >
         <YourApp />
       </VibraInitializer>
     );
   }

3. Use stores in your components

   // Counter.tsx
   import { useVibra } from 'vibra-react';
   import { counterStore } from './stores';
      
   function Counter() {
     const count = useVibra(counterStore);
        
     return (
       <div>
         <p>Count: {count}</p>
         <button onClick={() => counterStore.set(count + 1)}>
           Increment
         </button>
       </div>
     );
   }

🎯 Best Practices

Store Organization

1. Keep stores in a dedicated directory

   src/
     stores/
       counter.ts
       user.ts
       auth.ts
       index.ts  // Export all stores

2. Use meaningful names and types

   // stores/auth.ts
   import vibra from 'vibra';
      
   export interface AuthState {
     isAuthenticated: boolean;
     user: User | null;
   }
      
   export const authStore = vibra<AuthState>({
     isAuthenticated: false,
     user: null
   });

Type Safety

1. Always define interfaces for complex types

   interface Todo {
     id: string;
     text: string;
     completed: boolean;
   }
      
   const todoStore = vibra<Todo[]>([]);

2. Use type guards when needed

   function isUser(value: unknown): value is User {
     return (
       typeof value === 'object' &&
       value !== null &&
       'name' in value &&
       'age' in value
     );
   }

Performance

1. Initialize stores early in your app

   // App.tsx
   function App() {
     return (
       <VibraInitializer stores={[...]}>
         <Router>
           <Routes>
             {/* Your routes */}
           </Routes>
         </Router>
       </VibraInitializer>
     );
   }

2. Use the hook only where needed

   // Only subscribe to the store in components that need it
   function UserProfile() {
     const user = useVibra(userStore);
     return <div>{user.name}</div>;
   }

🧪 Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

🛠 Development

# Install dependencies
npm install

# Start development server
npm run dev

# Start Storybook
npm run storybook

# Build the library
npm run build

# Run linter
npm run lint

# Run type checking
npm run type-check

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• React
• TypeScript
• Vibra
• Storybook
• Jest
• Testing Library

📞 Support

• GitHub Issues
• Documentation
• Email Support