Types

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.	lib/types/index.ts:137
`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.	lib/types/index.ts:138
`path`	`string`	A keypath indicates how to dig for the data and where to place the data.	lib/types/index.ts:139
`successAction`	`string`	a user defined action for Superglue to dispatch when auto deferement is successful	lib/types/index.ts:140
`failAction`	`string`	a user defined action for Superglue to dispatch when auto deferement failed	lib/types/index.ts:141

GraftResponse\<T>¶

The GraftResponse is a protocol, a shape that is responsible for partial updates using props_template's digging functionality in Superglue. Its meant to be implemented by the server and if you are using superglue_rails, the generators would have generated a props_template layout and view that would shape the graft responses for you.

Type Parameters¶

Type Parameter	Default type
`T`	`JSONMappable`

Properties¶

Property	Type	Description	Defined in
`data`	`T`	-	lib/types/index.ts:151
`componentIdentifier`	`string`	-	lib/types/index.ts:152
`assets`	`string`[]	-	lib/types/index.ts:153
`csrfToken?`	`string`	-	lib/types/index.ts:154
`fragments`	`Fragment`[]	-	lib/types/index.ts:155
`defers`	`Defer`[]	-	lib/types/index.ts:156
`slices`	`JSONObject`	-	lib/types/index.ts:157
`renderedAt`	`number`	-	lib/types/index.ts:159
`restoreStrategy`	`RestoreStrategy`	-	lib/types/index.ts:160
`action`	`"graft"`	-	lib/types/index.ts:182
`path`	`string`	Used by superglue to replace the data at that location.	lib/types/index.ts:183

Fragment¶

A Fragment identifies a cross cutting concern, like a shared header or footer.

Properties¶

Property	Type	Description	Defined in
`type`	`string`	A user supplied string identifying a fragment. This is usually created using props_template	lib/types/index.ts:201
`path`	`string`	A Keypath specifying the location of the fragment	lib/types/index.ts:202

SuperglueState¶

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.	lib/types/index.ts:217
`search`	`Record`\<`string`, `undefined` \| `string`>	The query string object of the current url.	lib/types/index.ts:219
`csrfToken?`	`string`	The Rails csrfToken that you can use for forms.	lib/types/index.ts:221
`assets`	`string`[]	The tracked asset digests.	lib/types/index.ts:223

RootState\<T>¶

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	lib/types/index.ts:232
`pages`	`AllPages`\<`T`>	Every PageResponse that superglue recieves is stored here.	lib/types/index.ts:234

Meta¶

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 VisitResponse to store, when that happens.	lib/types/index.ts:248
`page`	`VisitResponse`\<`JSONMappable`>	The VisitResponse of the page	lib/types/index.ts:250
`redirected`	`boolean`	Indicates if response was redirected	lib/types/index.ts:252
`rsp`	`Response`	The original response object	lib/types/index.ts:254
`fetchArgs`	`FetchArgs`	The original args passed to fetch.	lib/types/index.ts:256
`componentIdentifier`	`string`	The ComponentIdentifier extracted from the response.	lib/types/index.ts:258
`needsRefresh`	`boolean`	`true` when assets locally are detected to be out of date	lib/types/index.ts:260

VisitMeta¶

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 VisitResponse to store, when that happens.	`Meta`.`pageKey`	lib/types/index.ts:248
`page`	`VisitResponse`\<`JSONMappable`>	The VisitResponse of the page	`Meta`.`page`	lib/types/index.ts:250
`redirected`	`boolean`	Indicates if response was redirected	`Meta`.`redirected`	lib/types/index.ts:252
`rsp`	`Response`	The original response object	`Meta`.`rsp`	lib/types/index.ts:254
`fetchArgs`	`FetchArgs`	The original args passed to fetch.	`Meta`.`fetchArgs`	lib/types/index.ts:256
`componentIdentifier`	`string`	The ComponentIdentifier extracted from the response.	`Meta`.`componentIdentifier`	lib/types/index.ts:258
`needsRefresh`	`boolean`	`true` when assets locally are detected to be out of date	`Meta`.`needsRefresh`	lib/types/index.ts:260
`navigationAction`	`NavigationAction`	The NavigationAction. This can be used for navigation.	-	lib/types/index.ts:265

Handlers¶

Properties¶

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

HistoryState¶

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	lib/types/index.ts:332
`pageKey`	`string`	The page key in SuperglueState to restore from	lib/types/index.ts:334
`posX`	`number`	The scroll position X of the page	lib/types/index.ts:336
`posY`	`number`	The scroll position Y of the page	lib/types/index.ts:338

BasicRequestInit¶

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

Extends¶

RequestInit

Properties¶

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

NavigationContextProps¶

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`	-	lib/types/index.ts:414
`visit`	`ApplicationVisit`	-	lib/types/index.ts:415
`remote`	`ApplicationRemote`	-	lib/types/index.ts:416
`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.	lib/types/index.ts:417
`search`	`Record`\<`string`, `undefined` \| `string`>	The current pageKey (current url) query params as an object.	lib/types/index.ts:418

NavigationProviderProps¶

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`	-	lib/types/index.ts:431
`visit`	`ApplicationVisit`	-	lib/types/index.ts:432
`remote`	`ApplicationRemote`	-	lib/types/index.ts:433
`mapping`	`Record`\<`string`, `ComponentType`\<{}>>	-	lib/types/index.ts:434
`initialPageKey`	`string`	The PageKey that's to be used when first rendering. Used to determine the initial page component to show.	lib/types/index.ts:435

