feat: add `@electric-sql/start` package that interacts with Cloud #3595

thruflo · 2025-12-12T17:54:26Z

@icehaunter I remember now that this WIP was me pulling out the start package specifics to a clean PR, then fixing stuff in it. See the TODO.md. When verified as working, this PR can be merged and the @electric-sql/start package published, and then the quickstart branch can be published with just the website changes. That's the idea ...

netlify · 2025-12-12T17:56:43Z

✅ Deploy Preview for electric-next ready!

Name	Link
🔨 Latest commit	`0371010`
🔍 Latest deploy log	https://app.netlify.com/projects/electric-next/deploys/693c56d55fe71300085ec9bb
😎 Deploy Preview	https://deploy-preview-3595--electric-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

codecov · 2025-12-22T15:08:46Z

Codecov Report

❌ Patch coverage is 89.65517% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.91%. Comparing base (7e2da0d) to head (d1d4d1d).
⚠️ Report is 12 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/start/src/cli.ts	80.35%	11 Missing ⚠️
packages/start/src/electric-api.ts	93.22%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3595      +/-   ##
==========================================
- Coverage   88.13%   87.91%   -0.22%     
==========================================
  Files          18       21       +3     
  Lines        1643     1821     +178     
  Branches      412      462      +50     
==========================================
+ Hits         1448     1601     +153     
- Misses        193      218      +25     
  Partials        2        2

