This guide covers common issues you might encounter when building restaurant applications with CraveJS and provides step-by-step solutions. ## Installation Issues ### Package Resolution Errors **Problem**: Import errors or "Module not found" when using CraveJS components. ```bash Error: Cannot resolve module '@cravejs/restaurant' ``` **Solutions**: 1. **Verify Installation** ```bash npm list @cravejs/restaurant @cravejs/ui # or pnpm list @cravejs/restaurant @cravejs/ui ``` 2. **Check package.json Dependencies** ```json { "dependencies": { "@cravejs/restaurant": "latest", "@cravejs/ui": "latest" } } ``` 3. **Clear Cache and Reinstall** ```bash # For npm rm -rf node_modules package-lock.json npm install # For pnpm rm -rf node_modules pnpm-lock.yaml pnpm install ``` 4. **Check Import Paths** ```tsx // ✅ Correct import { MenuItemCard } from '@cravejs/restaurant' import { Button } from '@cravejs/ui' // ❌ Incorrect import { MenuItemCard } from '@cravejs/restaurant/menu' ``` ### TypeScript Configuration Issues **Problem**: TypeScript errors with CraveJS components. **Solution**: Update your `tsconfig.json`: ```json { "compilerOptions": { "moduleResolution": "node", "esModuleInterop": true, "allowSyntheticDefaultImports": true, "jsx": "react-jsx", "paths": { "@/*": ["./src/*"], "@/components/*": ["./src/components/*"], "@/lib/*": ["./src/lib/*"] } }, "include": [ "src/**/*", "node_modules/@cravejs/*/dist/**/*.d.ts" ] } ``` ## Component Issues ### Styling Problems **Problem**: Components don't display correctly or styles are missing. **Solutions**: 1. **Verify CSS Import** ```tsx // In your main App.tsx or _app.tsx import '@cravejs/ui/dist/styles.css' // or if using Tailwind import './globals.css' ``` 2. **Check Tailwind Configuration** ```js // tailwind.config.js module.exports = { content: [ './src/**/*.{js,ts,jsx,tsx}', './node_modules/@cravejs/**/*.{js,ts,jsx,tsx}' // Add this ], // ... rest of config } ``` 3. **CSS Module Conflicts** ```tsx // If using CSS modules, ensure proper className handling import { cn } from '@/lib/utils' ``` ### Menu Item Card Not Responsive **Problem**: Menu cards don't resize properly on mobile devices. **Solution**: ```tsx // ✅ Use responsive grid

{menuItems.map(item => ( ))}

// ✅ Or use responsive container

{/* Cards will automatically wrap */}

``` ### Cart State Not Persisting **Problem**: Cart items disappear after page refresh. **Solution**: Implement proper state persistence: ```tsx // Using Zustand with persistence import { persist } from 'zustand/middleware' export const useCartStore = create( persist( (set, get) => ({ items: [], addItem: (item) => set((state) => ({ items: [...state.items, item] })), // ... other actions }), { name: 'restaurant-cart', // localStorage key partialize: (state) => ({ items: state.items }), // Only persist items } ) ) // Handle hydration in Next.js function CartProvider({ children }) { const [isHydrated, setIsHydrated] = useState(false) useEffect(() => { setIsHydrated(true) }, []) if (!isHydrated) { return

} return children } ``` ## Performance Issues ### Slow Menu Loading **Problem**: Menu takes too long to load or appears sluggish. **Solutions**: 1. **Implement Virtualization** ```tsx import { FixedSizeList as List } from 'react-window' function VirtualizedMenu({ items }) { const Row = ({ index, style }) => (

) return ( {Row} ) } ``` 2. **Add Skeleton Loading** ```tsx function MenuSkeleton() { return (

{Array.from({ length: 6 }).map((_, i) => (

))}

) } ``` 3. **Optimize Images** ```tsx import Image from 'next/image' {item.name}

``` ### Memory Leaks **Problem**: App becomes slower over time, especially with cart operations. **Solution**: Proper cleanup and memoization: ```tsx // ✅ Memoize expensive calculations const menuTotal = useMemo(() => { return items.reduce((sum, item) => sum + item.price * item.quantity, 0) }, [items]) // ✅ Clean up subscriptions useEffect(() => { const unsubscribe = cartStore.subscribe((state) => { updateCartBadge(state.items.length) }) return unsubscribe // Cleanup }, []) // ✅ Use React.memo for expensive components const MenuItemCard = React.memo(({ item, onSelect }) => { return (

