Superglue

The minimal Consumer surface Superglue depends on. Pass an instance of this (e.g. createConsumer('/cable') from @rails/actioncable or createCable() from @anycable/web) as cable to createApp.

Properties¶

Property	Type	Defined in
`subscriptions`	`Subscriptions`	types/cable.ts:60

Type Aliases¶

ChannelNameWithParams¶

ChannelNameWithParams = {[key: string]: undefined | string | number | boolean; channel: string; }

Defined in: types/cable.ts:15

A channel identifier. Either a bare channel name string or an object with a channel key plus arbitrary identifier params.

Indexable¶

[key: string]: undefined | string | number | boolean

Properties¶

channel¶

channel: string

Defined in: types/cable.ts:16

Functions¶

webVisit()¶

webVisit(store: SuperglueStore, path: string, options?: VisitProps): Promise\<VisitResult | ErrorResult>

Defined in: action_creators/web.ts:18

Web specific wrapper around the visit thunk adding asset-refresh when the response indicates the client bundle is stale.

Returns a never-settling promise on that branch so the chain terminates with the browser unload.

Parameters¶

Parameter	Type
`store`	`SuperglueStore`
`path`	`string`
`options?`	`VisitProps`

Returns¶

Promise\<VisitResult | ErrorResult>

webRemote()¶

webRemote(store: SuperglueStore, path: string, options?: RemoteProps): Promise\<Result | ErrorResult>

Defined in: action_creators/web.ts:39

Web specific wrapper around the remote thunk. Just a passthrough.

Parameters¶

Parameter	Type
`store`	`SuperglueStore`
`path`	`string`
`options?`	`RemoteProps`

Returns¶

Promise\<Result | ErrorResult>

toFragmentRef()¶

toFragmentRef\<T, P>(id: string): FragmentRef\<T, P>

Defined in: hooks/useFragment.tsx:14

Converts a string ID to a typed FragmentRef.

Type Parameters¶

Type Parameter	Default type
`T`	-
`P` extends `boolean`	`false`

Parameters¶

Parameter	Type
`id`	`string`

Returns¶

FragmentRef\<T, P>

Example¶

const author = useFragment(toFragmentRef<Author>("author_123"))

useFragment()¶

useFragment\<T, P>(fragmentRef: FragmentRef\<T, P>, options?: ValidateOption): P extends true ? T : undefined | T

Defined in: hooks/useFragment.tsx:62

Returns a proxy for accessing a fragment's content from the store.

Passing in a fragment reference scopes the tracking of fragments to that hook usage. This is useful in performance scenarios where you want a child component to update, but not the parent.

import {unproxy} from '@thoughtbot/superglue'

const content = useContent()
const rawContent = unproxy(content)

<h1>{content.title}</h1>
<SlidingCart cartRef={rawContent.cart} />

then in SlidingCart

const SlidingCart = (cartRef) => {
  const cart = useFragment(cartRef)
}

SlidingCart will update only if the fragment referenced by cartRef updates.

Type Parameters¶

Type Parameter	Description
`T`	The data type being accessed
`P` extends `boolean`	Whether the fragment is guaranteed to be present

Parameters¶

Parameter	Type	Description
`fragmentRef`	`FragmentRef`\<`T`, `P`>	A typed fragment reference
`options?`	`ValidateOption`	-

Returns¶

P extends true ? T : undefined | T

Reactive proxy to fragment data. Returns T if present, T | undefined otherwise.

Example¶

// Access fragment via unproxied ref
const rawContent = unproxy(content)
const user = useFragment(rawContent.user)

// Access fragment via string ID
const cart = useFragment(toFragmentRef<Cart>("cart_123"))

useUpdateContent()¶

useUpdateContent(): \<T>(pageKey: string, updater: (draft: T) => void) => void

Defined in: hooks/useUpdateContent.tsx:9

Returns¶

\<T>(pageKey: string, updater: (draft: T) => void): void

Type Parameters¶

Type Parameter	Default type
`T`	`unknown`

Parameters¶

Parameter	Type
`pageKey`	`string`
`updater`	(`draft`: `T`) => `void`

Returns¶

void

createApp()¶

createApp(__namedParameters: CreateAppArgs & { _storeResult?: StoreResult; }): CreateAppResult

Defined in: index.tsx:80

Bootstrap a Superglue application. Performs all of the per-request setup (resetting the store, building visit/remote, installing history, seeding the initial page) and returns a { Provider, Outlet } pair the caller can arrange in their own React tree.

const { Provider, Outlet, ujs } = createApp({
  initialPage: window.SUPERGLUE_INITIAL_PAGE_STATE,
  baseUrl: location.origin,
  path: location.pathname + location.search + location.hash,
  mapping: pageIdentifierToPageComponent,
  buildVisitAndRemote,
})

createRoot(el).render(
  <div onClick={ujs.onClick} onSubmit={ujs.onSubmit}>
    <Provider>
      <AppLayout>
        <Outlet />
      </AppLayout>
    </Provider>
  </div>
)