Types

Interfaces¶

ParsedResponse¶

Properties¶

Property	Type	Defined in
`rsp`	`Response`	types/index.ts:172
`json`	`PageResponse`	types/index.ts:173

Defer¶

Defined in: types/index.ts:197

Defer is a node in the page response thats been intentionally filled with empty or placeholder data for the purposes of fetching it later.

You would typically use it with props_template for parts of a page that you know would be slower to load.

Properties¶

Property	Type	Description	Defined in
`url`	`string`	A url with props_at keypath in the query parameter to indicate how to dig for the data, and where to place the data.	types/index.ts:198
`type`	`"auto"` \| `"manual"`	When set to `auto` Superglue will automatically make the request using the `url`. When set to `manual`, Superglue does nothing, and you would need to manually use `remote` with the `url` to fetch the missing data.	types/index.ts:199
`path`	`string`	A keypath indicates how to dig for the data and where to place the data.	types/index.ts:200
`successAction`	`string`	a user defined action for Superglue to dispatch when auto deferement is successful	types/index.ts:201
`failAction`	`string`	a user defined action for Superglue to dispatch when auto deferement failed	types/index.ts:202

GraftResponse\<T>¶

Defined in: types/index.ts:238

The GraftResponse is responsible for partial updates using props_template's digging functionality in Superglue.

Type Parameters¶

Type Parameter	Default type
`T`	`JSONMappable`

Properties¶

Property	Type	Description	Defined in
`data`	`T`	-	types/index.ts:239
`componentIdentifier`	`string`	-	types/index.ts:240
`assets`	`string`[]	-	types/index.ts:241
`csrfToken?`	`string`	-	types/index.ts:242
`fragments`	`FragmentPath`[]	-	types/index.ts:243
`defers`	`Defer`[]	-	types/index.ts:244
`slices`	`JSONObject`	-	types/index.ts:245
`action`	`"graft"`	-	types/index.ts:246
`renderedAt`	`number`	-	types/index.ts:247
`path`	`string`	Used by superglue to replace the data at that location.	types/index.ts:249
`fragmentContext?`	`string`	-	types/index.ts:250

FragmentPath¶

Defined in: types/index.ts:287

A FragmentPath identifies a fragment inside of a PageResponse. Its used internally by Superglue to denormalize a page response into fragments, if any.

Properties¶

Property	Type	Description	Defined in
`id`	`string`	-	types/index.ts:288
`path`	`string`	A Keypath specifying the location of the fragment	types/index.ts:289

FragmentRef¶

Defined in: types/index.ts:300

A FragmentRef is a reference to a Fragment.

Properties¶

Property	Type	Description	Defined in
`__id`	`string`	A user supplied string identifying the fragment. This is usually created using props_template	types/index.ts:301

SuperglueState¶

Defined in: types/index.ts:320

A read only state that contains meta information about the current page.

Properties¶

Property	Type	Description	Defined in
`currentPageKey`	`string`	The PageKey (url pathname + search) of the current page. This can be pass to Remote.	types/index.ts:322
`search`	`Record`\<`string`, `string` \| `undefined`>	The query string object of the current url.	types/index.ts:324
`csrfToken?`	`string`	The Rails csrfToken that you can use for forms.	types/index.ts:326
`assets`	`string`[]	The tracked asset digests.	types/index.ts:328

RootState\<T>¶

Defined in: types/index.ts:335

The root state for a Superglue application. It occupies 2 keys in your app.

Type Parameters¶

Type Parameter	Default type
`T`	`JSONMappable`

Indexable¶

[name: string]: unknown

Properties¶

Property	Type	Description	Defined in
`superglue`	`SuperglueState`	Contains readonly metadata about the current page	types/index.ts:337
`pages`	`AllPages`\<`T`>	Every PageResponse that superglue recieves is stored here.	types/index.ts:339
`fragments`	`AllFragments`	-	types/index.ts:340

Meta¶

Defined in: types/index.ts:349

Meta is passed to the Promise when visit or remote resolves and contains additional information for navigation.

Extended by¶

VisitMeta

Properties¶

