Render Runtime

The Render Runtime app is responsible for handling runtime execution of React apps in the VTEX IO Platform. Additionally, it exports:

Helpful variables, such as canUseDOM.
Hooks, such as useRuntime.
React components, such as Block (alias ExtensionPoint), Helmet, Link, NoSSR and withRuntimeContext.

ℹ️ Tip: Run vtex setup --typings to add vtex.render-runtime types in your app. This way, IDEs will be able to provide autocomplete for variables and methods.

Check the following sections for more information on the objects exported by the Render Runtime app.

Variables

canUseDOM

A boolean value that indicates whether the code is running in a browser environment (true) or in a Node/SSR environment (false).

ℹ️ Notice that the canUseDOM variable is especially useful in cases the components use DOM related data (e.g: document or window).

Take the following usage example:

import React from 'react'
import { canUseDOM } from 'vtex.render-runtime'

function MyComponent() {
  const data = canUseDOM
    ? window.localStorage.getItem('foo')
    : ''

  return <div>Hello</div>
}

export default MyComponent

Hooks

useRuntime

The useRuntime React hook is useful when creating components since it provides runtime contextual variables and methods.

For an example on its usage, check the following snippet:

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const runtime = useRuntime()

  return <div>Hello</div>
}

Inside the runtime object you can have access to the following variables:

Name	Type	Description
`account`	string	The VTEX account name, (e.g., `storecomponents`).
`binding`	object	An object containing the `id` and `canonicalBaseAddress` of the store binding.
`culture`	object	An object containing culture, currency and locale information.
`deviceInfo`	object	An object specifying the user device type (`phone`, `desktop`, `tablet`, or `unknown`). This data varies when the user resizes the window.
`getSettings`	function	A function that, when called, returns the public `settings` of an app.
`hints`	object	An object which specifies the user device type (`phone`, `desktop`, `tablet`, or `unknown`) based on the information provided by the CDN. Different from `deviceInfo` this data is static.
`history`	object	A `history` object reexported from the `history` package. For further information, check this link.
`navigate`	function	A function used in the client-side to define the navigation behaviour.
`page`	string	The current `page` id (e.g., `store.home`).
`pages`	object	Object containing all `pages`. The keys are the pages ids (e.g., `store.home`).
`route`	object	Object containing data related to the current route, such as `id`, `path`, `blockId` and others.
`production`	boolean	Points if the app is in a production workspace (`true`) or not (`false`).
`query`	object	The URL query string values in a key-value format (e.g., `{ "foo": "bar" }`).
`renderMajor`	number	The major version of the Render Runtime app.
`rootPath`	string	The store root path (e.g., `/ar`). If not specified, its value is `undefined`.
`setQuery`	function	A function that can be called to set query string params.
`workspace`	string	The current workspace name (e.g., `master`).

Usage examples

Check the following section for usage examples on how to use the internal runtime variables.

`account`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { account } = useRuntime()

  return <div>Welcome to {account}</div>
}

export default MyComponent

`binding`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { binding } = useRuntime()

  return <div>Canonical address is "{binding.canonicalBaseAddress}"</div>
}

export default MyComponent

Type:

interface BindingInfo {
  id: string
  canonicalBaseAddress: string
}

Example value:

{
  "id": "aacb06b3-a8fa-4bab-b5bd-2d654d20dcd8",
  "canonicalBaseAddress": "storetheme.vtex.com/"
}

`culture`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { culture } = useRuntime()

  return <div>Current active locale is: "{culture.locale}"</div>
}

export default MyComponent

Type:

interface Culture {
  availableLocales: string[]
  country: string
  currency: string
  language: string
  locale: string
  customCurrencyDecimalDigits: number | null
  customCurrencySymbol: string | null
}

Example value:

{
  "availableLocales": [],
  "country": "USA",
  "currency": "USD",
  "language": "en",
  "locale": "en-US",
  "customCurrencyDecimalDigits": null,
  "customCurrencySymbol": "$"
}

`deviceInfo`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { deviceInfo } = useRuntime()

  return <div>This page is being rendered on a "{deviceInfo.type}"</div>
}

export default MyComponent

Type:

interface DeviceInfo {
  isMobile: boolean
  type: 'phone' | 'tablet' | 'desktop' | 'unknown'
}

Example value:

{
  "isMobile": false,
  "type": "desktop"
}

`getSettings`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { getSettings } = useRuntime()
  const settings = getSettings('vtex.store')

  return <div>This is the store's name: "{settings.storeName}"</div>
}

export default MyComponent

`hints`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { hints } = useRuntime()

  if (!hints.desktop) {
    return <div>This is not a desktop</div>
  }

  return <div>This is a desktop</div>
}

export default MyComponent

Type:

interface Hints {
  desktop: boolean
  mobile: boolean
  tablet: boolean
  phone: boolean
  unknown: boolean
}

Example value:

{
  "desktop": true,
  "mobile": false,
  "tablet": false,
  "phone": false,
  "unknown": false,
}

