Troubleshooting

Common issues and solutions when working with ShadcnStore blocks.

Installation Issues

Authentication Errors

Problem: Getting 401 or 403 errors when installing premium blocks.

Solutions:

1. Verify your license key:

   • Check your license key is correct and active
   • Visit your dashboard to confirm

2. Quote the URL properly:

   # ✅ Correct - quoted URL
   npx shadcn@latest add "https://shadcnstore.com/r/[component].json?token=your_key"
   
   # ❌ Incorrect - unquoted URL with special characters
   npx shadcn@latest add https://shadcnstore.com/r/[component].json?token=your_key

3. Try different authentication methods:

   # Method 1: Query parameter (recommended)
   npx shadcn@latest add "https://shadcnstore.com/r/[component].json?token=your_key"
   
   # Method 2: Environment variable
   export SHADCN_STORE_TOKEN="your_key"
   npx shadcn@latest add "https://shadcnstore.com/r/[component].json?token=$SHADCN_STORE_TOKEN"

Network Connection Issues

Problem: Unable to download components from the registry.

Solutions:

1. Check internet connection:

   # Test connectivity
   ping shadcnstore.com
   curl -I https://shadcnstore.com

2. Corporate firewall/proxy:

   • Check with your IT department about HTTPS access
   • Configure npm proxy settings if needed:

   npm config set proxy http://proxy.company.com:8080
   npm config set https-proxy http://proxy.company.com:8080

3. DNS issues:

   # Try alternative DNS
   nslookup shadcnstore.com 8.8.8.8

File Permission Errors

Problem: Cannot write files to the components directory.

Solutions:

1. Check directory permissions:

   ls -la components/
   chmod 755 components/

2. Run with appropriate permissions:

   # macOS/Linux
   sudo npx shadcn@latest add [component]
   
   # Or fix ownership
   sudo chown -R $USER:$USER components/

3. Windows permissions:

   • Run command prompt as administrator
   • Check folder permissions in Properties

Configuration Issues

Invalid components.json

Problem: shadcn CLI cannot find or parse components.json.

Solutions:

1. Initialize shadcn/ui:

   npx shadcn@latest init

2. Validate JSON syntax:

   # Check for syntax errors
   cat components.json | jq .

3. Verify required fields:

   {
     "style": "new-york",
     "rsc": true,
     "tailwind": {
       "config": "tailwind.config.js",
       "css": "app/globals.css",
       "baseColor": "neutral",
       "cssVariables": true
     },
     "aliases": {
       "components": "@/components",
       "utils": "@/lib/utils"
     }
   }

Path Alias Issues

Problem: Import errors with @/ paths after installing blocks.

Solutions:

1. Check tsconfig.json paths:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "@/*": ["./*"],
         "@/components/*": ["./components/*"],
         "@/lib/*": ["./lib/*"]
       }
     }
   }

2. Verify aliases match components.json:

   // components.json
   {
     "aliases": {
       "components": "@/components",
       "utils": "@/lib/utils"
     }
   }

3. Framework-specific configuration:

   Next.js: Paths are automatically handled

   Vite:

   // vite.config.ts
   export default defineConfig({
     resolve: {
       alias: {
         "@": path.resolve(__dirname, "./src"),
       },
     },
   })

   Create React App with CRACO:

   // craco.config.js
   const path = require('path')
   
   module.exports = {
     webpack: {
       alias: {
         '@': path.resolve(__dirname, 'src'),
       },
     },
   }

Styling Issues

Blocks Look Broken or Unstyled

Problem: Components appear without styling or with broken layout.

Solutions:

1. Check Tailwind CSS installation:

   # Verify Tailwind is installed
   npm list tailwindcss
   
   # Reinstall if needed
   npm install -D tailwindcss postcss autoprefixer

2. Verify CSS imports:

   /* In your main CSS file */
   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   
   /* For Tailwind v4 */
   @import "tailwindcss";

3. Check CSS variables:

   /* Ensure shadcn/ui CSS variables are defined */
   :root {
     --background: oklch(1 0 0);
     --foreground: oklch(0.145 0 0);
     --primary: oklch(0.205 0 0);
     /* ... other variables */
   }

4. Verify Tailwind config:

   // tailwind.config.js
   module.exports = {
     darkMode: ["class"],
     content: [
       './pages/**/*.{ts,tsx}',
       './components/**/*.{ts,tsx}',
       './app/**/*.{ts,tsx}',
       './src/**/*.{ts,tsx}',
     ],
     // ... rest of config
   }

Dark Mode Not Working

Problem: Dark mode styles not applying correctly.

Solutions:

1. Check dark mode configuration:

   // tailwind.config.js
   module.exports = {
     darkMode: ["class"], // Enable class-based dark mode
   }

2. Verify dark class application:

   // Should be applied to html or body element
   <html className="dark">

3. Check CSS variables for dark mode:

   .dark {
     --background: oklch(0.145 0 0);
     --foreground: oklch(0.985 0 0);
     /* ... other dark mode variables */
   }

4. Theme provider setup:

   import { ThemeProvider } from "next-themes"
   
   <ThemeProvider attribute="class" defaultTheme="system">
     {children}
   </ThemeProvider>

Responsive Design Issues

Problem: Blocks not responding correctly to screen size changes.

Solutions:

1. Check viewport meta tag:

   <meta name="viewport" content="width=device-width, initial-scale=1">

2. Verify responsive classes:

   // Check block uses responsive prefixes
   <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">