Property	Type	Description	Defined in
`pageKey`	`string`	The URL of the response converted to a pageKey. Superglue uses this to persist the SaveResponse to store, when that happens.	types/index.ts:354
`page`	`PageResponse`	The SaveResponse of the page	types/index.ts:356
`redirected`	`boolean`	Indicates if response was redirected	types/index.ts:358
`rsp`	`Response`	The original response object	types/index.ts:360
`fetchArgs`	`FetchArgs`	The original args passed to fetch.	types/index.ts:362
`componentIdentifier?`	`string`	The ComponentIdentifier extracted from the response.	types/index.ts:364
`needsRefresh`	`boolean`	`true` when assets locally are detected to be out of date	types/index.ts:366

VisitMeta¶

Defined in: types/index.ts:369

Meta is passed to the Promise when visit or remote resolves and contains additional information for navigation.

Extends¶

Meta

Properties¶

Property	Type	Description	Inherited from	Defined in
`pageKey`	`string`	The URL of the response converted to a pageKey. Superglue uses this to persist the SaveResponse to store, when that happens.	`Meta`.`pageKey`	types/index.ts:354
`page`	`PageResponse`	The SaveResponse of the page	`Meta`.`page`	types/index.ts:356
`redirected`	`boolean`	Indicates if response was redirected	`Meta`.`redirected`	types/index.ts:358
`rsp`	`Response`	The original response object	`Meta`.`rsp`	types/index.ts:360
`fetchArgs`	`FetchArgs`	The original args passed to fetch.	`Meta`.`fetchArgs`	types/index.ts:362
`componentIdentifier?`	`string`	The ComponentIdentifier extracted from the response.	`Meta`.`componentIdentifier`	types/index.ts:364
`needsRefresh`	`boolean`	`true` when assets locally are detected to be out of date	`Meta`.`needsRefresh`	types/index.ts:366
`navigationAction`	`NavigationAction`	The NavigationAction. This can be used for navigation.	-	types/index.ts:371

Handlers¶

Defined in: types/index.ts:414

Properties¶

Property	Type	Defined in
`onClick`	(`event`: `MouseEvent`\<`HTMLDivElement`, `MouseEvent`>) => `void`	types/index.ts:415
`onSubmit`	(`event`: `FormEvent`\<`HTMLDivElement`>) => `void`	types/index.ts:416

HistoryState¶

Defined in: types/index.ts:436

The state that is saved to history.state. Superglue stores information about the current page so that it can restore the page state when navigating back

Properties¶

Property	Type	Description	Defined in
`superglue`	`true`	Is always `true` so superglue can differentiate pages that have superglue enabled or not	types/index.ts:438
`pageKey`	`string`	The page key in SuperglueState to restore from	types/index.ts:440
`posX`	`number`	The scroll position X of the page	types/index.ts:442
`posY`	`number`	The scroll position Y of the page	types/index.ts:444

BasicRequestInit¶

Defined in: types/index.ts:470

A variation of RequestInit except the headers must be a regular object

Extends¶

RequestInit

Properties¶

Property	Type	Description	Overrides	Defined in
`headers?`	{[`key`: `string`]: `string`; }	A Headers object, an object literal, or an array of two-item arrays to set request's headers.	`RequestInit.headers`	types/index.ts:471

NavigationContextProps¶

Defined in: types/index.ts:519

Superglue comes with a Navigation component that provides a context with access to Visit, Remote and other useful tooling.

You can also use this to build your own <Link> component.

Properties¶

Property	Type	Description	Defined in
`navigateTo`	`NavigateTo`	-	types/index.ts:520
`visit`	`ApplicationVisit`	-	types/index.ts:521
`remote`	`ApplicationRemote`	-	types/index.ts:522
`pageKey`	`string`	The pagekey that's being used to render the current page component. Useful when used in combination with Remote to create requests that target the current page.	types/index.ts:523
`search`	`Record`\<`string`, `undefined` \| `string`>	The current pageKey (current url) query params as an object.	types/index.ts:524

NavigationProviderProps¶

Defined in: types/index.ts:536

This is the navigation component that gets used by ApplicationProps. The component takes a mapping of page components and swaps them when navigating and passes NavigateTo to all page components.

Properties¶