BuildStore()¶

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\<JSONMappable>, reducer: {superglue: superglueReducer;pages: pageReducer; }): SuperglueStore

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`\<`JSONMappable`>	A preconfigured intial state to pass to your store.
`reducer`	`object`	A preconfigured reducer
`reducer.superglue`	(`state`: `SuperglueState`, `action`: `Action`) => `SuperglueState`	-
`reducer.pages`	(`state`: `AllPages`, `action`: `Action`) => `AllPages`	-

Returns¶

SuperglueStore

Defined in¶

lib/types/index.ts:447

BuildVisitAndRemote()¶

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; }

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.

Parameters¶

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

Returns¶

{visit: ApplicationVisit;remote: ApplicationRemote; }

Name	Type	Defined in
`visit`	`ApplicationVisit`	lib/types/index.ts:467
`remote`	`ApplicationRemote`	lib/types/index.ts:468

Defined in¶

lib/types/index.ts:463

SetupProps¶

Properties¶

Property	Type	Description	Defined in
`initialPage`	`VisitResponse`\<`JSONMappable`>	The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb template, e.g., index.html.erb	lib/types/index.ts:477
`baseUrl`	`string`	The base url prefixed to all calls made by `visit` and `remote`.	lib/types/index.ts:482
`path`	`string`	The path of the current page. It should equal to the `location.pathname` + `location.search` + `location.hash`	lib/types/index.ts:487
`store`	`SuperglueStore`	The exported store from store.js. If you used the generators it would contain slices for superglue, pages, and the flash.	lib/types/index.ts:492
`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.	lib/types/index.ts:499
`history?`	`History`	An optional history object https://github.com/remix-run/history. If none is provided Superglue will create one for you.	lib/types/index.ts:504
`navigatorRef`	`RefObject`\<`null` \| {`navigateTo`: `NavigateTo`; }>	A ref object created from the Application component that will be passed to buildVisitAndRemote	lib/types/index.ts:508

ApplicationProps¶

Props for the Application component

Extends¶

ComponentPropsWithoutRef\<"div">

Properties¶

