Troubleshooting

Common issues and solutions when using React Kickstart. If you don't find your issue here, please open a GitHub issue (opens in a new tab).

🚨 Installation Issues

Node.js Version Error

Error: React Kickstart requires Node.js >= 16

Solution:

# Check your Node.js version
node --version
 
# Update Node.js to version 16 or higher
# Using nvm (recommended)
nvm install 18
nvm use 18
 
# Or download from nodejs.org

NPX Command Not Found

npx: command not found

Solution:

# Update npm to latest version
npm install -g npm@latest
 
# Try npx again
npx @gavbarosee/react-kickstart my-app

📁 Project Creation Issues

Directory Not Empty Error

Error: The directory 'my-app' is not empty

Solutions:

# Option 1: Use a different name
npx @gavbarosee/react-kickstart my-new-app
 
# Option 2: Remove existing directory
rm -rf my-app
npx @gavbarosee/react-kickstart my-app
 
# Option 3: Use a subdirectory
npx @gavbarosee/react-kickstart projects/my-app

Invalid Project Name

Error: Invalid project name. Must be a valid npm package name.

Valid project names:

✅ my-app
✅ my-react-project
✅ awesome-app-2024
❌ My App (no spaces)
❌ my_app (no underscores)
❌ 123-app (can't start with number)

Solution:

# Use kebab-case names
npx @gavbarosee/react-kickstart my-awesome-app

Permission Denied

Error: EACCES: permission denied, mkdir '/path/to/project'

Solutions:

# Navigate to a directory you own
cd ~/Documents
npx @gavbarosee/react-kickstart my-app

📦 Dependency Installation Issues

Network/Registry Errors

npm ERR! network request failed
npm ERR! registry error parsing json

Solutions:

# Navigate to your project
cd my-app
 
# Retry installation
npm install
 
# Or with verbose logging
npm install --verbose

Dependency Conflicts

npm ERR! peer dep missing
npm ERR! conflicting dependencies

Solution:

# Delete node_modules and package-lock.json
cd my-app
rm -rf node_modules package-lock.json
 
# Reinstall dependencies
npm install
 
# Or use --force flag (use with caution)
npm install --force

🚀 Development Server Issues

Port Already in Use

Error: Port 3000 is already in use
Error: Port 5173 is already in use

Solutions:

# Kill process on port 3000 (Next.js)
lsof -ti:3000 | xargs kill -9
 
# Kill process on port 5173 (Vite)
lsof -ti:5173 | xargs kill -9
 
# Then start your server
npm run dev

Module Not Found Errors

Module not found: Can't resolve 'react'
Module not found: Can't resolve './App'

Solutions:

# Ensure dependencies are installed
npm install
 
# Check if files exist
ls src/
ls src/App.tsx  # or App.jsx
 
# Restart development server
npm run dev

🔧 Build Issues

TypeScript Compilation Errors

Type error: Cannot find module 'react' or its corresponding type declarations

Solutions:

# Install missing type definitions
npm install --save-dev @types/react @types/react-dom
 
# For Node.js types
npm install --save-dev @types/node

Build Command Fails

npm run build
> vite build
Error: Build failed

Solutions:

# Check for TypeScript errors
npm run build -- --mode development
 
# Clear cache and rebuild
rm -rf dist .vite node_modules/.cache
npm install
npm run build
 
# Check for memory issues
NODE_OPTIONS="--max-old-space-size=4096" npm run build

🎨 Styling Issues

Tailwind CSS Not Working

Styles not applying or Tailwind classes not working.

Solutions:

# Verify tailwind.config.js exists
cat tailwind.config.js
 
# Verify postcss.config.js exists
cat postcss.config.js
 
# Reinstall Tailwind if needed
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

styled-components Not Working

Components not styled or TypeScript errors.

Solution:

# Install styled-components and types
npm install styled-components
npm install --save-dev @types/styled-components
 
# Check babel config (if using Vite with styled-components)
# vite.config.ts should have the styled-components plugin

🧪 Testing Issues

Tests Not Running

npm test
> No tests found

Solutions:

# Check if test files exist
ls src/**/*.test.*
ls src/**/*.spec.*
 
# For Vitest
npm install --save-dev vitest @testing-library/react @testing-library/jest-dom
 
# For Jest
npm install --save-dev jest @testing-library/react @testing-library/jest-dom

Jest Configuration Issues

Jest encountered an unexpected token

Solution:

Create a babel.config.json file for Vite + Jest:

{
  "presets": [
    ["@babel/preset-env", { "targets": { "node": "current" } }],
    ["@babel/preset-react", { "runtime": "automatic" }]
  ]
}

Install required babel packages:

npm install --save-dev @babel/preset-env @babel/preset-react

🔍 Getting More Help

Enable Debug Mode

# Run with debug information
DEBUG=react-kickstart* npx @gavbarosee/react-kickstart my-app
 
# Or with verbose npm logging
npm run dev --verbose

Check System Information

# Check versions
node --version
npm --version
npx --version
 
# Check npm configuration
npm config list
 
# Check installed packages
npm list --depth=0

Common Environment Issues

⚠️

Windows Users: Use PowerShell or Git Bash for the best experience. Command Prompt may have issues with some commands.

Windows-specific solutions:

# Use PowerShell instead of Command Prompt
# Or install Git Bash: https://git-scm.com/download/win
 
# For permission issues, run PowerShell as Administrator
# Set execution policy if needed:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

🆘 Still Need Help?

If you're still experiencing issues:

Search Existing Issues: Check GitHub Issues (opens in a new tab) for similar problems
Create New Issue: If you can't find a solution, create a new issue (opens in a new tab) with:
- Your operating system and version
- Node.js and npm versions
- Complete error message
- Steps to reproduce the issue
- What you expected to happen
Join Discussions: Ask questions in GitHub Discussions (opens in a new tab)

Pro Tip: When reporting issues, include the output of node --version, npm --version, and the complete error message for faster resolution.

Your First Project