Property	Type	Description	Defined in
`history`	`History`	-	types/index.ts:537
`visit`	`ApplicationVisit`	-	types/index.ts:538
`remote`	`ApplicationRemote`	-	types/index.ts:539
`mapping`	`Record`\<`ComponentIdentifier`, `React.ComponentType`>	-	types/index.ts:540
`initialPageKey`	`string`	The PageKey that's to be used when first rendering. Used to determine the initial page component to show.	types/index.ts:541

BuildStore()¶

Defined in: types/index.ts:552

Provide this callback to ApplicationProps returning a Redux store for Superglue to use. This would be setup and generated for you in store.js. We recommend using using Redux toolkit's configureStore to build the store.

BuildStore(initialState: RootState, reducer: { superglue: (state: SuperglueState, action: Action) => SuperglueState; pages: (state: AllPages, action: Action) => AllPages; fragments: (state: AllFragments, action: Action) => AllFragments; }): SuperglueStore

Defined in: types/index.ts:553

Provide this callback to ApplicationProps returning a Redux store for Superglue to use. This would be setup and generated for you in store.js. We recommend using using Redux toolkit's configureStore to build the store.

Parameters¶

Parameter	Type	Description
`initialState`	`RootState`	A preconfigured intial state to pass to your store.
`reducer`	{ `superglue`: (`state`: `SuperglueState`, `action`: `Action`) => `SuperglueState`; `pages`: (`state`: `AllPages`, `action`: `Action`) => `AllPages`; `fragments`: (`state`: `AllFragments`, `action`: `Action`) => `AllFragments`; }	A preconfigured reducer
`reducer.superglue`	(`state`: `SuperglueState`, `action`: `Action`) => `SuperglueState`	-
`reducer.pages`	(`state`: `AllPages`, `action`: `Action`) => `AllPages`	-
`reducer.fragments`	(`state`: `AllFragments`, `action`: `Action`) => `AllFragments`	-

Returns¶

SuperglueStore

BuildVisitAndRemote()¶

Defined in: types/index.ts:568

Provide this callback to ApplicationProps returning a visit and remote function. These functions will be used by Superglue to power its UJS attributes and passed to your page components and NavigationContextProps. You may customize this functionality to your liking, e.g, adding a progress bar.

BuildVisitAndRemote(navigatorRef: RefObject\<null | { navigateTo: NavigateTo; }>, store: SuperglueStore): { visit: ApplicationVisit; remote: ApplicationRemote; }

Defined in: types/index.ts:569

Parameters¶

Parameter	Type	Description
`navigatorRef`	`RefObject`\<`null` \| { `navigateTo`: `NavigateTo`; }>
`store`	`SuperglueStore`

Returns¶

{ visit: ApplicationVisit; remote: ApplicationRemote; }

Name	Type	Defined in
`visit`	`ApplicationVisit`	types/index.ts:573
`remote`	`ApplicationRemote`	types/index.ts:574

SetupProps¶

Defined in: types/index.ts:578

Properties¶

Property	Type	Description	Defined in
`initialPage`	`SaveResponse`	The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb template, e.g., application/superglue.html.erb	types/index.ts:583
`baseUrl`	`string`	The base url prefixed to all calls made by `visit` and `remote`.	types/index.ts:588
`path`	`string`	The path of the current page. It should equal to the `location.pathname` + `location.search` + `location.hash`	types/index.ts:593
`store`	`SuperglueStore`	The exported store from store.js. If you used the generators it would contain slices for superglue, pages, and the flash.	types/index.ts:598
`buildVisitAndRemote`	`BuildVisitAndRemote`	A factory function that will return a `visit` and `remote` function. All of Superglue and UJS will use these functions. You should customize the function, for example, to add a progress bar.	types/index.ts:605
`history?`	`History`	An optional history object https://github.com/remix-run/history. If none is provided Superglue will create one for you.	types/index.ts:610
`navigatorRef`	`RefObject`\<`null` \| { `navigateTo`: `NavigateTo`; }>	A ref object created from the Application component that will be passed to buildVisitAndRemote	types/index.ts:614

ApplicationProps¶

Defined in: types/index.ts:622

Props for the Application component

Extends¶

ComponentPropsWithoutRef\<"div">

Properties¶

