Render Runtime

This app handles runtime execution of React apps in the VTEX IO Platform.

Exported Components

Link

Navigation related component that, when clicked, redirects to another route. Details here.

NoSSR

This wrapper component removes its children from the subject of the Server Side Rendering(SSR). It may be useful for Components that use DOM related data (e.g: document). You can provide an optional prop onSSR with a component to render instead when in SSR mode.

<NoSSR onSSR={<div>Loading...</div>}>
  <DomRelatedComponent/>
</NoSSR>

In addition, you can use it as a React hook, with useSSR.

const isSSR = useSSR()

if (isSSR) {
  return <div>Loading...</div>
}

return <DomRelatedComponent/>

Navigation

The Render framework provides a built-in navigation solution that provides great experience and modularity for our sites. Building a store, alongside blocks.json and interfaces.json, you can provide a routes.json file that describes routes that a user is able to access. A route looks like this:

"store.product": {
	"path": "/:slug/p"
},

Extracted from vtex-store

In this example, store.product represents a block that renders a specific template, and /:slug/p represents the URL path that match with that product block.

We provide two solutions for navigation inside our Render apps: the navigate method exported from render-runtime, and the Link component. You can also only set query parameters using the setQuery method.

navigate

This method is the most powerful solution for navigation and can be used inside a React Component's lifecycle. It may be injected with the HOC withRuntimeContext or, preferably, with the useRuntime hook.

import { useRuntime, withRuntimeContext } from 'vtex.render-runtime'
...
const MyComponent = () => {
  const { navigate }  = useRuntime()
}

// OR

const MyOtherComponent = ({ navigate }) => {
}

export default withRuntimeContext(MyOtherComponent)

You can pass a handful of configuration props to navigate:

Navigate Options

Name	Type	Default	Description
fallbackToWindowLocation	boolean	false	If true, sets the href of window.location with the future path
fetchPage	boolean	true	If false, won't fetch navigation assets in pages-graphql
page	string	--	Name of the page that will be redirected to. Maps to a blocks.json block. Example: 'store.product'
to	string	--	Alternatively to page, you can pass the whole URL directly instead of the page name (Useful for the search-result). Example: /shirt/p?skuId=1
params	object	{}	Map of parameters names in the path for the page and the values that should replace them. Example: {slug: 'shirt'}
query	string	''	String representation of the query params that will be appended to the path. Example: skuId=231.
scrollOptions	RenderScrollOptions	--	After the navigation, if the page should be scrolled to a specific position, or should stay still (use false)
replace	boolean	undefined	If it should call the replace function to navigate or not
preventRemount	boolean	false	If true, only the URL will change, but not the components ❗ Use with caution!

Example

navigate({
  page: 'store.search',
  params: { department: 'accessories' },
  query: 'order=OrderByPrice',
  scrollOptions: { baseElementId: 'search-result-anchor', top: -HEADER_SCROLL_OFFSET },
})

Link

Link is a custom React component that renders an a HTML element that, when clicked, navigates the user to the provided route. It has a similar API with the navigate method.

Props

Name	Type	Default	Description
page	string	--	Name of the page that will be redirect to. Maps to a blocks.json block. Example: 'store.product'
to	string	--	Alternatively to page, you can pass the whole URL directly instead of the page name (Useful for the search-result). Example: /shirt/p?skuId=1
params	object	{}	Map of param names in the path for the page and the values that should replace them. Example: {slug: 'shirt'}
query	string	''	String representation of the query params that will be appended to the path. Example: skuId=231.
onClick	function	--	Callback that will be fired when the user click on the Component. Example: () => alert('Salut')
replace	boolean	undefined	If it should call the replace function to navigate or not

Other props you pass will be forwarded to the a component and can be used for customisation.

Use Example

import { Link } from 'render-runtime'
  <Link
    page={linkprops.page}
    query={linkprops.querystring}
    params={linkprops.params}
    classname="c-on-base f5 ml-auto db no-underline pv4 ph5 hover-bg-muted-4"
  >
   {option.label}
  </Link>

Extracted from vtex.search-result

Other methods

goBack

This method has no parameters and can be called to return the user to the last navigated page.

const { goBack } = useRuntime()
...
goBack()

setQuery

This auxiliary method changes the current page's query string without fetching navigation data to pages-graphql. It operates in the same way that React's setStatedoes, merging the passed queries to the current ones. You can also specify to replace all of the queries.

setQuery(query, options)

Parameters

Name	Type	Default	Description
query	object	--	Object describing the query E.g: { order: 'price' }
options	object	--	Configuration. Described below

Options

Name	Type	Default	Description
merge	boolean	true	Set if the passed queries will be merged into the current ones.
replace	boolean	false	If true, it uses history's replace method instead of push.
scrollOptions	RenderScrollOptions	false	After the navigation, if the page should be scrolled to a specific position, or should stay still (use false)