Flag	Coverage Δ
packages/experimental	`87.73% <ø> (ø)`
packages/react-hooks	`86.48% <ø> (ø)`
packages/start	`89.65% <89.65%> (?)`
packages/typescript-client	`93.66% <ø> (-0.10%)`	⬇️
packages/y-electric	`56.05% <ø> (+0.38%)`	⬆️
typescript	`87.91% <89.65%> (-0.22%)`	⬇️
unit-tests	`87.91% <89.65%> (-0.22%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

thruflo · 2025-12-22T19:22:05Z

The trouble with the https://tanstack-start-db-electric-starter.localhost approach in the current starter is it doesn't work in Safari:

There's no actual need to use the subdomain like this. We can just run on a normal / default vite address.

In the port-sharing version of the start I did, #3228, I solve this and also remove the need for Caddy and avoid the double security popup when installing. For me, running this starter from scratch on new macOS, I get two system-level security popups and a console warning when I run pnpm run dev on the starter.

thruflo · 2025-12-22T19:25:55Z

There's also another DX problem which is that running the migrations after the dev server makes it likely to forget to run the migrations. You then open the web browser, try to login and get an auth error. I think it may be better to just do less magic and have explicit instructions in the README and docker version of the Quickstart to (a) ensure you have caddy and have run caddy trust (b) run the backend (c) then run the migrations (d) then run the dev server. This would mean adjusting the dev command to not run the backend services.

thruflo · 2025-12-24T00:06:46Z

@icehaunter have updated the readme as envisaged on call earlier. Needs your changes for this to actually work.

thruflo · 2025-12-24T01:35:59Z

Quickstart updated to match this: #3114

thruflo · 2025-12-24T01:43:06Z

packages/start/src/cli.ts

+    console.log(``)
+    console.log(`Next steps:`)
+    console.log(`  cd ${appName}`)
+    console.log(`  pnpm install`)


The idea here: https://deploy-preview-3114--electric-next.netlify.app/docs/quickstart#get-started is that the start command wraps up install and migrate (because it can and it just simplifies the Quickstart flow).

(This also affects the .stackblitzrc as to whether it installs reps or not).

Any reason not to switch this over (aside from explicitness)?

We can do a manual pnpm install & migrate if you want, although I slightly prefer the explicitness and not auto-installing stuff. Is it also worth noting in the quickstart guide the fact that NeonDB databases will expire in about an hour unless claimed?

This supports StackBlitz forking and generally enables switching a starter template to use cloud provisioned resources via `npx @electric-sql/start .`. Summary of changes: 1. cli.ts - Added . as valid app name: - Line 11: Added usage hint for . mode - Line 18-19: Skip alphanumeric validation when appName === '.' - Line 27-31: Show "Configuring current directory..." instead of "Creating app: ." - Line 44-46: Skip "cd" instruction when using . 2. template-setup.ts - Skip gitpick for current directory: - Line 25: appPath = appName === '.' ? process.cwd() : join(process.cwd(), appName) - Lines 29-35: Only run gitpick when appName !== '.' 3. Test files - Added 5 new tests and fixed 1 pre-existing incorrect expectation This enables the StackBlitz flow where `npx @electric-sql/start .` configures an existing template directory without re-cloning it.

thruflo · 2025-12-24T02:18:13Z

@icehaunter see 9f4db14

icehaunter · 2025-12-24T10:28:55Z

@thruflo - addressed your feedback in bb25a02

Only one dev command, pnpm dev, driven by .env file
ELECTRIC_URL being set takes the precedence - if you want
to run against docker, you need to unset it or set to the docker url
@electric-sql/start will run pnpm install & pnpm migrate immediately to match quickstart
Made sure Caddy runs on localhost:4000 with an HTTPS cert instead of .localhost domain

1. Only one dev command, `pnpm dev`, driven by `.env` file 2. `ELECTRIC_URL` being set takes the precedence - if you want to run against docker, you need to unset it or set to the docker url 3. `@electric-sql/start` will run `pnpm install` & `pnpm migrate` immediately to match quickstart 4. Made sure Caddy runs on `localhost:4000` with an HTTPS cert instead of `.localhost` domain

A simpler Quickstart based on the tanstack-db.web-starter and @electric-sql/start package: https://deploy-preview-3114--electric-next.netlify.app/docs/quickstart Relies on #3595 being finished and published and #3634 being merged and used to deploy the Quickstart demo.

icehaunter force-pushed the thruflo/start-package branch from 0371010 to 280c242 Compare December 22, 2025 15:07

wip: local WIP on start package.

75c9066

icehaunter force-pushed the thruflo/start-package branch from 280c242 to da43856 Compare December 22, 2025 15:08

This comment has been minimized.

Sign in to view

icehaunter force-pushed the thruflo/start-package branch 3 times, most recently from ac678e0 to fc7cc2b Compare December 22, 2025 15:30

icehaunter changed the title ~~wip: local WIP on start package.~~ feat: add @electric-sql/start package that interacts with Cloud Dec 22, 2025

icehaunter force-pushed the thruflo/start-package branch from fc7cc2b to 3451d04 Compare December 22, 2025 15:37

icehaunter marked this pull request as ready for review December 22, 2025 15:37

icehaunter force-pushed the thruflo/start-package branch 2 times, most recently from 3156614 to e3e7d5e Compare December 22, 2025 16:06

This comment has been minimized.

Sign in to view

fixed the packages/start

3bdbd55

icehaunter force-pushed the thruflo/start-package branch from e3e7d5e to 3bdbd55 Compare December 22, 2025 16:16

icehaunter added 2 commits December 22, 2025 19:33

made it work on netlify

a4e3527

fixed defaults dev for tanstack db

bf51c4d

This comment has been minimized.

Sign in to view

thruflo added 2 commits December 23, 2025 16:05

examples: less magic in the starter README.

421a023

examples: also update the AGENTS.md.

c980e52

thruflo mentioned this pull request Dec 24, 2025

New quickstart package and docs. #3114

Merged

thruflo commented Dec 24, 2025

View reviewed changes

icehaunter approved these changes Dec 24, 2025

View reviewed changes

icehaunter force-pushed the thruflo/start-package branch from 6544287 to bb25a02 Compare December 24, 2025 10:29

This comment has been minimized.

Sign in to view

icehaunter force-pushed the thruflo/start-package branch from bb25a02 to 02468b6 Compare December 24, 2025 11:02

updated the port

d1d4d1d

icehaunter merged commit 8ab953a into main Dec 24, 2025
14 of 15 checks passed

icehaunter deleted the thruflo/start-package branch December 24, 2025 16:10

icehaunter temporarily deployed to Pull request December 24, 2025 16:10 — with GitHub Actions Inactive

feat: add @electric-sql/start package that interacts with Cloud #3595

feat: add @electric-sql/start package that interacts with Cloud #3595

Uh oh!

Conversation

thruflo commented Dec 12, 2025

Uh oh!

netlify bot commented Dec 12, 2025

✅ Deploy Preview for electric-next ready!

Uh oh!

codecov bot commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

thruflo commented Dec 22, 2025

Uh oh!

thruflo commented Dec 22, 2025

Uh oh!

thruflo commented Dec 24, 2025

Uh oh!

thruflo commented Dec 24, 2025

Uh oh!

thruflo Dec 24, 2025

Choose a reason for hiding this comment

Uh oh!

icehaunter Dec 24, 2025

Choose a reason for hiding this comment

Uh oh!

thruflo commented Dec 24, 2025

Uh oh!

icehaunter commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: add `@electric-sql/start` package that interacts with Cloud #3595

feat: add `@electric-sql/start` package that interacts with Cloud #3595

codecov bot commented Dec 22, 2025 •

edited

Loading

icehaunter commented Dec 24, 2025 •

edited

Loading