Property	Type	Description	Defined in
`initialPage`	`SaveResponse`	The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb template, e.g., application/superglue.html.erb	types/index.ts:628
`baseUrl`	`string`	The base url prefixed to all calls made by `visit` and `remote`.	types/index.ts:633
`path`	`string`	The path of the current page. It should equal to the `location.pathname` + `location.search` + `location.hash`	types/index.ts:638
`buildVisitAndRemote`	`BuildVisitAndRemote`	A factory function that will return a `visit` and `remote` function. All of Superglue and UJS will use these functions. You should customize the function, for example, to add a progress bar.	types/index.ts:645
`mapping`	`Record`\<`string`, `React.ComponentType`>	A mapping between your page props and page component. This is setup for you in page_to_page_mapping.	types/index.ts:650
`history?`	`History`	An optional history object https://github.com/remix-run/history. If none is provided Superglue will create one for you.	types/index.ts:655
`store`	`SuperglueStore`	The exported store from store.js. If you used the generators it would contain slices for superglue, pages, and the flash.	types/index.ts:660

Type Aliases¶

PageKey¶

PageKey = string

Defined in: types/index.ts:23

A PageKey is a combination of a parsed URL's pathname + query string. No hash.

*

Example¶

/posts?foobar=123

RestoreStrategy¶

RestoreStrategy = "fromCacheOnly" | "revisitOnly" | "fromCacheAndRevisitInBackground"

Defined in: types/index.ts:39

Defines the behavior when navigating to a page that is already stored on the client. For example, when navigating back.

When the page already exists in the store: - fromCacheOnly - Use the cached page that exists on the store, only. - revisitOnly - Ignore the cache and make a request for the latest page. If the response was 200, the NavigationAction would be none as we don't want to push into history. If the response was redirected, the NavigationAction would be set to replace. - fromCacheAndRevisitInBackground - Use the cache version of the page so superglue can optimistically navigate to it, then make an additional request for the latest version.

NavigationAction¶

NavigationAction = "push" | "replace" | "none"

Defined in: types/index.ts:48

A NavigationAction is used to tell Superglue to history.push, history.replace or do nothing.

ComponentIdentifier¶

ComponentIdentifier = string

Defined in: types/index.ts:54

An identifier that Superglue will uses to determine which page component to render with your page response.

Keypath¶

Keypath = string

Defined in: types/index.ts:78

A keypath is a string representing the location of a piece of data. Superglue uses the keypath to dig for or update data.

Examples¶

Object access

data.header.avatar

Array access

data.body.posts.0.title

Array with lookahead

data.body.posts.post_id=foobar.title

JSONPrimitive¶

JSONPrimitive = string | number | boolean | null | undefined

Defined in: types/index.ts:85

A JSON Primitive value

JSONObject¶

JSONObject = {[key: string]: JSONValue; }

Defined in: types/index.ts:90

A JSON Object

Index Signature¶

[key: string]: JSONValue

JSONMappable¶

JSONMappable = JSONValue[] | JSONObject

Defined in: types/index.ts:97

A JSON Object or an array of values

JSONKeyable¶

JSONKeyable = JSONObject[] | JSONObject

Defined in: types/index.ts:102

A array of JSON key value objects or a JSON Object

JSONValue¶

JSONValue = JSONPrimitive | JSONMappable

Defined in: types/index.ts:107

A primitive or a mappable object

Fragment\<T, Present>¶

Fragment\<T, Present> = { __id: string; __fragmentType?: T; __required?: Present extends boolean ? Present : false; }

Defined in: types/index.ts:146

A Fragment is a rendered Rails partial with an identity. The use of this type is optional, but it makes usage with unproxy and useSetFragment type friendly.

In general, Fragments enable normalized state management where Rails partials become referenceable entities on the client. The server renders partials as fragments with unique IDs, then Superglue normalizes them into a separate fragments store while replacing the original data with fragment references.

Examples¶

{
  "data": { "cart": { "__id": "userCart" } },
  "fragments": [{ "type": "userCart", "path": ["cart"] }]
}

{
  pages: { "/page": { data: { cart: { __id: "userCart" } } } },
  fragments: { "userCart": { items: [...], totalCost: 69.97 } }
}

type PageData = {
  cart: Fragment<{ items: Item[]; totalCost: number }, true>;
  user?: Fragment<{ name: string; email: string }>; // Optional fragment
}