onSelect(item)}> {/* Component content */}

) }, (prevProps, nextProps) => { // Custom comparison return prevProps.item.id === nextProps.item.id }) ``` ## API Integration Issues ### Failed Cart Updates **Problem**: Cart updates fail or don't sync with the server. **Solution**: Implement robust error handling: ```tsx export function useCartMutations() { const queryClient = useQueryClient() return useMutation({ mutationFn: async (cartData) => { const response = await fetch('/api/cart', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(cartData) }) if (!response.ok) { throw new Error(`HTTP ${response.status}: ${response.statusText}`) } return response.json() }, // Optimistic updates onMutate: async (newCartData) => { await queryClient.cancelQueries(['cart']) const previousCart = queryClient.getQueryData(['cart']) queryClient.setQueryData(['cart'], newCartData) return { previousCart } }, // Rollback on error onError: (err, newCartData, context) => { queryClient.setQueryData(['cart'], context.previousCart) toast.error('Failed to update cart. Please try again.') }, // Refetch on success or error onSettled: () => { queryClient.invalidateQueries(['cart']) }, }) } ``` ### Authentication Issues **Problem**: User authentication fails or tokens expire. **Solution**: Implement token refresh logic: ```tsx // API interceptor for token handling const apiClient = axios.create({ baseURL: process.env.NEXT_PUBLIC_API_URL }) apiClient.interceptors.request.use((config) => { const token = localStorage.getItem('authToken') if (token) { config.headers.Authorization = `Bearer ${token}` } return config }) apiClient.interceptors.response.use( (response) => response, async (error) => { if (error.response?.status === 401) { // Try to refresh token try { const refreshToken = localStorage.getItem('refreshToken') const response = await fetch('/api/auth/refresh', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ refreshToken }) }) if (response.ok) { const { accessToken } = await response.json() localStorage.setItem('authToken', accessToken) // Retry original request error.config.headers.Authorization = `Bearer ${accessToken}` return apiClient.request(error.config) } } catch (refreshError) { // Redirect to login window.location.href = '/login' } } return Promise.reject(error) } ) ``` ## Mobile Issues ### Touch Events Not Working **Problem**: Touch interactions don't work properly on mobile devices. **Solution**: Implement proper touch event handling: ```tsx function TouchableMenuCard({ item, onSelect }) { const [isPressed, setIsPressed] = useState(false) const handleTouchStart = () => { setIsPressed(true) } const handleTouchEnd = () => { setIsPressed(false) onSelect(item) } const handleTouchCancel = () => { setIsPressed(false) } return (

{/* Card content */}

) } ``` ### Viewport Issues **Problem**: Components don't scale properly on different screen sizes. **Solution**: Use proper viewport configuration: ```html ``` ```css /* Prevent zoom on input focus (iOS) */ input, select, textarea { font-size: 16px; } /* Safe area support for notched devices */ .safe-area { padding-top: env(safe-area-inset-top); padding-bottom: env(safe-area-inset-bottom); padding-left: env(safe-area-inset-left); padding-right: env(safe-area-inset-right); } ``` ## Payment Integration Issues ### Payment Modal Not Opening **Problem**: Payment modal or checkout flow doesn't work. **Solution**: Check payment provider integration: ```tsx // Stripe example useEffect(() => { const loadStripe = async () => { if (!window.Stripe) { const stripe = await import('@stripe/stripe-js') window.stripePromise = stripe.loadStripe(process.env.NEXT_PUBLIC_STRIPE_KEY) } } loadStripe() }, []) // Handle payment with error boundaries async function handlePayment() { try { const stripe = await window.stripePromise if (!stripe) { throw new Error('Stripe failed to load') } const { error } = await stripe.confirmCardPayment(clientSecret, { payment_method: { card: cardElement, billing_details: { name: customerName } } }) if (error) { setPaymentError(error.message) } else { // Payment succeeded router.push('/order-confirmation') } } catch (err) { setPaymentError('Payment processing failed. Please try again.') } } ``` ## Browser Compatibility ### Internet Explorer Issues **Problem**: Components don't work in older browsers. **Solution**: Add polyfills and fallbacks: ```bash # Install polyfills npm install core-js whatwg-fetch ``` ```tsx // In your main entry file import 'core-js/stable' import 'whatwg-fetch' // Conditional polyfills if (!window.IntersectionObserver) { import('intersection-observer') } if (!window.ResizeObserver) { import('@juggle/resize-observer').then(module => { window.ResizeObserver = module.ResizeObserver }) } ``` ### Safari Issues **Problem**: Animations or layouts break in Safari. **Solution**: Add Safari-specific CSS: ```css /* Fix flexbox issues in Safari */ .flex-container { display: -webkit-flex; display: flex; -webkit-flex-direction: column; flex-direction: column; } /* Fix sticky positioning */ .sticky { position: -webkit-sticky; position: sticky; } /* Prevent bounce scrolling */ body { overscroll-behavior: none; -webkit-overflow-scrolling: touch; } ``` ## Common Error Messages ### "React Hook called conditionally" **Problem**: ``` React Hook "useState" is called conditionally ``` **Solution**: Always call hooks at the top level: ```tsx // ❌ Wrong function MenuComponent({ showCart }) { if (showCart) { const [cartItems, setCartItems] = useState([]) } // ... } // ✅ Correct function MenuComponent({ showCart }) { const [cartItems, setCartItems] = useState([]) if (!showCart) { return null } // ... } ``` ### "Cannot read property of undefined" **Problem**: Accessing properties on undefined objects. **Solution**: Add proper null checks: ```tsx // ❌ Risky function MenuCard({ item }) { return

{item.name}

} // ✅ Safe function MenuCard({ item }) { if (!item) return null return (

{item.name}

{item.description || 'No description available'}

${item.price?.toFixed(2) || '0.00'}

) } // ✅ With optional chaining function MenuCard({ item }) { return (

{item?.name || 'Unknown Item'}

{item?.description}

${item?.price?.toFixed(2)}

) } ``` ## Getting Help If you're still experiencing issues: 1. **Check the Console**: Look for JavaScript errors in your browser's developer console 2. **Verify Network Requests**: Check the Network tab for failed API calls 3. **Test in Isolation**: Create a minimal reproduction of the issue 4. **Check Documentation**: Review the component documentation for proper usage 5. **Search Issues**: Look through existing GitHub issues for similar problems 6. **Create a Bug Report**: If the issue persists, create a detailed bug report with: - Steps to reproduce - Expected vs actual behavior - Browser and version - Code samples - Console errors ### Debug Mode Enable debug mode for additional logging: ```tsx // Add to your app if (process.env.NODE_ENV === 'development') { window.CRAVEJS_DEBUG = true } // Components will log additional information ``` Remember: Most issues are configuration-related. Double-check your setup before diving into complex debugging!

Troubleshooting