useShape
<script setup lang="ts">
const { data, isLive, error } = await useShape('/api/shapes/todos')
</script>
Auto-imported by the module.
Types
Routes in server/api/shapes/ that pass a Drizzle table to proxyShape are
typed: data is Ref<(typeof todos.$inferSelect)[]> without a type argument, and dynamic routes
([id].get.ts) match any value in their segment. The module generates
.nuxt/types/wervt-shapes.d.ts from the route files; a new route shows up after nuxt prepare or
while nuxt dev runs.
For other routes, pass the row type yourself: useShape<Todo>('/api/other').
Values match what Drizzle reads: timestamp and timestamptz arrive as Date (keep Drizzle's
default mode: 'date'), bigint as BigInt, numeric and date as strings, json parsed.
Parameters
| Type | ||
|---|---|---|
path | string | A route that serves a shape with proxyShape. |
options.key | string | Payload key, defaults to the path. |
options.live | boolean | Keep the rows live on the client. Default true. |
Returns
| Type | ||
|---|---|---|
data | ShallowRef<T[]> | Current rows, in no particular order. Sort with computed. |
isLive | Ref<boolean> | true once the client stream is up to date. |
unauthorized | Ref<boolean> | true when the route refused the snapshot for lack of a user (401). |
error | Ref<unknown> | Loading or streaming error. |
Behaviour
- Server: loads the shape's current rows through the route in-process (cookies and
authorizationare forwarded) and stores rows, offset and shape handle in the payload. The rows come from Postgres, not from the shape's log, so frequent updates don't slow down rendering. - Client: starts an Electric
ShapeStreamfrom the stored offset on mount and applies inserts, updates (merged into the existing row) and deletes. Amust-refetchfrom Electric clears the rows and reloads. - On client-side navigation without SSR, the snapshot is loaded in the browser first.
- Shared: every
useShapewith the same path (orkey) in a tab shares one stream and the samedata,errorandisLiverefs, so a list and a counter on the same shape open one connection. Once no component uses the shape, its stream stays open for 10 seconds: navigating to another page with the same shape renders right away, without a new snapshot. - On the server nothing is shared: each request loads its own snapshot.
- No user: when the route answers 401 (it requires a signed-in user and there is none,
like an anonymous visitor of a public app or the deploy's page check),
datastays empty,errorstaysnull,unauthorizedistrueand the shape doesn't go live. Nothing is logged: it's the route's expected answer, not a failure. Useunauthorizedto show "sign in" instead of an empty state. Signing in reloads the page, which loads the rows.
preloadShape
<NuxtLink to="/todos" @mouseenter="preloadShape('/api/shapes/todos')">Todos</NuxtLink>
Opens the shape before it's needed, e.g. when a link is hovered, and resolves once its rows are up
to date. The page that then calls useShape with that path renders from those rows instead of
fetching the snapshot. A preloaded shape nobody uses closes after 30 seconds. Client only; on the
server it does nothing. Auto-imported, typed like useShape.