const content = useContent<PageData>()
const cart = content.cart // Resolves fragment reference to actual data

Type Parameters¶

Type Parameter	Default type
`T`	-
`Present`	`false`

Properties¶

__id¶

__id: string

Defined in: types/index.ts:148

The fragment ID *

__fragmentType?¶

optional __fragmentType: T

Defined in: types/index.ts:150

Phantom type, please ignore *

__required?¶

optional __required: Present extends boolean ? Present : false

Defined in: types/index.ts:152

Phantom type, please ignore *

Unproxy\<T>¶

Unproxy\<T> = T extends FragmentProxy ? FragmentRef : T extends Fragment\<unknown, unknown> ? FragmentRef : T extends infer U[] ? Unproxy\<U>[] : T extends object ? { [K in keyof T]: Unproxy<T[K]> } : T

Defined in: types/index.ts:159

Utility type for unproxy that converts Fragment types to fragment references. This recursively processes objects and arrays to convert Fragment to { __id: string }.

Type Parameters¶

Type Parameter
`T`

SaveResponse\<T>¶

SaveResponse\<T> = { data: T; componentIdentifier: ComponentIdentifier; assets: string[]; csrfToken?: string; fragments: FragmentPath[]; defers: Defer[]; slices: JSONObject; action: "savePage"; renderedAt: number; restoreStrategy: RestoreStrategy; }

Defined in: types/index.ts:209

The SaveResponse response is responsible for persisting a full page visit in Superglue.

Type Parameters¶

Type Parameter	Default type
`T`	`JSONMappable`

Properties¶

data¶

data: T

Defined in: types/index.ts:210

componentIdentifier¶

componentIdentifier: ComponentIdentifier

Defined in: types/index.ts:211

assets¶

assets: string[]

Defined in: types/index.ts:212

csrfToken?¶

optional csrfToken: string

Defined in: types/index.ts:213

fragments¶

fragments: FragmentPath[]

Defined in: types/index.ts:214

defers¶

defers: Defer[]

Defined in: types/index.ts:215

slices¶

slices: JSONObject

Defined in: types/index.ts:216

action¶

action: "savePage"

Defined in: types/index.ts:217

renderedAt¶

renderedAt: number

Defined in: types/index.ts:219

restoreStrategy¶

restoreStrategy: RestoreStrategy

Defined in: types/index.ts:220

Page\<T>¶

Page\<T> = SaveResponse\<T> & { savedAt: number; }

Defined in: types/index.ts:226

A Page is a SaveResponse that's been saved to the store

Type declaration¶

Name	Type	Defined in
`savedAt`	`number`	types/index.ts:227

Type Parameters¶

Type Parameter	Default type
`T`	`JSONMappable`

StreamMessage¶

StreamMessage = { data: JSONMappable; fragmentIds: string[]; handler: "append" | "prepend" | "save"; options: Record\<string, string>; }

Defined in: types/index.ts:253

Properties¶

data¶

data: JSONMappable

Defined in: types/index.ts:254

fragmentIds¶

fragmentIds: string[]

Defined in: types/index.ts:255

handler¶

handler: "append" | "prepend" | "save"

Defined in: types/index.ts:256

options¶

options: Record\<string, string>

Defined in: types/index.ts:257

StreamResponse¶

StreamResponse = { data: StreamMessage[]; fragments: FragmentPath[]; assets: string[]; csrfToken?: string; action: "handleStreamResponse"; renderedAt: number; slices: JSONObject; }

Defined in: types/index.ts:260

Properties¶

data¶

data: StreamMessage[]

Defined in: types/index.ts:261

fragments¶

fragments: FragmentPath[]

Defined in: types/index.ts:262

assets¶

assets: string[]

Defined in: types/index.ts:263

csrfToken?¶

optional csrfToken: string

Defined in: types/index.ts:264

action¶

action: "handleStreamResponse"

Defined in: types/index.ts:265

renderedAt¶

renderedAt: number

Defined in: types/index.ts:266

slices¶

slices: JSONObject

Defined in: types/index.ts:267

PageResponse¶

PageResponse = GraftResponse | SaveResponse | StreamResponse

Defined in: types/index.ts:275