Property	Type	Description	Defined in
`initialPage`	`VisitResponse`\<`JSONMappable`>	The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb template, e.g., index.html.erb	lib/types/index.ts:522
`baseUrl`	`string`	The base url prefixed to all calls made by `visit` and `remote`.	lib/types/index.ts:527
`path`	`string`	The path of the current page. It should equal to the `location.pathname` + `location.search` + `location.hash`	lib/types/index.ts:532
`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.	lib/types/index.ts:539
`mapping`	`Record`\<`string`, `ComponentType`\<{}>>	A mapping between your page props and page component. This is setup for you in page_to_page_mapping.	lib/types/index.ts:544
`history?`	`History`	An optional history object https://github.com/remix-run/history. If none is provided Superglue will create one for you.	lib/types/index.ts:549
`store`	`SuperglueStore`	The exported store from store.js. If you used the generators it would contain slices for superglue, pages, and the flash.	lib/types/index.ts:554

Type Aliases¶

PageKey¶

PageKey: string

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

*

Example¶

/posts?foobar=123

Defined in¶

lib/types/index.ts:22

RestoreStrategy¶

RestoreStrategy: "fromCacheOnly" | "revisitOnly" | "fromCacheAndRevisitInBackground"

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.

Defined in¶

lib/types/index.ts:38

NavigationAction¶

NavigationAction: "push" | "replace" | "none"

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

Defined in¶

lib/types/index.ts:47

ComponentIdentifier¶

ComponentIdentifier: string

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

Defined in¶

lib/types/index.ts:53

Keypath¶

Keypath: string

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

Defined in¶

lib/types/index.ts:77

JSONPrimitive¶

JSONPrimitive: string | number | boolean | null | undefined

A JSON Primitive value

Defined in¶

lib/types/index.ts:84

JSONObject¶

JSONObject: {}

A JSON Object

Index Signature¶

[key: string]: JSONValue

Defined in¶

lib/types/index.ts:89

JSONMappable¶

JSONMappable: JSONValue[] | JSONObject

A JSON Object or an array of values

Defined in¶

lib/types/index.ts:96

JSONKeyable¶

JSONKeyable: JSONObject[] | JSONObject

A array of JSON key value objects or a JSON Object

Defined in¶

lib/types/index.ts:101

JSONValue¶

JSONValue: JSONPrimitive | JSONMappable

A primitive or a mappable object

Defined in¶

lib/types/index.ts:106

VisitResponse\<T>¶

VisitResponse\<T>: {data: T;componentIdentifier: ComponentIdentifier;assets: string[];csrfToken: string;fragments: Fragment[];defers: Defer[];slices: JSONObject;renderedAt: number;restoreStrategy: RestoreStrategy; }

The VisitResponse is a protocol, a shape that is responsible for full page visits in Superglue. Its meant to be implemented by the server and if you are using superglue_rails, the generators would have generated a props_template layout and view that would shape the visit responses for you.

Type Parameters¶

Type Parameter	Default type
`T`	`JSONMappable`

Type declaration¶

Name	Type	Defined in
`data`	`T`	lib/types/index.ts:151
`componentIdentifier`	`ComponentIdentifier`	lib/types/index.ts:152
`assets`	`string`[]	lib/types/index.ts:153
`csrfToken`?	`string`	lib/types/index.ts:154
`fragments`	`Fragment`[]	lib/types/index.ts:155
`defers`	`Defer`[]	lib/types/index.ts:156
`slices`	`JSONObject`	lib/types/index.ts:157
`renderedAt`	`number`	lib/types/index.ts:159
`restoreStrategy`	`RestoreStrategy`	lib/types/index.ts:160

Defined in¶

lib/types/index.ts:150

Page\<T>¶

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

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

Type declaration¶

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

Type Parameters¶

Type Parameter	Default type
`T`	`JSONMappable`

Defined in¶

lib/types/index.ts:166

PageResponse¶

PageResponse: GraftResponse | VisitResponse

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

Defined in¶

lib/types/index.ts:191

AllPages\<T>¶

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

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`

Defined in¶

lib/types/index.ts:209

VisitCreator()¶

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

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

Parameters¶

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

Returns¶

VisitMetaThunk

Defined in¶

lib/types/index.ts:274

RemoteCreator()¶

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

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

Parameters¶

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

Returns¶

MetaThunk

Defined in¶

lib/types/index.ts:283

Dispatch¶

Dispatch: ThunkDispatch\<RootState, undefined, Action>

Defined in¶

lib/types/index.ts:288

SuperglueStore¶

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

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

Defined in¶

lib/types/index.ts:295

UJSHandlers()¶

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

Parameters¶

Parameter	Type
`{ ujsAttributePrefix, visit, remote, store, }`	`object`
`{ 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

Defined in¶

lib/types/index.ts:313

SaveAndProcessPageThunk¶

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

Defined in¶

lib/types/index.ts:341

MetaThunk¶

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

Defined in¶

lib/types/index.ts:348

VisitMetaThunk¶

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

Defined in¶

lib/types/index.ts:349

DefermentThunk¶

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

Defined in¶

lib/types/index.ts:356

NavigateTo()¶

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

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.

Parameters¶

Parameter	Type	Description
`path`	`Keypath`
`options`	`object`	-
`options.action`	`NavigationAction`	when `none`, `navigateTo` will immediately return `false`

Returns¶

boolean

true if the navigation was a success, false if the page was not found in the store.

Defined in¶

lib/types/index.ts:394