`history`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { history } = useRuntime()

  const handleClick = () => {
    history.goBack()
  }

  return <button onClick={handleClick}>Back</button>
}

export default MyComponent

`navigate`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { navigate } = useRuntime()

  const handleClick = () => {
    navigate({
      to: '/other-page'
    })
  }

  return <button onClick={handleClick}>Go</button>
}

export default MyComponent

Function param:

interface NavigateOptions {
  fallbackToWindowLocation?: boolean
  hash?: string
  page?: string
  params?: any
  query?: any
  replace?: boolean
  rootPath?: string
  scrollOptions?: false | {
    baseElementId: string,
    behavior: 'auto' | 'smooth'
    left: number
    top: number
  }
  skipSetPath?: boolean
  to?: string
}

`page`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { page } = useRuntime()

  return <div>This is the current page id: "{page}"</div>
}

export default MyComponent

`pages`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { pages, page } = useRuntime()

  return <div>This is the current page declarer: "{pages[page].declarer}"</div>
}

export default MyComponent

Example value:

{
  "allowConditions": true,
  "context": null,
  "declarer": "vtex.store@2.x",
  "path": "/",
  "routeId": "store.home",
  "blockId": "vtex.store-theme@4.x:store.home",
  "map": []
}

`route`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { route } = useRuntime()

  return <div>This is the current route full path: "{route.path}"</div>
}

export default MyComponent

Example value:

{
  "domain": "store",
  "id": "store.home",
  "pageContext": {
    "id": "store.home",
    "type": "route"
  },
  "params": {},
  "path": "/",
  "pathId": "/",
  "queryString": {},
  "breakpointStyles": [
    {
      "path": "/_v/public/vtex.styles-graphql/v1/style/vtex.store-theme@4.3.0$style.common.min.css",
      "mediaQuery": "",
      "type": "common"
    },
    {
      "path": "/_v/public/vtex.styles-graphql/v1/style/vtex.store-theme@4.3.0$style.small.min.css",
      "mediaQuery": "screen and (min-width: 20em)",
      "type": "small"
    },
    {
      "path": "/_v/public/vtex.styles-graphql/v1/style/vtex.store-theme@4.3.0$style.notsmall.min.css",
      "mediaQuery": "screen and (min-width: 40em)",
      "type": "notsmall"
    },
    {
      "path": "/_v/public/vtex.styles-graphql/v1/style/vtex.store-theme@4.3.0$style.large.min.css",
      "mediaQuery": "screen and (min-width: 64em)",
      "type": "large"
    },
    {
      "path": "/_v/public/vtex.styles-graphql/v1/style/vtex.store-theme@4.3.0$style.xlarge.min.css",
      "mediaQuery": "screen and (min-width: 80em)",
      "type": "xlarge"
    }
  ],
  "fonts": "/_v/public/vtex.styles-graphql/v1/fonts/7ead87572b7446c1ca01c45f5065665fc8cfd256",
  "overrides": [
    "/_v/public/vtex.styles-graphql/v1/overrides/vtex.product-list@0.28.2$overrides.css",
    "/_v/public/vtex.styles-graphql/v1/overrides/vtex.minicart@2.56.0$overrides.css",
    "/_v/public/vtex.styles-graphql/v1/overrides/vtex.store-theme@4.3.0$overrides.css"
  ],
  "rootName": "store.home",
  "ssr": true,
  "styleMeta": {
    "fontsHash": "7ead87572b7446c1ca01c45f5065665fc8cfd256",
    "overridesIds": [
      {
        "id": "vtex.product-list@0.28.2$overrides.css"
      },
      {
        "id": "vtex.minicart@2.56.0$overrides.css"
      },
      {
        "id": "vtex.store-theme@4.3.0$overrides.css"
      }
    ],
    "themeId": "vtex.store-theme@4.3.0$style.min.css"
  },
  "blockId": "vtex.store-theme@4.x:store.home",
  "canonicalPath": "/",
  "metaTags": null,
  "routeId": "store.home",
  "title": null,
  "varyContentById": false
}

`production`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { production } = useRuntime()

  if (!production) {
    return <div>This is not a production workspace</div>
  }

  return <div>This is a production workspace</div>
}

export default MyComponent

`query`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { query } = useRuntime()

  return <div>The current query strings are {JSON.stringify(query)}</div>
}

export default MyComponent

`renderMajor`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { renderMajor } = useRuntime()

  return <div>This page is rendered using vtex.render-runtime@{renderMajor}.x</div>
}

export default MyComponent

`rootPath`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { rootPath } = useRuntime()

  if (!rootPath) {
    return <div>The store doesn't have a rootPath set</div>
  }

  return <div>The store rootPath is "{rootPath}"</div>
}

export default MyComponent

`setQuery`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { setQuery } = useRuntime()

  const handleClick = () => {
    setQuery({ foo: 'bar' })
  }

  return <button>Set</button>
}

export default MyComponent

`workspace`

import React from 'react'
import { useRuntime } from 'vtex.render-runtime'