A PageResponse can be either a GraftResponse, SaveResponse. or a StreamResponse Its meant to be implemented by the server and if you are using superglue_rails, the generators will handle all cases.

AllPages\<T>¶

AllPages\<T> = Record\<PageKey, Page\<T>>

Defined in: types/index.ts:308

The store where all page responses are stored indexed by PageKey. You are encouraged to mutate the Pages in this store.

Type Parameters¶

Type Parameter	Default type
`T`	`JSONMappable`

AllFragments¶

AllFragments = Record\<string, JSONMappable>

Defined in: types/index.ts:314

The store where all page responses are stored indexed by PageKey. You are encouraged to mutate the Pages in this store.

VisitCreator()¶

VisitCreator = (input: string | PageKey, options: VisitProps) => VisitMetaThunk

Defined in: types/index.ts:380

VisitCreator is a Redux action creator that returns a thunk. Use this to build the Visit function. Typically it's already generated in application_visit.js

Parameters¶

Parameter	Type
`input`	`string` \| `PageKey`
`options`	`VisitProps`

Returns¶

VisitMetaThunk

RemoteCreator()¶

RemoteCreator = (input: string | PageKey, options: RemoteProps) => MetaThunk

Defined in: types/index.ts:389

RemoteCreator is a Redux action creator that returns a thunk. Use this to build the Remote function. Typically it's already generated in application_visit.js

Parameters¶

Parameter	Type
`input`	`string` \| `PageKey`
`options`	`RemoteProps`

Returns¶

MetaThunk

Dispatch¶

Dispatch = ThunkDispatch\<RootState, undefined, Action>

Defined in: types/index.ts:394

SuperglueStore¶

SuperglueStore = EnhancedStore\<RootState, Action, Tuple\<[StoreEnhancer\<{ dispatch: Dispatch; }>, StoreEnhancer]>>

Defined in: types/index.ts:401

A Store created with Redux Toolkit's configureStore setup with reducers from Superglue. If you are using superglue_rails this would have been generated for you in store.js and setup correctly in application.js

UJSHandlers()¶

UJSHandlers = ({ ujsAttributePrefix, visit, remote, store, }: { ujsAttributePrefix: string; visit: ApplicationVisit; remote: ApplicationRemote; store: SuperglueStore; }) => Handlers

Defined in: types/index.ts:419

Parameters¶

Parameter	Type
`{ ujsAttributePrefix, visit, remote, store, }`	{ `ujsAttributePrefix`: `string`; `visit`: `ApplicationVisit`; `remote`: `ApplicationRemote`; `store`: `SuperglueStore`; }
`{ ujsAttributePrefix, visit, remote, store, }.ujsAttributePrefix`	`string`
`{ ujsAttributePrefix, visit, remote, store, }.visit`	`ApplicationVisit`
`{ ujsAttributePrefix, visit, remote, store, }.remote`	`ApplicationRemote`
`{ ujsAttributePrefix, visit, remote, store, }.store`	`SuperglueStore`

Returns¶

Handlers

SaveAndProcessPageThunk¶

SaveAndProcessPageThunk = ThunkAction\<Promise\<void>, RootState, undefined, Action>

Defined in: types/index.ts:447

MetaThunk¶

MetaThunk = ThunkAction\<Promise\<Meta>, RootState, undefined, Action>

Defined in: types/index.ts:454

VisitMetaThunk¶

VisitMetaThunk = ThunkAction\<Promise\<VisitMeta>, RootState, undefined, Action>

Defined in: types/index.ts:455

DefermentThunk¶

DefermentThunk = ThunkAction\<Promise\<void[]>, RootState, undefined, Action>

Defined in: types/index.ts:462

NavigateTo()¶

NavigateTo = (path: Keypath, options: { action: NavigationAction; }) => boolean

Defined in: types/index.ts:500

Passed to every page component and also available as part of a NavigationContext:

import { NavigationContext } from '@thoughtbot/superglue';

const { navigateTo } = useContext(NavigationContext)

Manually navigate using pages that exists in the store and restores scroll position. navigateTo is what Visit in your application_visit.js ultimately calls.

If there is an existing page in your store navigateTo will restore the props, render the correct component, and return true. Otherwise, it will return false. This is useful if you want to restore an existing page before making a call to visit or remote.