Troubleshooting

Common issues and solutions for the Fireship AI Blog component.

Installation Issues

Error: Package installation fails

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

# Install with legacy peer deps if needed
npm install --legacy-peer-deps

Error: Peer dependency warnings

# Install all required dependencies
npm install fireship-ai-blog remark remark-gfm remark-html unified lucide-react @tailwindcss/typography

Error: TypeScript compilation errors

// tsconfig.json - Add to compilerOptions
{
  "compilerOptions": {
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}

API Issues

401 Unauthorized Errors

Error: "API key is required"

Check environment variable:

# Verify in .env.local
NEXT_PUBLIC_FIRESHIP_BLOG_PUBLISHABLE_KEY=fs_your_key_here

Restart development server:

# Kill existing process
pkill -f "next dev"

# Start fresh
npm run dev

Error: "Invalid JWT form"

This indicates Clerk middleware is intercepting the API calls. Update your middleware.ts:

import { clerkMiddleware } from '@clerk/nextjs/server';

export default clerkMiddleware((auth, req) => {
  // Skip authentication for fireship-blog API routes
  if (req.nextUrl.pathname.startsWith('/api/fireship-blog')) {
    return;
  }
});

Network Errors

Error: Failed to fetch

Check API proxy route exists:

ls app/api/fireship-blog/[...path]/route.ts

Test proxy endpoint:

curl http://localhost:3000/api/fireship-blog/posts

Display Issues

Content Not Showing

Issue: "No content available" or empty posts

Check API response format:

curl "http://localhost:3000/api/fireship-blog/posts/your-post-slug"

Add debugging to your component:

// Add debugging to your component
useEffect(() => {
  console.log('Posts data:', posts);
  console.log('Current post:', currentPost);
}, [posts, currentPost]);

Styling Issues

Issue: Styles not loading

Import CSS file:

import 'fireship-ai-blog/styles/blog.css';

Install typography plugin:

npm install @tailwindcss/typography

Performance Issues

Slow Loading

Issue: Blog loads slowly

Enable caching:

// In API route
export async function GET(req: Request, ctx: any) {
  const response = await base.GET(req, ctx);
  response.headers.set('Cache-Control', 'public, s-maxage=300');
  return response;
}

Optimize images:

// next.config.js
module.exports = {
  images: {
    domains: ['fireship.ai', 'images.unsplash.com'],
  },
};

Getting Help

Debug Information

When reporting issues, include:

# System information
node --version
npm --version

# Package versions
npm list fireship-ai-blog
npm list next
npm list react

# Environment check
echo $NEXT_PUBLIC_FIRESHIP_BLOG_PUBLISHABLE_KEY | head -c 10

Support Channels

• GitHub Issues: Report bugs

• Documentation: Fireship.ai Docs

• Discord: Join the community for help

• Email: support@fireship.ai

Common Solutions Checklist

API key is correctly formatted (starts with fs_)

Environment variables are in .env.local

Development server restarted after env changes

All dependencies installed

TailwindCSS configured with typography plugin

API proxy route exists and is correct

Middleware excludes blog API routes

No JavaScript errors in browser console