electric-sql · nshkrdotcom · Jun 5, 2025
diff --git a/examples/phoenix-todo-app/.gitignore b/examples/phoenix-todo-app/.gitignore
@@ -0,0 +1,75 @@
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where 3rd-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez
+
+# Temporary files, for example, from tests.
+/tmp/
+
+# Ignore package tarball (built via "mix hex.build").
+electric_phoenix-*.tar
+
+# Ignore assets that are produced by build tools.
+/priv/static/assets/
+
+# Ignore digested assets cache.
+/priv/static/cache_manifest.json
+
+# In case you use Node.js/npm, you want to ignore these.
+npm-debug.log
+/assets/node_modules/
+
+# Phoenix .gitignore patterns
+phoenix/_build/
+phoenix/cover/
+phoenix/deps/
+phoenix/doc/
+phoenix/.fetch
+phoenix/erl_crash.dump
+phoenix/*.ez
+phoenix/tmp/
+phoenix/*-*.tar
+phoenix/priv/static/assets/
+phoenix/priv/static/cache_manifest.json
+phoenix/assets/node_modules/
+
+# Electric runtime data - NEVER commit this!
+phoenix/persistent/
+
+# React .gitignore patterns  
+frontend/node_modules/
+frontend/dist/
+frontend/.vite/
+frontend/.env.local
+frontend/.env.development.local
+frontend/.env.test.local
+frontend/.env.production.local
+
+# General patterns
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.DS_Store
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
diff --git a/examples/phoenix-todo-app/README.md b/examples/phoenix-todo-app/README.md
@@ -0,0 +1,179 @@
+# Phoenix + ElectricSQL + React Todo App
+
+A full-stack todo application demonstrating real-time synchronization between Phoenix backend and React frontend using ElectricSQL.
+
+## 🏗️ Architecture
+
+- **Phoenix Backend** (`phoenix/`) - Elixir/Phoenix API with embedded ElectricSQL sync
+- **React Frontend** (`frontend/`) - Modern React app with real-time data sync
+- **PostgreSQL** - Database with logical replication for real-time sync
+
+## 📁 Project Structure
+
+```
+phoenix-todo-app/
+├── phoenix/           # Phoenix backend with ElectricSQL
+│   ├── lib/           # Phoenix application code
+│   ├── config/        # Configuration files
+│   ├── priv/          # Static assets and migrations
+│   ├── test/          # Tests
+│   ├── mix.exs        # Elixir dependencies
+│   ├── start.sh       # Phoenix-specific start script
+│   └── ...
+├── frontend/          # React frontend
+│   ├── src/           # React source code
+│   ├── public/        # Static assets
+│   ├── package.json   # NPM dependencies
+│   └── ...
+├── start.sh           # Main start script
+├── README.md          # This file
+└── LICENSE
+```
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **PostgreSQL 16+** with logical replication enabled
+- **Elixir 1.18+** and **Phoenix**
+- **Node.js 18+** and **npm**
+
+### Setup
+
+1. **Clone and navigate to the project:**
+   ```bash
+   cd phoenix-todo-app
+   ```
+
+2. **Configure PostgreSQL for logical replication:**
+   ```bash
+   # Edit PostgreSQL config
+   sudo sed -i 's/wal_level = replica/wal_level = logical/' /etc/postgresql/16/main/postgresql.conf
+
+   # Restart PostgreSQL
+   sudo systemctl restart postgresql
+   ```
+
+3. **Install dependencies:**
+   ```bash
+   # Phoenix dependencies
+   cd phoenix && mix deps.get
+
+   # React dependencies  
+   cd ../frontend && npm install
+   cd ..
+   ```
+
+4. **Setup database:**
+   ```bash
+   cd phoenix && mix ecto.setup
+   cd ..
+   ```
+
+## 🎯 Running the Application
+
+Use the main start script for the best experience:
+
+```bash
+./start.sh
+```
+
+### Options:
+
+1. **🚀 Production Mode** - Single Phoenix server serves everything
+   - React app built and served by Phoenix
+   - No CORS complexity
+   - Access at: `http://localhost:4000`
+
+2. **🔧 Development Mode** - Separate servers with hot reload
+   - Phoenix backend: `http://localhost:4000`
+   - React frontend: `http://localhost:5173` (with hot reload)
+
+3. **🧪 Backend Only** - Phoenix server only
+   - Useful for API testing
+   - Frontend can be started separately later
+
+## 🛠️ Manual Commands
+
+### Phoenix Backend
+```bash
+cd phoenix
+mix phx.server
+# Runs at http://localhost:4000
+```
+
+### React Frontend
+```bash
+cd frontend
+npm run dev
+# Runs at http://localhost:5173
+```
+
+### Production Build
+```bash
+cd frontend
+npm run build
+cp -r dist/* ../phoenix/priv/static/
+cd ../phoenix
+mix phx.server
+# Single server at http://localhost:4000
+```
+
+## 🔧 Development
+
+### Project Features
+
+- **Real-time Sync**: Changes in one browser tab instantly appear in others
+- **Offline Support**: Works offline, syncs when connection returns
+- **Optimistic Updates**: UI updates immediately, then syncs to server
+- **Conflict Resolution**: ElectricSQL handles data conflicts automatically
+
+### Key Technologies
+
+- **Phoenix.Sync**: Embedded ElectricSQL for real-time data sync
+- **@electric-sql/react**: React hooks for shape-based data sync
+- **PostgreSQL**: Logical replication for change data capture
+- **Vite**: Fast React development and building
+
+### API Endpoints
+
+- `GET /api/health` - Health check
+- `GET /shapes/todos` - ElectricSQL shape endpoint for real-time sync
+- `GET /api/todos` - Get all todos
+- `POST /api/todos` - Create new todo
+- `PUT /api/todos/:id` - Update todo
+- `DELETE /api/todos/:id` - Delete todo
+
+## 🧪 Testing
+
+```bash
+cd phoenix
+mix test
+```
+
+## 📦 Deployment
+
+The application is designed for single-server deployment in production:
+
+1. Build the React app
+2. Copy static files to Phoenix
+3. Deploy Phoenix server
+4. Configure PostgreSQL with logical replication
+
+## 🎯 Key Benefits
+
+- **No CORS Issues**: Single-origin deployment
+- **Real-time**: Instant updates across all clients  
+- **Scalable**: PostgreSQL replication handles high loads
+- **Developer Friendly**: Hot reload in development
+- **Production Ready**: Optimized static assets
+
+## 📚 Learn More
+
+- [ElectricSQL Documentation](https://electric-sql.com/docs)
+- [Phoenix Framework](https://phoenixframework.org/)
+- [React Documentation](https://react.dev/)
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
diff --git a/examples/phoenix-todo-app/frontend/index.html b/examples/phoenix-todo-app/frontend/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Phoenix Electric Todo App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>