[GUIDE]: TROUBLESHOOTING

Troubleshooting

Common issues, error messages, debugging tips, and solutions for library templates.

[0x00] IMPORT ERRORS

[ERROR]: Cannot find module '@/design-system'

Cause: Design system module not set up or path alias not configured.

[FIX]:

1// 1. Verify tsconfig.json has path alias
2{
3  "compilerOptions": {
4    "paths": {
5      "@/*": ["./src/*"]
6    }
7  }
8}
9
10// 2. Create design-system.ts if missing
11// src/design-system.ts
12export const mode = {
13  font: "font-mono",
14  radius: "rounded-none",
15  color: {
16    text: {
17      muted: "text-muted-foreground",
18      primary: "text-primary",
19    }
20  }
21};

[ERROR]: Module not found: Can't resolve '@/components/ui/...'

Cause: Component not installed or wrong path.

[FIX]:

1. Check component exists: ls src/components/ui/

2. Install missing component from components documentation

3. Verify import path matches file location

[0x01] TYPESCRIPT ERRORS

[ERROR]: Property 'mode' does not exist on type ''

Cause: Design system types not exported properly.

[FIX]:

1// src/design-system.ts
2export const mode = {
3  font: "font-mono",
4  radius: "rounded-none",
5  // ... rest of design system
6} as const;
7
8// Regenerate types
9npm run type-check

[ERROR]: Type 'Promise' is not assignable to type 'ReactNode'

Cause: Next.js 15 async params not awaited.

[FIX]:

1// ✗ Wrong
2export default function Page({ params }) {
3  const { id } = params; // params is Promise
4
5// ✓ Correct
6export default async function Page({ params }) {
7  const { id } = await params; // Must await

[0x02] STYLING ISSUES

[ISSUE]: Tailwind classes not applying

Cause: Template path not in Tailwind config content array.

[FIX]:

1// tailwind.config.ts
2export default {
3  content: [
4    "./src/**/*.{ts,tsx}",  // Include all template files
5    "./app/**/*.{ts,tsx}",
6  ],
7  // ... rest of config
8};
9
10// Restart dev server
11npm run dev

[ISSUE]: Terminal aesthetic not working

Cause: Missing font-mono on body tag or design system not imported.

[FIX]:

1// app/layout.tsx
2<body className="font-mono antialiased">
3  {children}
4</body>
5
6// Or in component
7import { mode } from "@/design-system";
8
9<div className={mode.font}>Content</div>

[0x03] RUNTIME ERRORS

[ERROR]: Hydration mismatch

Cause: Server and client rendering differ (common with date/time or random values).

[FIX]:

1// Use suppressHydrationWarning for dynamic content
2<div suppressHydrationWarning>
3  {new Date().toLocaleString()}
4</div>
5
6// Or use useEffect for client-only rendering
7const [mounted, setMounted] = useState(false);
8useEffect(() => setMounted(true), []);
9
10if (!mounted) return null;

[ERROR]: Too many re-renders

Cause: State update in render function causing infinite loop.

[FIX]:

1// ✗ Wrong - causes infinite loop
2function Component() {
3  const [count, setCount] = useState(0);
4  setCount(count + 1); // DON'T do this
5
6// ✓ Correct - update in effect or event handler
7function Component() {
8  const [count, setCount] = useState(0);
9
10  useEffect(() => {
11    setCount(count + 1);
12  }, []); // Run once on mount

[0x04] PERFORMANCE ISSUES

[ISSUE]: Template loads slowly

Solutions:

Use React.lazy() for heavy components
Add loading states with Suspense
Optimize images with next/image
Reduce bundle size by removing unused imports

[0x05] QUICK FIXES

Template not showing after paste:

Verify route matches file location. Check for typos in directory names.

Mock data still showing:

Replace mock data imports with real API calls or database queries.

Icons not rendering:

Install lucide-react: npm install lucide-react

Build failing in production:

Run npm run type-check and fix TypeScript errors before deploying.

[0x06] STILL STUCK?

If you're still experiencing issues:

Check Console

Open browser DevTools (F12) and check Console tab for error messages.

Review Logs

Check terminal output where dev server is running for build errors.

Useful debugging commands:

1$# Clear cache and restart
2$rm -rf .next && npm run dev
3
4$# Check TypeScript errors
5$npm run type-check
6
7$# Verify all dependencies installed
8$npm install
9
10$# Check for missing peer dependencies
11$npm ls

[0x08] NEXT STEPS

Getting started guide for initial setup
Customization guide for design system changes

1// 1. Verify tsconfig.json has path alias

3 "compilerOptions": {

4 "paths": {

5 "@/*": ["./src/*"]

6 }

7 }

10// 2. Create design-system.ts if missing

11// src/design-system.ts

12export const mode = {

13 font: "font-mono",

14 radius: "rounded-none",

15 color: {

16 text: {

17 muted: "text-muted-foreground",

18 primary: "text-primary",

19 }

20 }

21};

1// ✗ Wrong

2export default function Page({ params }) {

3 const { id } = params; // params is Promise

5// ✓ Correct

6export default async function Page({ params }) {

7 const { id } = await params; // Must await

1// tailwind.config.ts

2export default {

3 content: [

4 "./src/**/*.{ts,tsx}", // Include all template files

5 "./app/**/*.{ts,tsx}",

6 ],

7 // ... rest of config

8};

10// Restart dev server

11npm run dev

1// Use suppressHydrationWarning for dynamic content

2<div suppressHydrationWarning>

3 {new Date().toLocaleString()}

4</div>

6// Or use useEffect for client-only rendering

7const [mounted, setMounted] = useState(false);

8useEffect(() => setMounted(true), []);

10if (!mounted) return null;

1// ✗ Wrong - causes infinite loop

2function Component() {

3 const [count, setCount] = useState(0);

4 setCount(count + 1); // DON'T do this

6// ✓ Correct - update in effect or event handler

7function Component() {

8 const [count, setCount] = useState(0);

10 useEffect(() => {

11 setCount(count + 1);

12 }, []); // Run once on mount

1$# Clear cache and restart

2$rm -rf .next && npm run dev

4$# Check TypeScript errors

5$npm run type-check

7$# Verify all dependencies installed

8$npm install

10$# Check for missing peer dependencies

11$npm ls