# 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](./QUICK_START.md)** - Get started in 5 minutes
- **[Guides](/guides/)** - Detailed documentation
  - [Installation Guide](./guides/installation.md)
  - [Development Guide](./guides/development.md)
  - [Deployment Guide](./guides/deployment.md)
  - [SSR Guide](./guides/ssr.md)
- **[IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md)** - Technical architecture and internals
- **[live_solidjs_examples/GEMINI.md](./live_solidjs_examples/GEMINI.md)** - Comprehensive component examples and best practices

## Examples

The [live_solidjs_examples](./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](./QUICK_START.md) for step-by-step setup instructions.

Or explore the [live_solidjs_examples](./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:

```jsx
// ✅ 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](./QUICK_START.md#reactive-props) for more details.

### Windows Users

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

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

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

```bash
mix phx.server  # Vite 会自动启动
```

更多详情见 [Installation Guide - Windows Users](./guides/installation.md#windows-用户特别说明)。

### Streams Support
Phoenix Streams are fully supported for efficient real-time list updates. See [GEMINI.md - Streams Bug Fix](./live_solidjs_examples/GEMINI.md#重要-bug-修复记录) for implementation details.

## Contributing

Contributions are welcome! Please refer to [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) for technical details on the project architecture.

## External Resources

- [Phoenix LiveView Documentation](https://hexdocs.pm/phoenix_live_view/)
- [SolidJS Official Docs](https://www.solidjs.com/)
- [SolidJS Tutorial](https://www.solidjs.com/tutorial/introduction_basics)
- [Vite Documentation](https://vitejs.dev/)
- [Tailwind CSS](https://tailwindcss.com/)

## Credits

Inspired by the following libraries:

- [LiveVue](https://github.com/Valian/live_vue) - Vue + LiveView integration
- [LiveSvelte](https://github.com/woutdp/live_svelte) - Svelte + LiveView integration
- [LiveReact](https://github.com/mrdotb/live_react) - React + LiveView integration

## License

MIT License - See LICENSE.md for details