function MyComponent() {
  const { workspace } = useRuntime()

  return <div>This is the {workspace} workspace</div>
}

export default MyComponent

Components

Block (alias ExtensionPoint)

Block is a React component used to create Store Framework blocks.

For implementation details, take the following example.

ℹ️ Notice that the Block component will always expect a specific block id.

import React from 'react'
import { Block } from 'vtex.render-runtime'
// or
// import { ExtensionPoint } from 'vtex.render-runtime'

function MyComponent() {
  return (
    <div>
      Foobar
      <Block id="my-other-block" />
      {/* or <ExtensionPoint id="my-other-block" /> */}
    </div>
  )
}

export default MyComponent

Helmet

Helmet is a component used to add HTML tags inside the <head> tag of a page. Take the following example:

ℹ️ Helmet is a reexport of the Helmet component from the react-helmet library.

import React from 'react'
import { Helmet } from 'vtex.render-runtime'

function MyComponent() {
  return (
    <>
      <Helmet>
        <meta property="og:type" content="article" />
      </Helmet>
    </>
  )
}

export default MyComponent

Link

The Link React component is responsible for rendering an a HTML element that, when clicked, navigates the user to the provided route.

ℹ️ Notice that the Link component has a similar API to the navigate method from the useRuntime hook.

Name	Type	Description	Default
`page`	`string`	The name of the page that the user will be redirected to. Maps to a `blocks.json` block (e.g., `'store.product'`)
`to`	`string`	The URL of the page that the user will be redirected to (e.g., `/shirt/p?skuId=1`). Notice that `to` is an alternative to `page` and it contains the whole URL instead of the page name.
`params`	`object`	The `param` values of the page path in a key-value format (e.g, `{slug: 'shirt'}`). Params that starts with `__` are not considered on path transformations, and can be generaly be used as an alternative to query params	`{}`
`query`	`string`	The representation of the query params that are appended to the page path (e.g., `skuId=231`.)	`''`
`onClick`	`function`	A callback that is fired when the user clicks on a component (e.g., `() => alert('Salut')`)
`replace`	`boolean`	The boolean value used to indicate if it should call (`true`) the replace function to navigate or not (`false`)

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

Take the following usage examples:

import React from 'react'
import { Link } from 'vtex.render-runtime'

function MyComponent() {
  return <Link to="/otherpage" classname="c-on-base">Hello</Link>
}

export default MyComponent

import React from 'react'
import { Link } from 'vtex.render-runtime'

function MyComponent() {
  const params = {
    slug: PRODUCT_SLUG, // Considered on path transformations (/{slug}/p)
    __listName: 'List of products' // Ignored on path transformations
    __yourProductPageParam: YOUR_PARAM // Ignored on path transformations
  }

  return <Link to="/productpage" params={params}>Hello</Link>
}

export default MyComponent

NoSSR

⚠️ We always recommend using the canUseDOM variable when possible.

NoSSR is a React component that avoids rendering its children during Server-Side Rendering (SSR).

ℹ️ Notice that the NoSSR component is especially useful in cases the components use DOM related data (e.g: document or window).

Take the following usage example:

import React from 'react'
import { NoSSR } from 'vtex.render-runtime'

import DomRelatedComponent from './DomRelatedComponent'

function MyComponent() {
  return (
    <NoSSR onSSR={<div>Loading...</div>}>
      <DomRelatedComponent/>
    </NoSSR>
  )
}

withRuntimeContext (High Order Component)

withRuntimeContext is a React High Order Component (HOC) that allows class components to access the runtime context.

ℹ️ When using function components, you can use useRuntimeContext hook instead.

Take the following usage example:

import React from 'react'
import { withRuntimeContext, RenderContext } from 'vtex.render-runtime'

class MyComponent extends React.Component<{ runtime: RenderContext }>{
  render({ runtime }) {
    return <div>This is the current page id: "{runtime.page}"</div>
  }
}

const MyComponentWithRuntime = withRuntimeContext(MyComponent)

Notice that, when in SSR mode, you can optionally provide the onSSR prop together with a component to render instead.

Name		Name	Last commit message	Last commit date
Latest commit History 2,809 Commits
.github		.github
docs		docs
react		react
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.vtexignore		.vtexignore
CHANGELOG.md		CHANGELOG.md
lint.sh		lint.sh
manifest.json		manifest.json

vtex-apps/render-runtime

Folders and files

Latest commit

History

Repository files navigation

Render Runtime

Variables

canUseDOM

Hooks

useRuntime

Usage examples

account

binding

culture

deviceInfo

getSettings

hints

history

navigate

page

pages

route

production

query

renderMajor

rootPath

setQuery

workspace

Components

Block (alias ExtensionPoint)

Helmet

Link

NoSSR

withRuntimeContext (High Order Component)

About

Topics

Resources

Stars

Watchers

Forks

Languages

`account`

`binding`

`culture`

`deviceInfo`

`getSettings`

`hints`

`history`

`navigate`

`page`

`pages`

`route`

`production`

`query`

`renderMajor`

`rootPath`

`setQuery`

`workspace`