{"id":26124773,"url":"https://github.com/vldmrgnn/starfx-electric","last_synced_at":"2026-06-30T17:32:15.490Z","repository":{"id":268765407,"uuid":"904614978","full_name":"VldMrgnn/starfx-electric","owner":"VldMrgnn","description":"Example for integrating Starfx  with  ElectricSQL","archived":false,"fork":false,"pushed_at":"2024-12-20T19:03:37.000Z","size":225,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-10T16:50:27.257Z","etag":null,"topics":["electricsql","poc","starfx"],"latest_commit_sha":null,"homepage":"https://swiz.ro/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VldMrgnn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-17T08:29:33.000Z","updated_at":"2024-12-20T19:03:41.000Z","dependencies_parsed_at":"2024-12-18T19:41:51.212Z","dependency_job_id":"feaa4dab-91df-40bf-82a9-2b5c717b0db7","html_url":"https://github.com/VldMrgnn/starfx-electric","commit_stats":null,"previous_names":["vldmrgnn/starfx-electric"],"tags_count":0,"template":false,"template_full_name":"VldMrgnn/starfx-explorations","purl":"pkg:github/VldMrgnn/starfx-electric","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VldMrgnn%2Fstarfx-electric","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VldMrgnn%2Fstarfx-electric/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VldMrgnn%2Fstarfx-electric/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VldMrgnn%2Fstarfx-electric/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VldMrgnn","download_url":"https://codeload.github.com/VldMrgnn/starfx-electric/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VldMrgnn%2Fstarfx-electric/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34977667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electricsql","poc","starfx"],"created_at":"2025-03-10T16:50:10.570Z","updated_at":"2026-06-30T17:32:15.466Z","avatar_url":"https://github.com/VldMrgnn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Proof of Concept: Integrating Starfx with ElectricSQL\n\n**Status:** *Work in Progress*\n\nThis proof of concept demonstrates how to integrate [Starfx](https://starfx.bower.sh/) with [ElectricSQL](https://electric-sql.com/). It showcases how to set up an ElectricSQL server, connect to a PostgreSQL database, and perform read and sync operations, as well as run a simple Node.js-based CRUD API.\n\n## Prerequisites\n\n1. **PostgreSQL Server**  \n   Ensure you have access to a running PostgreSQL instance.  \n   For installation and configuration, refer to the official [PostgreSQL documentation](https://www.postgresql.org/docs/).\n\n2. **ElectricSQL Server**  \n   Follow the [ElectricSQL installation guide](https://electric-sql.com/docs/guides/installation) to set up and run your ElectricSQL server.\n\n3. **Node.js and npm**  \n   Make sure you have [Node.js](https://nodejs.org/) and npm installed.\n\n## Setup Instructions\n\n1. **Clone the Repository**  \n   ```bash\n   git clone https://github.com/VldMrgnn/starfx-electric.git\n   cd starfx-electric\n   ```\n\n2. **Install Dependencies**  \n   ```bash\n   npm install\n   ```\n\n3. **Environment Variables**  \n   Create an `.env.development` file in the project root and define the following keys:\n   ```env\n   VITE_ELECTRIC_SERVICE=YOUR_ELECTRICSQL_SERVICE_URL\n   VITE_PROXY_URL=http://localhost:8033\n   ```\n    Also create a `.env.production` file in the project root and define the following\n    ```env\n    VITE_ELECTRIC_SERVICE=YOUR_ELECTRICSQL_SERVICE_URL\n    VITE_PROXY_URL=https://yourdomain.com\n    ```\n\n    Replace `YOUR_ELECTRICSQL_SERVICE_URL` with the ElectricSQL service endpoint.\n\n   - **VITE_PROXY_URL**: Points to your Node.js server. The server setup is illustrated in the \"/server/README.md\" file.\n   - **VITE_ELECTRIC_SERVICE**: Defines the service endpoint for ElectricSQL’s sync functionality.\n\n## Running the Servers\n\n1. **ElectricSQL Server**  \n   Start the ElectricSQL server according to the official instructions.  \n   *(Refer to the [ElectricSQL documentation](https://electric-sql.com/docs/guides/installation) for details.)*\n\n2. **Node.js Backend Server**  \n   This project includes a simple Node.js HTTP server that provides CRUD operations on sample tables (e.g., `users`, `emails`).  \n   To start the server:\n   ```bash\n   npm run server\n   ```\n\n3. **Client Application**  \n   Start the development client:\n   ```bash\n   npm run dev\n   ```\n\n## Project Structure\n\n- **`src/server/server.js`**: A basic Node.js server handling CRUD operations.\n- **Client Side Files**: Located in `src`, configured to connect via the environment variables.\n\n## Notes\n\n- This is a first attempt for the integration of Starfx with ElectricSQL. Most likely in the future, a more refine and optimized version will be available.\n\n\u003c!-- this is a plan of action. not exactly accomplished yet. --\u003e\n \u003c!-- by schema -\u003e api-mdw = subscribe (initialize then go live)\n by api -\u003e start/stop stream\n by api -\u003e parse to store.\n by api -\u003e optimistic operations - insert, update, delete.\n --\u003e\n## Some More Explanation\n\n**How it works:**  \nElectricSQL pushes updates for the \"shapes\" we subscribe to.  \nThese shapes represent portions of PostgreSQL tables (or materialized views).\n\n**Push Updates:**  \nThese pushes are well-structured and follow a logical sequence. First, a “batch” of historical data is delivered, which is then used to initially populate the shape. After that, the shape on the client transitions into a \"live\" mode and begins receiving real-time updates. ElectricSQL manages this transition internally, providing significant value because synchronization can be more complex than it first appears.\n\n**Current Approach:**  \nFor the initial setup, the `ThunkCtx` interface was extended with fields specific to ElectricSQL (as guided by their documentation). This extended type is then used for subscriptions:\n\n```typescript\nexport interface EleCtx extends ThunkCtx {\n  table: string;\n  where?: string;\n  replica?: `full` | `default`;\n  columns?: string[];\n}\n```\n\nA middleware (`mdw-electric.ts`) has been introduced to leverage the shape subscriptions. This middleware remains active to continuously receive updates.\n\n**Bi-Directional Updates:**  \nCurrently, ElectricSQL does not handle pushing updates back to the database. That responsibility remains on our side, handled via the standard Starfx API.\n\n**Synchronization Strategy:**  \nElectricSQL suggests several synchronization strategies. Without committing fully to any predefined pattern, an optimistic update approach seems natural. To facilitate this, we need a local buffer of optimistic data that can be rolled back if necessary.\n\nIn this setup, the Starfx \"loaders\" table is used as a straightforward solution. Loaders respond quickly to both success and failure, come with built-in metadata handling, and support the optimistic update pattern well. Any rollback logic is managed by the synchronization process itself.\n\nTo support this, constants were defined for special loader keys, along with a simple but effective selector that prioritizes optimistic data over current data.\n\n**Looking Ahead:**  \nIt may be more elegant to define an “electric” slice, for example:\n\n```typescript\nslice.electric({\n   shape: `users`,\n   columns: [`id`, `name`, `email`],\n   where: `active = true`,\n   replica: `full`\n})\n```\n\nWith such a definition in place, the middleware could create subscriptions for all similarly defined slices, and pre-built thunks for CRUD operations could be introduced. Further consideration will be needed to determine when and how to start or stop these data streams.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvldmrgnn%2Fstarfx-electric","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvldmrgnn%2Fstarfx-electric","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvldmrgnn%2Fstarfx-electric/lists"}