--- name: libraries-dependencies-mastery description: Complete mastery of essential modern web development libraries and dependencies. Cover Next.js, React, TypeScript, Tailwind CSS, Firebase, Zustand, redux-toolkit, react-hook-form, Zod, shadcn/ui, lucide-react, Stripe, and more. Learn setup, integration patterns, advanced usage, performance optimization, troubleshooting, common pitfalls, and version management. Includes quick reference guides, in-depth tutorials, complete examples for e-commerce and SaaS, configuration files, type definitions, error handling, and production patterns. Master how libraries work together and solve real-world challenges. --- # Libraries & Dependencies Mastery ## Overview You are an expert in modern web development libraries and their integration. This skill provides complete mastery of the essential libraries powering modern full-stack applications: **Next.js**, **React**, **TypeScript**, **Tailwind CSS**, **Firebase**, **State Management** (Zustand, Redux Toolkit), **Forms** (react-hook-form, Zod), **UI/UX** (shadcn/ui, lucide-react), and **Payments** (Stripe). Learn setup, configuration, integration patterns, advanced usage, performance optimization, troubleshooting, version management, and common pitfalls. ## Core Library Mastery ### 1. Next.js 13+ Complete Mastery **Setup & Configuration:** - Installation and project initialization - tsconfig.json configuration for strict TypeScript - next.config.js customization - Environment variables (.env, .env.local, .env.production) - Path aliases (@/ imports) - Monorepo setup with workspaces **App Router (Next.js 13+):** - File-based routing structure - Route segments and dynamic routes ([id], [...slug]) - Route groups and layouts ((auth), (dashboard)) - Parallel routes and intercepting routes - Loading states and error boundaries - Not found and error.js pages - Middleware and request handling - Route handlers (GET, POST, PUT, DELETE, PATCH) - Server Components vs Client Components - Suspense and streaming - Data fetching patterns (fetch, cache tags) - Revalidation strategies (ISR, on-demand) **Performance Optimization:** - Image optimization with next/image - Font optimization - Script optimization and loading strategies - Dynamic imports with React.lazy - Code splitting and bundle analysis - CSS optimization and minification - Compression and gzip - CDN configuration **Common Pitfalls & Solutions:** - Hydration mismatches (Server vs Client) - Using client-only features in Server Components - Incorrect caching strategies - Image optimization issues - Font loading performance - Dynamic routes not rendering statically - Environment variable scope **Troubleshooting Guide:** ``` Issue: "Cannot find module" in builds Solution: Check tsconfig paths, clear .next folder, rebuild Issue: Hydration mismatch error Solution: Use dynamic imports, wrap client code, check useEffect Issue: Images not optimizing Solution: Use next/image, configure domains, check sizes Issue: Build time too long Solution: Analyze with `next/bundle-analyzer`, use dynamic imports Issue: Environment variables undefined Solution: Prefix with NEXT_PUBLIC_ for client, restart dev server ``` **Version Management:** - Upgrading from Pages Router to App Router - Breaking changes between versions - Migration guides - Beta features and deprecations - Staying updated with releases --- ### 2. React 18+ Complete Mastery **Hooks Deep Dive:** - useState: State management, state updates, batching - useEffect: Side effects, cleanup, dependencies, common pitfalls - useContext: Context creation, avoiding prop drilling - useReducer: Complex state logic, reducer patterns - useCallback: Memoization, dependency arrays - useMemo: Expensive computations, memory management - useRef: DOM access, persistent values, .current - useLayoutEffect: DOM layout measurements - useTransition: Concurrent rendering, isPending state - useDeferredValue: Value debouncing, input optimization - useId: Unique identifiers, accessibility - useImperativeHandle: Custom instance values **Component Patterns:** - Functional components with hooks - Custom hooks development and reusability - Compound components - Render props pattern - Higher-order components - Provider pattern - Controlled vs uncontrolled components - Composition over inheritance **Performance Optimization:** - React.memo for preventing rerenders - useCallback with dependencies - useMemo for expensive operations - Lazy loading with React.lazy and Suspense - Code splitting strategies - List rendering with keys (importance of stable keys) - Avoiding unnecessary renders - Profiler API for performance measurement **Concurrent Features:** - Suspense boundaries - useTransition for non-blocking updates - useDeferredValue for value debouncing - Streaming and progressive rendering - Automatic batching of state updates **Common Pitfalls & Solutions:** - Missing dependency in useEffect - Stale closures in hooks - Memory leaks in useEffect - Infinite loops with useEffect - Using hooks conditionally - Not returning cleanup functions - Incorrect memo dependencies - State batching confusion **Troubleshooting Guide:** ``` Issue: Infinite loop in useEffect Solution: Check dependencies, add return cleanup function Issue: Stale state in callback Solution: Include state in dependencies or use useCallback Issue: Memory leak warning Solution: Add cleanup function to useEffect, unsubscribe Issue: Component rerending unnecessarily Solution: Use React.memo, useCallback, useMemo Issue: Hydration error with useId Solution: Use proper key prop, wrap in Suspense ``` --- ### 3. TypeScript Complete Mastery **Fundamentals:** - Primitive types (string, number, boolean, null, undefined) - Union types and intersection types - Type literals and literal types - Enums and const assertions - Type aliases vs interfaces - Extending types and interfaces - Optional properties (?) and nullish coalescing (??) **Advanced Types:** - Generic types and constraints - Conditional types (extends ? :) - Mapped types (Record, Partial, Required, etc.) - Utility types (Pick, Omit, Exclude, Extract, etc.) - Discriminated unions for exhaustive checking - Type guards and type predicates (is keyword) - Const type parameters - Template literal types **React + TypeScript:** - Component prop typing - Event handler typing - Ref typing with Ref - useState with initial values and TypeScript - useReducer with typed actions - useContext with typed values - Custom hook typing - Children prop typing **Common Patterns:** ```typescript // Discriminated union type Action = | { type: 'ADD'; payload: Item } | { type: 'REMOVE'; payload: string }; // Generic component function List(props: { items: T[] }) {} // Type guard function isString(value: unknown): value is string { return typeof value === 'string'; } // Utility type usage type User = { name: string; age: number; email: string }; type UserPreview = Pick; ``` **Configuration:** - tsconfig.json strict mode - CompilerOptions for strict type checking - Path mapping and aliases - Module resolution settings - Declaration file generation **Common Pitfalls & Solutions:** - Type inference failures - Type assertion misuse - Any type overuse - Incorrect generic constraints - Missing type definitions - Circular type dependencies **Troubleshooting Guide:** ``` Issue: Type 'X' is not assignable to type 'Y' Solution: Check property names, use type assertion carefully, review interfaces Issue: Cannot find name 'X' Solution: Check imports, verify tsconfig paths, check node_modules Issue: Property 'X' doesn't exist on type 'Y' Solution: Check types, update interfaces, verify external package types Issue: Generic type 'T' is too complex Solution: Add constraints, break into simpler types, use keyof ``` --- ### 4. Tailwind CSS Complete Mastery **Core Concepts:** - Utility-first CSS methodology - JIT (Just-In-Time) compilation - Responsive design with breakpoints (sm, md, lg, xl, 2xl) - Hover, focus, and other state variants - Dark mode implementation (class and prefers-color-scheme) - Custom configuration (colors, spacing, fonts) - Arbitrary values ([width: 343px]) - CSS layers and specificity **Configuration & Customization:** ```javascript // tailwind.config.ts import type { Config } from 'tailwindcss' export default { content: [ './app/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}', ], theme: { extend: { colors: { primary: '#your-color', }, spacing: { '128': '32rem', }, }, }, plugins: [], } satisfies Config ``` **Advanced Patterns:** - Responsive design strategies - Component extraction with @apply - Conditional styling with clsx/classnames - Dark mode toggling - Custom plugins - CSS variables integration - Animation and transition utilities - Theme switching with CSS custom properties **Performance Optimization:** - Purging unused styles in production - Content configuration for tree-shaking - CSS size analysis - Critical CSS inline optimization - Lazy loading stylesheets - CSS compression **Common Pitfalls & Solutions:** - Utility conflicts and specificity issues - Unresponsive images with Tailwind sizing - Dark mode not working properly - Build process including unused classes - Custom color not applying - Conflicting CSS and Tailwind classes **Troubleshooting Guide:** ``` Issue: Styles not applying in production Solution: Check content paths, rebuild, check purge config Issue: Dark mode not toggling Solution: Set darkMode: 'class' in config, add class to html Issue: Custom colors not available Solution: Update tailwind.config.ts theme.extend.colors Issue: Build size too large Solution: Verify content paths, use JIT, remove unused plugins Issue: Responsive styles not working Solution: Use correct breakpoint prefix (sm:, md:), check cascade ``` --- ### 5. Firebase Complete Mastery **Setup & Configuration:** ```typescript // lib/firebase.ts import { initializeApp } from 'firebase/app'; import { getAuth } from 'firebase/auth'; import { getFirestore } from 'firebase/firestore'; import { getStorage } from 'firebase/storage'; const firebaseConfig = { apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY, authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN, projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID, storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET, messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID, appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID, }; const app = initializeApp(firebaseConfig); export const auth = getAuth(app); export const db = getFirestore(app); export const storage = getStorage(app); ``` **Authentication:** - Email/password signup and signin - OAuth providers (Google, GitHub, Facebook) - User profile management - Custom claims for authorization - Session persistence - Token refresh and expiration - MFA setup and verification - Anonymous authentication **Firestore Database:** - Collection references and document references - CRUD operations (create, read, update, delete) - Real-time listeners with cleanup - Batch writes and transactions - Query operations (where, orderBy, limit) - Pagination with startAt/endAt - Subcollections vs root collections - Data modeling and normalization **Cloud Storage:** - File upload with progress tracking - Download URLs and signed URLs - File deletion and management - Access control and security rules - Image optimization strategies - Resumable uploads for large files **Offline Persistence:** - Local caching configuration - Sync with server on reconnection - Offline-first strategies - Conflict resolution **Common Pitfalls & Solutions:** - Security rules blocking access - Missing .onSnapshot cleanup - Querying with unstable data - Creating too many subcollections - Not validating data before writes - Inconsistent authentication state - Storage rules preventing uploads **Troubleshooting Guide:** ``` Issue: "Permission denied" errors Solution: Check Security Rules, verify auth state, check custom claims Issue: onSnapshot not updating Solution: Verify listener attached, check firestore rules, cleanup properly Issue: File upload failing Solution: Check storage rules, verify file path, check bucket permissions Issue: Auth state undefined on refresh Solution: Wait for onAuthStateChanged before rendering, use loading state Issue: Realtime listener consuming quota Solution: Limit listeners, use oncemore, implement cleanup ``` --- ### 6. State Management: Zustand & Redux Toolkit **Zustand Complete:** ```typescript // store/cartStore.ts import { create } from 'zustand'; import { persist } from 'zustand/middleware'; interface CartState { items: CartItem[]; addItem: (item: CartItem) => void; removeItem: (id: string) => void; getTotal: () => number; } export const useCartStore = create()( persist( (set, get) => ({ items: [], addItem: (item) => set(state => ({ items: [...state.items, item] })), removeItem: (id) => set(state => ({ items: state.items.filter(i => i.id !== id) })), getTotal: () => { return get().items.reduce((sum, item) => sum + item.price * item.quantity, 0 ); }, }), { name: 'cart-storage' } ) ); ``` **Redux Toolkit Complete:** ```typescript // store/cartSlice.ts import { createSlice, PayloadAction } from '@reduxjs/toolkit'; interface CartState { items: CartItem[]; } const cartSlice = createSlice({ name: 'cart', initialState: { items: [] }, reducers: { addItem: (state, action: PayloadAction) => { state.items.push(action.payload); }, removeItem: (state, action: PayloadAction) => { state.items = state.items.filter(i => i.id !== action.payload); }, }, }); export const { addItem, removeItem } = cartSlice.actions; export default cartSlice.reducer; ``` **Comparison & When to Use:** - Zustand: Lightweight, minimal boilerplate, easier for beginners - Redux Toolkit: More powerful, better DevTools, larger apps - Integration with other libraries - Performance considerations **Common Pitfalls & Solutions:** - Mutating state directly in Zustand - Not using persist middleware properly - Redux selector performance issues - Unnecessary renders from store changes - DevTools not working **Troubleshooting Guide:** ``` Issue: State not persisting in Zustand Solution: Add persist middleware, check localStorage, verify name prop Issue: Redux component not updating Solution: Check selector, verify dispatch called, check middleware Issue: Store data undefined on mount Solution: Use loading state, wait for hydration, check persist Issue: Memory leaks from listeners Solution: Return unsubscribe function, cleanup in useEffect ``` --- ### 7. Forms: react-hook-form + Zod **react-hook-form Setup:** ```typescript import { useForm } from 'react-hook-form'; import { zodResolver } from '@hookform/resolvers/zod'; import { z } from 'zod'; const schema = z.object({ email: z.string().email(), password: z.string().min(8), }); type FormData = z.infer; function LoginForm() { const { register, handleSubmit, formState: { errors } } = useForm({ resolver: zodResolver(schema), }); return (
{errors.email && {errors.email.message}}
); } ``` **Zod Validation:** ```typescript // Complete validation schema const userSchema = z.object({ name: z.string().min(2).max(50), email: z.string().email(), age: z.number().min(18).max(120), password: z.string().min(8), confirmPassword: z.string(), terms: z.boolean().refine(val => val === true), }).refine(data => data.password === data.confirmPassword, { message: "Passwords don't match", path: ["confirmPassword"], }); ``` **Advanced Patterns:** - Multi-step forms with validation - Dynamic field arrays - Conditional field rendering - Async validation (checking email availability) - Custom validators - Nested object validation - File upload validation - Form submission handling **Common Pitfalls & Solutions:** - Form not submitting with validation errors - Async validation causing delays - Zod schema not matching form structure - Field array complexity - Custom validation logic errors - Form reset not working - File upload validation failing **Troubleshooting Guide:** ``` Issue: Form submitting even with errors Solution: Check handleSubmit usage, verify resolver setup Issue: Async validation taking too long Solution: Add debounce, implement caching, optimize backend Issue: Zod error: "Expected object, received undefined" Solution: Verify schema matches form data structure Issue: Dynamic fields not validating Solution: Use z.array() properly, update schema dynamically Issue: File validation not working Solution: Use refine/superRefine, check file type validation ``` --- ### 8. UI/UX: shadcn/ui & lucide-react **shadcn/ui Setup & Usage:** ```typescript // Using pre-built components import { Button } from '@/components/ui/button'; import { Input } from '@/components/ui/input'; import { Card } from '@/components/ui/card'; export function MyComponent() { return ( ); } ``` **Available Components:** - Buttons (variants, sizes, states) - Input fields and forms - Cards and containers - Modals and dialogs - Dropdowns and menus - Tabs and accordions - Data tables and lists - Alerts and notifications - Progress indicators - Navigation components - Tooltips and popovers **lucide-react Icons:** ```typescript import { Heart, ShoppingCart, Menu, X } from 'lucide-react'; export function IconExample() { return ( <> ); } ``` **Customization & Theming:** - Tailwind CSS integration - Color customization - Size variants - Animation options - Dark mode support - Custom component wrappers **Common Pitfalls & Solutions:** - Component styling conflicts - Icon size inconsistencies - Accessibility issues - Theme not applying - Custom styling overriding defaults **Troubleshooting Guide:** ``` Issue: shadcn/ui component styles not applying Solution: Check Tailwind config, verify CSS import, check className conflicts Issue: Icons not showing or sizing incorrectly Solution: Specify size prop, check import path, verify CSS classes Issue: Dark mode not working with components Solution: Set darkMode in tailwind.config, wrap with provider Issue: Component variants not working Solution: Check component prop names, verify version compatibility ``` --- ### 9. Payments: Stripe Integration **Stripe Setup:** ```typescript import Stripe from 'stripe'; const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!); // Create payment intent const paymentIntent = await stripe.paymentIntents.create({ amount: 1000, // in cents currency: 'usd', payment_method_types: ['card'], }); ``` **Client-Side Integration:** ```typescript import { loadStripe } from '@stripe/js'; import { CardElement, useStripe, useElements } from '@stripe/react-stripe-js'; const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_KEY!); function PaymentForm() { const stripe = useStripe(); const elements = useElements(); const handleSubmit = async (e) => { const { paymentIntent } = await stripe.confirmCardPayment( clientSecret, { payment_method: { card: elements.getElement(CardElement) } } ); }; return ( ); } ``` **Webhooks & Server-Side:** - Payment intent creation - Webhook event handling - Subscription management - Customer management - Invoice generation - Refund processing **Common Pitfalls & Solutions:** - Missing publishable key environment variable - Webhook signature verification failing - Race conditions with payment status - PCI compliance violations - Testing with wrong API keys - Missing error handling - Race conditions in webhook processing **Troubleshooting Guide:** ``` Issue: "publishable key not found" error Solution: Check NEXT_PUBLIC_STRIPE_KEY env var, restart dev server Issue: Webhook verification failing Solution: Use correct webhook secret, check signature encoding Issue: Payment processing twice Solution: Implement idempotency keys, add retry logic, check order status Issue: Test card not working Solution: Use Stripe test cards (4242424242424242), check mode (test/live) ``` --- ### 10. Other Essential Libraries **react-hot-toast:** ```typescript import toast from 'react-hot-toast'; // Success toast toast.success('Order placed successfully!'); // Error toast toast.error('Payment failed'); // Custom toast toast((t) => (
Custom message
)); ``` **axios vs fetch:** ```typescript // axios - automatic JSON handling, interceptors import axios from 'axios'; const response = await axios.get('/api/products'); // fetch - native, no dependencies const response = await fetch('/api/products'); const data = await response.json(); ``` **clsx/classnames:** ```typescript import clsx from 'clsx'; const buttonClass = clsx( 'px-4 py-2 rounded', variant === 'primary' && 'bg-blue-600 text-white', variant === 'secondary' && 'bg-gray-200 text-gray-900', isLoading && 'opacity-50 cursor-not-allowed' ); ``` --- ## Integration Patterns: Libraries Working Together ### E-Commerce Example ```typescript // Components use shadcn/ui + lucide-react // Forms use react-hook-form + Zod // State with Zustand + persist // API calls with axios // Payments with Stripe // Database with Firebase // Styling with Tailwind CSS // Routing with Next.js ``` ### SaaS Example ```typescript // Next.js for routing + SSR // React for components // TypeScript for type safety // Firebase Auth + Firestore // Redux Toolkit for complex state // Tailwind + shadcn/ui for UI // react-hook-form for user forms // Stripe for subscriptions ``` --- ## Dependency Management **package.json Best Practices:** - Version pinning strategies - Semantic versioning - Peer dependencies - Dev vs production dependencies - Monorepo workspaces - Script automation **Updating Dependencies:** ```bash # Check outdated packages npm outdated # Update specific package npm install package@latest # Update all patch versions npm update # Check for vulnerabilities npm audit npm audit fix ``` **Common Issues:** - Peer dependency conflicts - Incompatible version combinations - Breaking changes during updates - Node version compatibility - Platform-specific issues --- ## Performance Optimization Across Libraries **Bundle Size Reduction:** - Dynamic imports with Next.js - Tree shaking with TypeScript - Removing unused Tailwind classes - Code splitting with React.lazy - Analyzing with bundle-analyzer **Runtime Performance:** - React memo and callbacks - Zustand selector optimization - Redux reselect usage - Lazy image loading with next/image - Request deduplication with axios interceptors **Database Performance:** - Firestore query optimization - Collection indexing - Batch operations - Caching strategies --- ## When to Use This Skill ✅ Understanding how to set up each library properly ✅ Learning integration patterns between libraries ✅ Troubleshooting library-specific issues ✅ Optimizing performance with libraries ✅ Upgrading and managing dependencies ✅ Finding solutions to common pitfalls ✅ Learning best practices for each library ✅ Making choices between similar libraries (Zustand vs Redux) ✅ Quick reference for library syntax and APIs ✅ Deep diving into advanced usage --- ## Quick Reference vs Deep Learning **This skill includes:** - ⚡ Quick lookup tables and syntax reference - 📚 In-depth tutorials and explanations - 🔧 Configuration file templates - 🐛 Troubleshooting guides - 🚀 Performance tips - ⚠️ Common pitfalls and solutions - 🔄 Integration patterns - 📊 Comparison guides - 💡 Real-world examples - 🎯 Best practices --- ## Resources & References ### Quick Reference Guides - **next-js-quick-ref.md** - Commands, config, routing - **react-hooks-reference.md** - All hooks with examples - **typescript-quick-ref.md** - Common patterns, syntax - **tailwind-utilities-ref.md** - All utility classes - **firebase-methods-ref.md** - All Firebase methods - **zod-validators-ref.md** - All Zod validators - **stripe-api-ref.md** - Stripe API methods ### In-Depth Guides - **next-js-advanced.md** - Advanced patterns, optimization - **react-performance.md** - Rendering optimization - **typescript-advanced.md** - Complex types, patterns - **tailwind-advanced.md** - Custom plugins, design systems - **firebase-patterns.md** - Architecture patterns - **zustand-vs-redux.md** - Comparison and when to use - **form-validation-deep.md** - Complex validation patterns - **stripe-complete.md** - Full Stripe implementation ### Troubleshooting & Common Issues - **common-errors.md** - Error messages and solutions - **dependency-conflicts.md** - Resolving version conflicts - **performance-issues.md** - Identifying and fixing slowness - **type-errors.md** - TypeScript error solutions - **build-issues.md** - Next.js build troubleshooting ### Integration Examples - **ecommerce-integration.md** - Complete e-commerce setup - **saas-integration.md** - SaaS platform setup - **authentication-flows.md** - Auth integration patterns - **payment-integration.md** - Payment processing setup --- ## Technology Stack Details **Versions Covered:** - Next.js 13+ - React 18+ - TypeScript 4.5+ - Tailwind CSS 3+ - Firebase SDK (latest) - Zustand 4+ - Redux Toolkit 1.9+ - react-hook-form 7+ - Zod 3+ - Stripe (latest) **Upgrade Paths:** - Next.js 12 → 13 → 14 - React 17 → 18 - Tailwind CSS 2 → 3 - TypeScript updates and breaking changes - Firebase SDK v8 → v9 (modular SDK) --- This comprehensive skill gives you complete mastery of the essential libraries and how they work together!