LiveSolidJS

Bring the power of SolidJS to Phoenix LiveView - seamless client-side interactivity with server-side state management.

SolidJS 为 Phoenix LiveView 提供高效的、细粒度响应式的前端框架集成。

Key Features

• ⚡ End-To-End Reactivity - Seamless two-way data binding between LiveView and SolidJS
• 🔋 Server-Side Rendering (SSR) - Render components on the server for faster initial page load
• 🎯 Fine-grained Reactivity - Only affected DOM nodes update, no virtual DOM overhead
• 🔗 Smart Link Component - Client-side navigation without full page reloads
• 🚀 Amazing DX - Fast HMR (Hot Module Reload) with Vite
• 🎨 CSS Support - Built-in Tailwind and PostCSS support
• 🪝 Full Hook Access - useLiveSolidJS() provides complete LiveView integration
• 📝 Form Integration - useLiveForm() hook for Ecto changesets and server-side validation
• 📡 Phoenix Streams - First-class support for real-time list updates with efficient patching
• 📁 File Upload Support - Built-in file upload functionality via useLiveSolidJS() hooks

Documentation

• QUICK_START.md - Get started in 5 minutes
• Guides - Detailed documentation
  • Installation Guide
  • Development Guide
  • Deployment Guide
  • SSR Guide
• IMPLEMENTATION_SUMMARY.md - Technical architecture and internals
• live_solidjs_examples/GEMINI.md - Comprehensive component examples and best practices

Examples

The live_solidjs_examples project includes:

• Basic Components: simple.jsx, simple-props.jsx, ssr.jsx
• Communication Patterns: counter.jsx, context.tsx (两种通信模式对比)
• Advanced Features: log-list.jsx, flash-sonner.jsx, link-example.jsx, slot.tsx
• Modern Practices: lazy.jsx, typescript.tsx, switch-language.jsx (国际化)

Each example is fully documented with explanation of SolidJS patterns and live_solidjs integration points.

Why LiveSolidJS?

Phoenix LiveView enables rich, real-time user experiences with server-rendered HTML and WebSocket communication. LiveSolidJS extends this by adding powerful client-side interactivity:

The Problem with Traditional React in LiveView

• React requires a virtual DOM, adding complexity and bundle size
• Components often re-render unnecessarily, wasting resources
• Props handling requires careful optimization to maintain reactivity
• Managing both server and client state becomes complicated

Why SolidJS is Different

1. Fine-grained Reactivity: Instead of re-rendering entire component trees, SolidJS tracks individual value changes and updates only the affected DOM nodes
2. No Virtual DOM: SolidJS compiles directly to optimized vanilla JavaScript, resulting in:
   • Smaller bundle sizes (20KB vs 40KB+ for React)
   • Faster execution
   • Better performance on mobile devices
3. Reactive Props: Props are automatically reactive through SolidJS stores, so components respond instantly to LiveView updates without manual optimization
4. Better Developer Experience: Closer to vanilla JavaScript with minimal abstractions

Real-World Use Cases

• Real-time Dashboards: Update specific metrics without re-rendering the entire page
• Collaborative Apps: Show live updates from other users with minimal overhead
• Large Lists: Efficiently update only the items that changed
• Interactive Forms: Provide instant feedback while syncing with the server

Quick Start

See QUICK_START.md for step-by-step setup instructions.

Or explore the live_solidjs_examples project to see it in action.

Important Notes

Props Handling (Critical!)

When accessing props in your SolidJS components, always use props.field syntax and avoid destructuring in the function signature:

// ✅ Correct - Props stay reactive
export function Component(props) {
  return <div>{props.value}</div>;
}

// ❌ Wrong - Props lose reactivity
export function Component({ value }) {
  return <div>{value}</div>;
}

See QUICK_START.md - Reactive Props for more details.

Windows Users

推荐：在 config/dev.exs 中配置 watchers，使用 cmd 运行 npm 命令，这样 mix phx.server 时 Vite 会自动启动：

# config/dev.exs
config :my_app, MyAppWeb.Endpoint,
  watchers: [
    cmd: ["/c", "npm", "run", "dev", cd: Path.expand("../assets", __DIR__)]
  ]

启动服务器时以管理员身份运行终端以支持符号链接（symlink）：

mix phx.server  # Vite 会自动启动

更多详情见 Installation Guide - Windows Users。

Streams Support

Phoenix Streams are fully supported for efficient real-time list updates. See GEMINI.md - Streams Bug Fix for implementation details.

Contributing

Contributions are welcome! Please refer to IMPLEMENTATION_SUMMARY.md for technical details on the project architecture.

External Resources

• Phoenix LiveView Documentation
• SolidJS Official Docs
• SolidJS Tutorial
• Vite Documentation
• Tailwind CSS

Credits

Inspired by the following libraries:

• LiveVue - Vue + LiveView integration
• LiveSvelte - Svelte + LiveView integration
• LiveReact - React + LiveView integration

License

MIT License - See LICENSE.md for details