AgentSkillsCN

electric

借助 ElectricSQL（HTTP Postgres 同步）与 TanStack DB，打造本地优先的应用程序。适用于配置 Electric 形状与代理路由、设定 electricCollectionOptions 选项、通过 txid 握手实现乐观突变，或排查实时查询、安全性问题以及部署过程中的各类故障。

SKILL.md
--- frontmatter
name: electric
description: Build local-first apps with ElectricSQL (HTTP Postgres sync) and TanStack DB. Use when wiring Electric shapes and proxy routes, configuring electricCollectionOptions, implementing optimistic mutations with txid handshake, or troubleshooting live queries, security, and deployment.

ElectricSQL + TanStack DB

Overview

Use this skill to implement the Electric + TanStack DB stack for local-first apps. Focus on secure proxying, shape configuration, optimistic write flow, and live queries. The full guide is in references/electric-docs.md.

Golden path

  1. •Create a project and run migrations.
  2. •Add an Electric proxy route on the server and inject SOURCE_ID/SECRET.
  3. •Create Electric collections on the client with electricCollectionOptions.
  4. •Implement write handlers that call the API and return a Postgres txid.
  5. •Use live queries for reads and joins.
  6. •Validate performance, auth, and deployment setup.

Security rules (always)

  • •Never expose SOURCE_SECRET to the browser.
  • •Do not call Electric directly from production clients.
  • •Define shapes server-side; do not allow client-defined tables or WHERE clauses.

Write path contract

  • •Optimistic mutation in TanStack DB.
  • •API writes to Postgres and returns txid.
  • •Client awaits txid on the Electric stream before dropping optimistic state.

Shape rules

  • •Shapes are single-table with optional where/columns.
  • •Include primary key when using columns.
  • •Shapes are immutable per subscription; create a new collection for dynamic shapes.

Troubleshooting

  • •UI flicker usually means missing txid handshake.
  • •Slow shapes in dev can be HTTP/1.1 limits; use HTTP/2 proxy or Electric Cloud.
  • •Ensure proxy forwards Electric query params and preserves headers.

References

  • •references/electric-docs.md contains the full documentation snapshot.