Troubleshooting

# Check if it's globally installed
npm list -g avangcli

# If not installed, install globally
npm install -g avangcli

# Or with Bun
bun install -g avangcli

# Check PATH variable
echo $PATH

# If using bun, make sure bin path is in PATH
export PATH="$HOME/.bun/bin:$PATH"

# If using npm
export PATH="$HOME/.npm-global/bin:$PATH"

# Option 1: Use a local prefix for npm
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
source ~/.profile

# Option 2: Change npm directory permissions
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Option 3: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node
npm install -g avangcli

# Check current version
node --version

# Install compatible version (>=18.0.0)
nvm install 18
nvm use 18

# Or use Bun (recommended)
curl -fsSL https://bun.sh/install | bash

# Option 1: Use a different name
avangcli init my-app-v2

# Option 2: Remove existing directory
rm -rf my-app
avangcli init my-app

# Option 3: Rename existing directory
mv my-app my-app-old
avangcli init my-app

# Clear npm cache
npm cache clean --force

# Try with another package manager
avangcli init my-app --pm bun

# If it persists, install manually
avangcli init my-app --skip-install
cd my-app
npm install

# Make sure you're in the project root
cd /path/to/your/project

# Verify package.json exists
ls -la package.json

# Verify it's a Next.js project
cat package.json | grep "next"

# Check existing modules
ls -la modules/

# Use a different name
avangcli module user-management

# Or remove the existing module
rm -rf modules/user
avangcli module user

# See which one is configured
cat package.json | grep -E "(mui|shadcn|heroui)"

# If you want to change, manually remove the previous one
npm uninstall @mui/material @emotion/react @emotion/styled

# Then install the new one
avangcli ui-library --ui shadcn

# Check tsconfig.json
cat tsconfig.json

# Make sure paths are configured
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"],
      "@/modules/*": ["./modules/*"]
    }
  }
}

# Restart development server
npm run dev

// Verify types are correctly imported
import type { UserProfile } from "../types/user-profile.types"

// Use type assertions if necessary
const profile = data as UserProfile

// Or type guards
function isUserProfile(data: any): data is UserProfile {
  return "id" in data && "name" in data
}

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Rebuild
npm run build

# Increase Node memory
export NODE_OPTIONS="--max-old-space-size=4096"

# Or in package.json
{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

// Make sure server/client HTML matches
// Avoid:
<div>
  {typeof window !== 'undefined' && <ClientComponent />}
</div>

// Use:
'use client'

import { useEffect, useState } from 'react'

export function Component() {
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
  }, [])

  if (!mounted) return null

  return <ClientComponent />
}

// Verify store is correctly exported
// store/user.store.ts
export const useUserStore = create<UserStore>((set) => ({
  // ...
}))

// In component
;("use client") // Make sure it's a client component

import { useUserStore } from "../store/user.store"

export const Component = () => {
  const { data } = useUserStore() // ✅
  // const data = useUserStore((state) => state.data) // ✅ Also valid
}

// .eslintrc.json
{
  "extends": ["next/core-web-vitals"],
  "parserOptions": {
    "babelOptions": {
      "presets": [require.resolve("next/babel")]
    }
  }
}

# Install eslint-config-prettier
npm install --save-dev eslint-config-prettier

# Update .eslintrc.json
{
  "extends": [
    "next/core-web-vitals",
    "prettier" // Must be last
  ]
}

// tailwind.config.ts
import type { Config } from 'tailwindcss'

const config: Config = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './modules/**/*.{js,ts,jsx,tsx,mdx}', // ← Important
    './components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  // ...
}

export default config

/* app/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

# Clear all lock files
rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml bun.lockb

# Reinstall with a single package manager
npm install
# Or
bun install
# Or
pnpm install

# Configure project to use a specific one
echo "package-manager=bun" > .npmrc

// ❌ Bad: Mutating state directly
set({ data: state.data.push(item) })

// ✅ Good: Create new object
set({ data: [...state.data, item] })

// ✅ Good: Use Immer
import { immer } from "zustand/middleware/immer"

export const useStore = create<Store>()(
  immer((set) => ({
    data: [],
    addItem: (item) =>
      set((state) => {
        state.data.push(item) // Now it works
      })
  }))
)

// For Zustand
import { devtools } from "zustand/middleware"

export const useStore = create<Store>()(
  devtools(
    (set) => ({
      // ...
    }),
    { name: "MyStore" } // ← Important to give name
  )
)

// Verify extension is installed
// Chrome/Edge: Redux DevTools Extension

# Verify shadcn is initialized
ls -la components/ui

# If it doesn't exist, initialize
npx shadcn-ui@latest init

# Add needed components
npx shadcn-ui@latest add button
npx shadcn-ui@latest add card

// app/layout.tsx
import { AppRouterCacheProvider } from '@mui/material-nextjs/v14-appRouter'
import { ThemeProvider } from '@mui/material/styles'
import CssBaseline from '@mui/material/CssBaseline'
import theme from '@/config/theme'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AppRouterCacheProvider>
          <ThemeProvider theme={theme}>
            <CssBaseline />
            {children}
          </ThemeProvider>
        </AppRouterCacheProvider>
      </body>
    </html>
  )
}

# Use Turbopack (Next.js 13+)
npm run dev --turbo

# Or update package.json
{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

# Verify there are no circular imports
# Use tools like madge
npm install -g madge
madge --circular --extensions ts,tsx .

// next.config.js
module.exports = {
  // Disable bundle analysis in development
  productionBrowserSourceMaps: false,

  // Optimize compilation
  swcMinify: true,

  // Reduce type checking during build
  typescript: {
    ignoreBuildErrors: false // Only in emergencies
  },

  // Optimize images
  images: {
    formats: ["image/avif", "image/webp"]
  }
}

# Verify husky is installed
ls -la .husky/pre-commit

# Reinstall husky
npm install --save-dev husky
npx husky install

# Give execution permissions
chmod +x .husky/pre-commit

# If you need to skip the hook (not recommended)
git commit --no-verify -m "message"

# Use conventional format
# Type: feat, fix, docs, style, refactor, test, chore

# ✅ Good
git commit -m "feat: add user profile module"
git commit -m "fix: resolve hydration error"
git commit -m "docs: update README"

# ❌ Bad
git commit -m "added stuff"
git commit -m "WIP"

# View configuration
cat commitlint.config.js

# Verify .env.local file exists
ls -la .env.local

# Public variables must have the prefix
# ✅ Good
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_APP_NAME=MyApp

# ❌ Bad (won't be available on client)
API_URL=http://localhost:3001

# Restart server after changes
# Variables are loaded on startup
npm run dev

# Check versions
avangcli --version
node --version
npm --version

# Clear cache
npm cache clean --force
rm -rf .next node_modules package-lock.json
npm install

# View project structure
tree -L 2 -I node_modules

# Check dependencies
npm list --depth=0

# View available scripts
npm run

# Verify TypeScript configuration
npx tsc --noEmit

# Verify ESLint configuration
npx eslint --print-config .

# Analyze bundle
npm run build
npx @next/bundle-analyzer