Guides and Tutorials

Step-by-step guides for common tasks and features.

Getting Started

Installation

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Run development server
npm run dev

Project Structure

├── app/                    # Next.js app directory
│   ├── layout.tsx         # Root layout
│   ├── page.tsx           # Home page
│   └── [routes]/          # App routes
├── components/            # React components
│   ├── UI/                # UI components
│   └── [components]      # Feature components
├── hooks/                 # Custom React hooks
├── lib/                   # Utility libraries
├── types/                 # TypeScript types
└── public/                # Static files

Feature Guides

1. Adding Internationalization

Step 1: Import the i18n hook

import { useI18n } from '@/hooks/useI18n';

Step 2: Use translations in your component

function MyComponent() {
  const { t, locale, changeLocale } = useI18n();

  return (
    <div>
      <p>{t('common.loading')}</p>
      <button onClick={() => changeLocale('de')}>Deutsch</button>
    </div>
  );
}

Step 3: Add translations

import { i18n } from '@/lib/i18n';

i18n.addTranslations('de', {
  myFeature: {
    title: 'Mein Titel',
    description: 'Meine Beschreibung',
  },
});

2. Implementing Search

Step 1: Import search utilities

import { searchApps, advancedSearch } from '@/lib/search';
import { advancedSearch as advanced } from '@/lib/advanced-search';

Step 2: Basic search

function SearchComponent() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  useEffect(() => {
    const results = searchApps(apps, query, {
      threshold: 0.3,
      limit: 50,
      fuzzy: true,
    });
    setResults(results);
  }, [query]);

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
      />
      {results.map((result) => (
        <div key={result.app.id}>{result.app.title}</div>
      ))}
    </div>
  );
}

Step 3: Advanced search with filters

const results = advancedSearch(apps, {
  query: 'search term',
  filters: {
    tags: ['productivity'],
    minRating: 4,
  },
  sortBy: 'rating',
  limit: 20,
});

3. Using Forms

Step 1: Use the form hook

import { useForm } from '@/hooks/useForm';

function MyForm() {
  const { values, handleChange, handleSubmit, errors, isSubmitting } = useForm({
    initialValues: {
      email: '',
      password: '',
    },
    validation: {
      email: { required: true, email: true },
      password: { required: true, minLength: 8 },
    },
    onSubmit: async (values) => {
      // Submit form
      await submitForm(values);
    },
  });

  return (
    <form onSubmit={handleSubmit}>
      <input
        name="email"
        value={values.email}
        onChange={handleChange}
      />
      {errors.email && <span>{errors.email}</span>}
      
      <input
        type="password"
        name="password"
        value={values.password}
        onChange={handleChange}
      />
      {errors.password && <span>{errors.password}</span>}
      
      <button type="submit" disabled={isSubmitting}>
        Submit
      </button>
    </form>
  );
}

4. Implementing Notifications

Step 1: Import notifications

import { notifications } from '@/lib/notifications';

Step 2: Show notifications

// Success notification
notifications.success('Success!', 'Operation completed successfully');

// Error notification (doesn't auto-dismiss)
notifications.error('Error!', 'Something went wrong');

// Warning notification
notifications.warning('Warning!', 'Please check your input');

// Info notification
notifications.info('Info', 'New update available');

// Custom notification
notifications.show({
  type: 'success',
  title: 'Custom',
  message: 'Custom message',
  duration: 3000,
  action: {
    label: 'Undo',
    onClick: () => {
      // Handle action
    },
  },
});

5. Using Modals

Step 1: Create modal state

const [isOpen, setIsOpen] = useState(false);

Step 2: Use Modal component

import Modal from '@/components/Modal';

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="My Modal"
  size="md"
>
  <p>Modal content</p>
</Modal>

6. Data Fetching with Caching

Step 1: Use data fetch hook

import { useDataFetch } from '@/hooks/useDataFetch';

function DataComponent() {
  const { data, isLoading, error, refetch } = useDataFetch('/api/data', {
    cache: {
      strategy: 'stale-while-revalidate',
      ttl: 60000,
    },
    retries: 3,
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return <div>{JSON.stringify(data)}</div>;
}

7. Keyboard Shortcuts

Step 1: Register shortcut

import { useKeyboardShortcut } from '@/hooks/useKeyboardShortcut';

function MyComponent() {
  useKeyboardShortcut({
    key: 'k',
    ctrl: true,
    action: () => {
      // Handle shortcut
      openSearch();
    },
    description: 'Open search',
  });

  return <div>Press Ctrl+K to open search</div>;
}

8. Image Optimization

Step 1: Import utilities

import { getOptimizedImageUrl, compressImage } from '@/lib/image-handling';

Step 2: Optimize images

// Get optimized URL
const optimizedUrl = getOptimizedImageUrl('/image.jpg', {
  width: 800,
  quality: 80,
  format: 'webp',
});

// Compress uploaded image
const handleFileUpload = async (file: File) => {
  const compressed = await compressImage(file, 1920, 1080, 0.8);
  // Upload compressed image
};

9. Error Handling

Step 1: Wrap app in error boundary

import { ErrorBoundaryAdvanced } from '@/components/ErrorBoundaryAdvanced';

<ErrorBoundaryAdvanced>
  <App />
</ErrorBoundaryAdvanced>

Step 2: Register recovery strategies

import { errorRecovery } from '@/lib/error-recovery';

errorRecovery.register({
  name: 'network-retry',
  priority: 10,
  canRecover: (error) => error.message.includes('network'),
  recover: async () => {
    // Retry logic
  },
});

10. State Persistence

Step 1: Use persisted state hook

import { usePersistedState } from '@/hooks/usePersistedState';

function MyComponent() {
  const [state, setState] = usePersistedState('my-state', {
    value: 'initial',
  });

  return (
    <div>
      <input
        value={state.value}
        onChange={(e) => setState({ ...state, value: e.target.value })}
      />
    </div>
  );
}

Best Practices

Performance

1. Lazy load components

   import dynamic from 'next/dynamic';
   
   const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
     loading: () => <LoadingState />,
   });
   

2. Use caching

   const data = await advancedCache.get('key', fetcher, {
     strategy: 'cache-first',
     ttl: 60000,
   });
   

3. Optimize images

   import Image from 'next/image';
   
   <Image
     src="/image.jpg"
     width={800}
     height={600}
     alt="Description"
     loading="lazy"
   />
   

Accessibility

1. Use semantic HTML
2. Add ARIA labels
3. Ensure keyboard navigation
4. Test with screen readers

Security

1. Sanitize user input

   import { sanitizeHTML } from '@/lib/security-advanced';
   
   const safe = sanitizeHTML(userInput);
   

2. Validate URLs

   import { validateURL } from '@/lib/security-advanced';
   
   if (validateURL(url, ['example.com'])) {
     // Safe to use
   }
   

3. Use rate limiting

   import { rateLimiter } from '@/lib/rate-limit';
   
   const result = rateLimiter.check('user-id', 100, 60000);
   if (!result.allowed) {
     // Rate limited
   }
   

Troubleshooting

Common Issues

1. Modal not closing

   • Check if onClose is properly set
   • Ensure isOpen state is managed correctly

2. Translations not working

   • Verify locale is set: i18n.setLocale('de')
   • Check if translations are added

3. Caching not working

   • Check cache strategy
   • Verify TTL is set correctly

4. Error boundary not catching errors

   • Ensure error boundary wraps components
   • Check if error is thrown in render

Examples

See the /examples directory for complete working examples of all features.