create-solid: SolidJS Project Setup Tool - AI Summary

Configuration

Installation & Execution

# CORRECT: Use latest version
npm create solid@latest
pnpm create solid
yarn create solid
deno init --npm solid

# WRONG: Global installation causes version conflicts
npm install -g solid-cli  # DON'T DO THIS

Critical Failure Point: Installing globally causes 3-hour debugging sessions due to version mismatches (0.2.1 vs 0.3.4+ have different template structures)

Template Selection Decision Matrix

Template	Use Case	Overhead	Reality
ts	RECOMMENDED - All projects	Minimal	Just works, stop overthinking
ts-vitest	Testing upfront	+20min setup, +3hrs debugging	Vitest 1.2.x has signal cleanup issues
ts-uvu	Alternative testing	Unknown	Weird syntax, skip
ts-unocss	CSS framework	Size optimized	Documentation unusable after 30min
ts-tailwindcss	CSS framework	+800KB bundle	Everyone knows classes

Decision Criteria: Choose ts unless you need specific testing framework. Time investment on alternatives rarely pays off.

Resource Requirements

Time Investments

• Setup Success: 30 seconds from command to coding
• Setup with Failures: 30min to 3 hours debugging network/permissions
• Template Decision Time: Entire Tuesday wasted comparing options
• Testing Setup Later: 20min saved upfront, 3hrs debugging async rendering

Expertise Requirements

• Minimum: Basic npm/package manager knowledge
• Troubleshooting: Windows administration, network debugging, npm cache management
• Production Deployment: Server configuration for SSR, static hosting for SPA

Network/Environment Dependencies

• Bandwidth: Template downloads fail 40% of the time on poor connections
• Corporate Networks: Firewall blocks registry access (ENOTFOUND errors)
• Windows Compatibility: Username spaces break extraction (EPERM errors)

Critical Warnings

Breaking Points and Failure Modes

High-Frequency Failures (30%+ occurrence rate)

1. Network Timeouts: ECONNRESET registry.npmjs.org:443

   • Cause: Poor network or corporate firewall
   • Solution: Ctrl+C, retry (usually works second time)
   • Prevention: Use phone hotspot on corporate networks

2. Windows Path Issues: EPERM: operation not permitted

   • Cause: Spaces in Windows username
   • Solution: Run PowerShell as admin OR use WSL
   • Impact: Complete setup failure

3. npm Cache Corruption: EINTEGRITY sha512-... integrity checksum failed

   • Solution: Delete ~/.npm and node_modules/.cache
   • Frequency: Random, but delete always fixes
   • Time Cost: 30 seconds to resolve

Production Deployment Gotchas

• Environment Variables: ReferenceError: process is not defined in SSR
  • Fix: Wrap in if (typeof window === 'undefined')
• Asset Paths: Break on subdirectories (GitHub Pages)
  • Fix: Set base: '/my-app/' in vite.config.ts
• Module Resolution: Module not found: Can't resolve '@solidjs/start/server'
  • Cause: Dependencies in devDependencies instead of dependencies
  • Impact: 4-hour debugging sessions at 2am

SolidStart vs Regular Solid Decision Criteria

Factor	Regular Solid	SolidStart
Use Case	SPAs	SSR/Static Generation
Deployment Complexity	Simple (static files anywhere)	Complex (needs real servers)
Failure Rate	Low	High (creative ways at 2am)
Debug Difficulty	Manageable	document is not defined with zero context
Version Stability	Stable	1.0.8 has dynamic import issues, downgrade to 1.0.6

Technology Comparisons

Framework Trade-offs

Framework	Job Market	Bundle Size	Support Quality	Hidden Costs
SolidJS	Small (betting on future)	120KB start	Discord, 12k members, core team responsive	Build ecosystem from scratch
React	Everywhere	2.5MB minimum	Stack Overflow has everything	Massive bundles, performance issues
Next.js	High paying	"Depends" (usually 8MB)	Good docs	Configuration complexity
Vue	Agencies, legacy	Reasonable	Okay docs	Stagnant ecosystem
Angular	Enterprise	Enormous	Pray when broken	Corporate nightmare

Node Version Requirements

• Required: Node 18+
• Might Work: Node 16
• Will Fail: Node 14
• Bun Issues: 40% registry timeout rate

Implementation Reality

Development Server Performance

• Cold Start: 2 seconds
• Hot Reload: Instant (until HMR breaks with [vite] hmr update /src/App.tsx failed)
• Build Times: 8 seconds small projects, 45 seconds large projects
• Production Build Issues: Tree-shaking breaks dynamic imports

Common Implementation Paths

1. SPA Route: Regular Solid → Deploy static files → Works everywhere
2. SSR Route: SolidStart → Complex deployment → Random failures
3. Migration Route: Manual solid-js install → 2 hours copying config → Start fresh instead

Testing Integration Reality

• Upfront Testing: 20min setup savings, 3hrs debugging signal cleanup
• Later Testing: npm install -D vitest @vitest/ui + hours of configuration
• Component Testing: TypeError: Cannot read properties of undefined (reading 'signal') - cleanup doesn't dispose signals properly

Decision Support Information

Worth It Despite X Assessments

• Performance: Worth bundle size optimization despite small ecosystem
• Learning Curve: Worth initial investment despite fewer jobs
• Community: Worth Discord dependency despite smaller size than Stack Overflow

Prerequisites Not in Documentation

• Windows: WSL or admin PowerShell for reliability
• Corporate: Phone hotspot for registry access
• Deployment: Real server knowledge for SolidStart (static hosting insufficient)
• Production: Manual optimization required to hit benchmark performance

Migration Pain Points

• From React: Completely different reactivity model, rebuild mental models
• To Production: Static works everywhere, SolidStart needs server expertise
• Template Changes: v0.3.0 removed JavaScript templates, TypeScript-only

Resource Links by Use Case

Immediate Problem Solving

• SolidJS Discord: 1-hour response time for create-solid failures
• solid-cli Issues: Check before posting, has cache/permission solutions

Development Setup

• SolidJS Playground: Test signal behavior without project setup
• Templates Repository: Reference for tsconfig.json mismatches

Production Deployment

• SolidStart Docs: Working deployment examples (improved 2025)
• Vite Documentation: Required for build customization

Debugging Tools

• Solid DevTools: Shows signal updates, more useful than React DevTools
• StackBlitz Templates: Cloud reproduction for Discord help requests