3. Test with browser dev tools:

   • Open responsive design mode
   • Test various screen sizes
   • Check for CSS conflicts

TypeScript Issues

Type Errors

Problem: TypeScript compilation errors when using blocks.

Solutions:

1. Install type dependencies:

   npm install -D @types/react @types/react-dom

2. Check import paths:

   // ✅ Correct import
   import { Button } from "@/components/ui/button"
   
   // ❌ Incorrect import
   import { Button } from "components/ui/button"

3. Verify TypeScript configuration:

   // tsconfig.json
   {
     "compilerOptions": {
       "moduleResolution": "bundler",
       "jsx": "preserve",
       "strict": true
     }
   }

4. Update dependencies:

   npm update @types/react @types/react-dom

Missing shadcn/ui Components

Problem: Blocks failing because required shadcn/ui components are missing.

Solutions:

1. Install required components:

   # Check error message for missing components
   npx shadcn@latest add button card input

2. Install all common components:

   npx shadcn@latest add button input label card dialog dropdown-menu

3. Check component dependencies:

   • Look at block documentation for required components
   • Install dependencies before installing the block

Build Issues

Build Failures

Problem: Build process fails when including blocks.

Solutions:

1. Clear build cache:

   # Next.js
   rm -rf .next
   
   # Vite
   rm -rf dist node_modules/.vite
   
   # General
   rm -rf node_modules package-lock.json
   npm install

2. Check for conflicting CSS:

   • Remove duplicate Tailwind imports
   • Check for CSS specificity conflicts
   • Verify no conflicting global styles

3. Update build tools:

   npm update next vite @vitejs/plugin-react

4. Check Node.js version:

   node --version
   # Ensure Node.js 18+ for best compatibility

Bundle Size Issues

Problem: Large bundle sizes after adding blocks.

Solutions:

1. Analyze bundle:

   # Next.js
   npm install @next/bundle-analyzer
   
   # Vite
   npm install rollup-plugin-visualizer

2. Code splitting:

   import { lazy, Suspense } from 'react'
   
   const HeavyBlock = lazy(() => import('@/components/heavy-block'))
   
   <Suspense fallback={<div>Loading...</div>}>
     <HeavyBlock />
   </Suspense>

3. Tree shake unused code:

   // ✅ Import specific components
   import { Button } from "@/components/ui/button"
   
   // ❌ Avoid barrel imports if unused
   import * as UI from "@/components/ui"

Runtime Issues

Hydration Mismatches

Problem: Server and client render different content (SSR/SSG).

Solutions:

1. Use suppressHydrationWarning:

   <div suppressHydrationWarning>
     {/* Dynamic content */}
   </div>

2. Client-only rendering:

   import { useState, useEffect } from 'react'
   
   function ClientOnlyBlock() {
     const [mounted, setMounted] = useState(false)
   
     useEffect(() => {
       setMounted(true)
     }, [])
   
     if (!mounted) return null
   
     return <YourBlock />
   }

3. Use dynamic imports:

   import dynamic from 'next/dynamic'
   
   const DynamicBlock = dynamic(() => import('@/components/block'), {
     ssr: false
   })

Performance Issues

Problem: Blocks causing performance problems.

Solutions:

1. Optimize images:

   // Use Next.js Image optimization
   import Image from 'next/image'
   
   <Image
     src="/hero.jpg"
     alt="Hero"
     width={800}
     height={600}
     priority
   />

2. Memoize expensive computations:

   import { useMemo } from 'react'
   
   function ExpensiveBlock({ data }) {
     const processedData = useMemo(() => {
       return data.map(item => /* expensive computation */)
     }, [data])
   
     return <div>{/* render */}</div>
   }

3. Use React.memo for pure components:

   import { memo } from 'react'
   
   const PureBlock = memo(function PureBlock({ title, content }) {
     return <div>{title}: {content}</div>
   })

Getting Help

Before Reaching Out

1. Check this troubleshooting guide
2. Review the FAQ for common questions
3. Search existing issues on GitHub
4. Try with a minimal reproduction to isolate the issue

How to Get Help

1. Community: Join our Discord community for help and discussions
2. Support Email: Contact hello@shadcnstore.com

What to Include

When reporting issues, include:

• Environment details: OS, Node.js version, framework version
• Error messages: Full error text and stack traces
• Reproduction steps: Minimal code example
• Expected vs actual behavior: What should happen vs what happens
• Configuration files: components.json, tailwind.config.js, etc.

Example Issue Report

## Bug Report

**Environment:**
- OS: macOS 13.0
- Node.js: 18.17.0
- Next.js: 13.4.19
- shadcn/ui: 0.8.0

**Issue:**
Hero block not displaying correctly in dark mode

**Reproduction:**
1. Install block
2. Enable dark mode
3. Text becomes unreadable

**Expected:** Text should be light in dark mode
**Actual:** Text remains dark and unreadable

**Code:**
Add your code here

**Screenshots:**
Attach any relevant screenshots or GIFs

Debugging Tips

Development Tools

1. React Developer Tools: Debug component state and props
2. Browser DevTools: Inspect CSS and network requests
3. TypeScript compiler: Check for type errors
4. ESLint/Prettier: Code quality and formatting

Common Debugging Steps

1. Start with a clean installation
2. Test with minimal code
3. Check browser console for errors
4. Verify all dependencies are installed
5. Test in incognito/private mode

Remember: Most issues are configuration-related. Double-check your setup before assuming it's a bug! 🐛→🎯