Locator Upgrade - Storyblok (Next.js) Steps
Search engines and AI assistants often cannot see your store finder. When they visit the page, your stores are not on it yet: they only appear later, on the visitor's screen. So your stores can be missing from search results and from the answers AI assistants give.
After these steps, every store finder page arrives with its stores already on it, with names, addresses and opening hours. Search engines and AI assistants can find each of your stores and show it. Your visitors see the store finder as usual.
Storyblok keeps your pages' content, and your site's frontend builds the pages from it. So these steps are in your frontend's code, not in Storyblok. It works for a store finder already on your site and for a new one. It takes eight steps, written for the developer who maintains the frontend.
What you need
A frontend on Next.js 15 or newer, with the App Router, that renders its pages on the server (which frontend builds your site)
Access to the frontend's code, and to the environment variables of the server it runs on
The Uberall Store Finder package for Next.js, which you install in step 2: uberall-store-finder-nextjs-0.2.1.tgz
Your render token, from Uberall
Your locator key, from Uberall. If the store finder is already on your site, it is the data-key of its snippet:
<div id="store-finder-widget" data-key="YOUR_LOCATOR_KEY"></div>
Your store finder's address: the page it is on, such as https://www.example.com/store-locator. Each store gets its own address under it
In Storyblok, the store finder's story, with a blok where the store finder goes: the one your site already has for it, or a new one with no fields, such as store_finder
Which frontend builds your site
Open your site in the browser, right click, and choose View page source:
-
self.__next_fin the source: Next.js with the App Router. -
__NEXT_DATA__: Next.js with the Pages Router. -
/_nuxt/: Nuxt.
In the frontend's code, Next.js has next in package.json, the App Router an app/ folder, and a site exported as static files output: 'export' in next.config.
Then:
- a) Next.js with the App Router, its pages rendered on a server (your own Node.js server, or a host such as Vercel that runs Next.js that way): follow the steps below.
- b) Next.js exported as static files: follow the static Next.js guide instead. Point Storyblok's Visual Editor at a preview that does not run behind that guide's function: the function sends the whole address to Uberall, with the parameters the editor adds, one of them a token.
- c) Anything else, such as Nuxt, Astro, SvelteKit, Remix, Gatsby or the Next.js Pages Router: these steps do not cover it yet. The store finder keeps working as it does today, on the visitor's screen. Tell Uberall which frontend your site uses.
If the store finder is already on your site
After these steps, your store finder pages use only the settings saved at Uberall. What is set on the page itself no longer applies there:
- attributes on the store finder's
div, other thandata-key,data-language,data-countriesanddata-widgetoriginurl - settings your site's scripts pass to
UberallStorefinderMountorUberallStorefinderRestart, other thanwithoutMap
On a Storyblok site, the snippet is usually in the component of the store finder's blok. Look there for the div's data- attributes, and for calls to these two functions, also in effects (useEffect) and in the scripts it loads.
If you find any of these settings, send them to Uberall before you start, to be saved with your store finder. Until then, leave the page as it is: the store finder keeps working as it does today.
Your pages' title and description
Uberall gives every store finder page its own canonical link. The title, the description and the preview image for social media come from Uberall only when they are set up there:
- The store finder's main page, and its directory pages (the lists of stores by country, region or city): only what is set up at Uberall. With nothing set up, these pages keep the title and description your site gives the store finder's story.
- A store's page: always a title and, when the store has one, a description: the store's name and short description, unless others are set up. The image is the store's photo.
On these pages, your site's own title, description, canonical link and Open Graph tags give way to Uberall's (step 4). So check with Uberall first that a title and a description are set up for your store finder, or send yours to be saved with it.
Step 1: Add your render token to the server's environment
Set the environment variable UBERALL_RENDER_TOKEN to your token where your frontend runs: in your host's settings for environment variables, or in .env.local while you develop.
UBERALL_RENDER_TOKEN=YOUR_RENDER_TOKEN
Do not start its name with NEXT_PUBLIC_: Next.js sends those to the browser. And do not keep it in Storyblok: your stories can be read with your space's public access token. Read this way, the token stays on your server. Visitors never see it.
Step 2: Install the Uberall Store Finder package
In your frontend's folder, install the package from Uberall:
npm install https://locator.uberall.com/locator-assets/nextjs/uberall-store-finder-nextjs-0.2.1.tgz
It adds @uberall/store-finder-nextjs to your package.json, at that address. To update it later, install the address of the new version the same way.
The package renders the store finder snippet with the store finder's content in it, loads the store finder's script after it, and gives your page's head the tags Uberall sends.
Step 3: Add the store finder's settings
Add lib/store-finder.ts, and replace YOUR_LOCATOR_KEY and the address with your own:
import type { StoreFinderPage, StoreFinderSettings } from '@uberall/store-finder-nextjs';
export const storeFinderSettings: StoreFinderSettings = {
locatorKey: 'YOUR_LOCATOR_KEY',
widgetOriginUrl: 'https://www.example.com/store-locator',
};
/** Whether the page is open in Storyblok's Visual Editor, which adds `_storyblok` parameters. */
export async function isInVisualEditor({ searchParams }: StoreFinderPage) {
return Object.keys(await searchParams).some((name) => name.startsWith('_storyblok'));
}
widgetOriginUrl is the store finder's full address, as visitors see it, without a slash at the end. If your addresses have no locale for your main language, it has none either.
isInVisualEditor tells the store finder's pages apart in Storyblok's Visual Editor, which opens them with parameters of its own (step 4).
If your snippet has data-language, data-countries or data-widgetoriginurl
Add the same values to the settings:
| Your snippet has | Add to the settings |
|---|---|
data-language= |
language: 'de' |
data-countries= |
countries: 'US, |
data-widgetoriginurl= |
widgetOriginUrl: 'https:/ |
Without countries, the page shows the stores of every country set up for the store finder at Uberall.
If your page loads storeFinderWidget-v2-withoutMap.js, or starts the store finder with withoutMap: true, add withoutMap: true to the settings.
Step 4: Give the store finder its own route
Each store's page lives at an address under the store finder, such as /store-locator/l/berlin/.... Your site's route for Storyblok's pages, a catch-all such as app/[locale]/[...slug]/page.tsx, would look for a story at each of these addresses and find none. So the store finder gets a route of its own, which answers all of them with the store finder's story.
First, add components/store-finder-slot.tsx. It passes the store finder, rendered on the server, to the blok of step 5:
'use client';
import { createContext, useContext, type ReactNode } from 'react';
// The store finder, as its page rendered it on the server, for the blok that shows it.
const StoreFinderContext = createContext<ReactNode>(null);
interface StoreFinderProviderProps {
storeFinder: ReactNode;
children: ReactNode;
}
export function StoreFinderProvider({ storeFinder, children }: StoreFinderProviderProps) {
return <StoreFinderContext value={storeFinder}>{children}</StoreFinderContext>;
}
export function StoreFinderSlot() {
return useContext(StoreFinderContext);
}
Then add the route, in the folder of your catch-all route, named after the store finder's address. For a store finder at /store-locator, next to app/[locale]/[...slug]/page.tsx, it is app/[locale]/store-locator/[[...path]]/page.tsx:
import { getStoreFinderMetadata, StoreFinder } from '@uberall/store-finder-nextjs';
import type { Metadata } from 'next';
import CmsPage, { generateMetadata as generateCmsMetadata } from '../../[...slug]/page';
import { StoreFinderProvider } from '@/components/store-finder-slot';
import { isInVisualEditor, storeFinderSettings } from '@/lib/store-finder';
interface StoreLocatorPageProps {
params: Promise<{ locale: string; path?: string[] }>;
searchParams: Promise<Record<string, string | string[] | undefined>>;
}
// Every address under the store finder shows the store finder's story.
function getStoryProps({ params, searchParams }: StoreLocatorPageProps) {
return { params: params.then(({ locale }) => ({ locale, slug: ['store-locator'] })), searchParams };
}
export async function generateMetadata(props: StoreLocatorPageProps): Promise<Metadata> {
const metadata = await generateCmsMetadata(getStoryProps(props));
if (await isInVisualEditor(props)) {
return metadata;
}
return { ...metadata, ...(await getStoreFinderMetadata(storeFinderSettings, props)) };
}
export default async function StoreLocatorPage(props: StoreLocatorPageProps) {
// The editor renders the page again after every change, and a new render would replace the
// running store finder. There, it starts on the screen alone, as before.
const page = (await isInVisualEditor(props)) ? undefined : props;
return (
<StoreFinderProvider storeFinder={<StoreFinder settings={storeFinderSettings} page={page} />}>
<CmsPage {...getStoryProps(props)} />
</StoreFinderProvider>
);
}
The route shows the store finder's story with your catch-all route's own page, the way that route shows every other story, with the same layout, drafts in the preview and errors.
In Storyblok's Visual Editor, the store finder's pages go out without Uberall's content, and the store finder appears on the screen, as it does today. Your editors need nothing more. The editor renders the page again after each change, and new content from Uberall would replace the store finder while it runs, which then stops responding. The editor's parameters, one of them a token that lets the preview show drafts, also stay away from Uberall.
Fit the route to your catch-all route:
The import is your catch-all route's page, two folders up. Without a [locale] folder, the route is app/store-locator/[[...path]]/page.tsx, the import stays the same, and locale goes from StoreLocatorPageProps and getStoryProps.
getStoryProps gives your catch-all route the props it expects, with the slug of the store finder's story in Storyblok: store-locator here. If your route names its folder other than [...slug], use that name.
generateMetadata: if your catch-all route has none, import only CmsPage from it, and the route's generateMetadata becomes:
export async function generateMetadata(props: StoreLocatorPageProps): Promise<Metadata> {
return (await isInVisualEditor(props)) ? {} : getStoreFinderMetadata(storeFinderSettings, props);
}
The package's metadata takes your site's own title, description, canonical link and Open Graph tags off the page, but only the kinds Uberall sends for it. If your layout writes its own structured data (application/ld+json), leave it off these pages: Uberall sends the store's.
If your next.config sets cacheComponents: true, add this line to this page, and to the head page in step 7:
export const instant = false;
The store finder's pages wait for Uberall's content before they go out, so they have no part that Next.js could build ahead of the visit. The line tells Next.js so, for these two pages only.
Every address under the store finder's page belongs to the store finder. Do not put other pages under it, in Storyblok either.
Links to the store finder
Links into the store finder can be next/link's <Link> or plain <a>. When the visitor comes to the store finder through a navigation in the browser, such as a <Link> or the Back button, the page loads again in full: React does not run the scripts of a page it builds in the browser, and the store finder starts only on a page that loads in full.
Give a <Link> to the store finder prefetch={false}, such as one in your header or footer:
<Link href="/store-locator" prefetch={false}>
Store locator
</Link>
Otherwise, Next.js loads the store finder's page ahead for every page that shows the link, and each time asks Uberall for its content, which the full load then asks for again.
Step 5: Show the store finder in its blok
In the component of the store finder's blok, show the slot from step 4:
import { storyblokEditable, type SbBlokData } from '@storyblok/react/rsc';
import { StoreFinderSlot } from '@/components/store-finder-slot';
interface StoreFinderBlokProps {
blok: SbBlokData;
}
export default function StoreFinderBlok({ blok }: StoreFinderBlokProps) {
return (
<div {...storyblokEditable(blok)}>
<StoreFinderSlot />
</div>
);
}
- Keep the
storyblokEditableyour blok imports today, from@storyblok/react/rscor@storyblok/react: the Visual Editor finds the blok by it. - Remove the old snippet from the blok, once its settings are at Uberall (the section above): the
div, thestoreFinderWidget-v2.jsscript and the calls that start the store finder. The package puts thedivand the script on the page. If the store finder's addresses have#!in them today, this removes it. - It works the same whether your bloks render on the server or as client components (
'use client', set up with aStoryblokProvider). - Do not render the package's
StoreFinderin the blok itself. There, it does not know the visitor's address, and the page goes out without the store finder's content. - A new blok goes into the
componentsof yourstoryblokInit, under its name in Storyblok, like your other bloks.
The blok shows the store finder on the route from step 4, and nothing on other pages. Put it once in the store finder's story.
Step 6: Keep the addresses whole in your proxy
Next.js runs proxy.ts (middleware.ts before Next.js 16) before every page. Look for it at the root of your frontend, or in src/:
a) There is none, or it does not change addresses: go on to step 7.
b) It rewrites or redirects addresses, for example to add a locale: it must keep the part after the store finder's address, and the query. A rule that sends every address under the store finder to the store finder's page shows its main page for every store.
Instead of:
if (request.nextUrl.pathname.startsWith('/store-locator')) {
return NextResponse.rewrite(new URL('/de-DE/store-locator', request.url));
}
rewrite the address whole:
if (request.nextUrl.pathname.startsWith('/store-locator')) {
const url = request.nextUrl.clone();
url.pathname = `/de-DE${url.pathname}`;
return NextResponse.rewrite(url);
}
Step 7: Put Uberall's head tags into the page's head
The store finder's styles have to be in the page's <head>, where the store finder looks for them. A page cannot write into <head> itself, so the layout that writes <html> gets a place for them: a parallel route named @head.
Search your app/ folder for <html to find that layout:
-
a)
app/[locale]/layout.tsx: the files below go inapp/[locale]/@head/. -
b)
app/layout.tsx, with no[locale]folder: they go inapp/@head/. -
c)
app/layout.tsx, with your pages in a[locale]folder: they go inapp/@head/[locale]/, exceptdefault.tsx, which goes inapp/@head/.
Add the store finder's head, @head/store-locator/[[...path]]/page.tsx, with the settings from step 3:
import { StoreFinderHead, type StoreFinderPage } from '@uberall/store-finder-nextjs';
import { isInVisualEditor, storeFinderSettings } from '@/lib/store-finder';
export default async function StoreLocatorHead(page: StoreFinderPage) {
return (await isInVisualEditor(page)) ? null : <StoreFinderHead settings={storeFinderSettings} page={page} />;
}
Every other page needs an empty head of its own. Add the same file three times, in the same @head folder: as default.tsx, as page.tsx and as [...slug]/page.tsx:
export default function NoHead() {
return null;
}
default.tsx covers a page that loads in full. page.tsx and [...slug] cover your home page and your other pages when the browser goes to them from the store finder. Without them, the store finder's head tags stay on that page. Name the [...slug] folder as your catch-all route names its own: with two names, Next.js does not build the site.
If your catch-all route is optional, [[...slug]], it answers your home page too. Then the head's catch-all is [[...slug]] as well, and page.tsx is left out: Next.js does not build the site with both.
Then, in the layout, add head to its props next to children, and put it at the end of <head>. The layout's other props, such as params, stay as they are:
interface RootLayoutProps {
children: React.ReactNode;
head: React.ReactNode;
}
export default function RootLayout({ children, head }: RootLayoutProps) {
return (
<html lang="en">
<head>
{/* ... what was already here stays as it is */}
{head}
</head>
<body>{children}</body>
</html>
);
}
Step 8: Deploy and check
Deploy the site with the token from step 1 in its environment.
Open your store finder in the browser, right click, and choose View page source. Search the source for id="store-finder-widget". Right after it, the store finder's content should follow, starting with <section class="ubsf_outer-wrap". If it works, the div is not empty.
Search the same source for <title and rel="canonical". Each should appear exactly once.
Then open one of your stores and copy its address into a new tab. The store's page should open, with the store's name as the page title.
Last, open the store finder's story in Storyblok's Visual Editor. The store finder shows in the preview, and its blok can be selected as before. Change the story, such as a text near the store finder: the store finder keeps responding.
More than one store finder on the site
Each store finder has its own render token. Give the second one its own environment variable, such as UBERALL_RENDER_TOKEN_2, and pass it in that store finder's settings:
export const otherStoreFinderSettings: StoreFinderSettings = {
locatorKey: 'YOUR_OTHER_LOCATOR_KEY',
widgetOriginUrl: 'https://www.example.com/other-store-locator',
renderToken: process.env.UBERALL_RENDER_TOKEN_2,
};
Then follow steps 4 and 7 for the second store finder's address and story, with these settings. The blok from step 5 serves both: each route gives it its own store finder.
If it does not work
| What you see | What to do |
|---|---|
The source has no server render (no token)
|
Add the token, as in step 1, and deploy again. |
The source has no server render (declined: unauthorised)
|
The token is not the one Uberall gave you for this locator key. |
The source has no server render (request failed)
|
Your server cannot reach Uberall. Allow outgoing HTTPS to uberall.com. |
The source has no server render (widgetOriginUrl is not an address)
|
Set widgetOriginUrl to the full address, starting with https:/ (step 3). |
The source has another no server render (...)
|
Contact Uberall, with that text. |
The story shows, but the source has no id=
|
The page is not the route from step 4, or that route does not wrap the story in StoreFinderProvider. |
The store-finder-widget div is empty, with no no server render
|
The blok still has its old snippet, or renders the package's StoreFinder itself: show the slot instead (step 5). |
| A store's page shows the store finder's main page | Your proxy or middleware drops the store's address (step 6). |
| A store's page says "Not Found" | The route from step 4 is not a catch-all: its folder must be named [[...path]]. |
| Next.js stops the build with "Ambiguous app routes" | The @head catch-all has another name than your catch-all route (step 7). |
| Next.js stops the build with "the same specificity as an optional catch-all route" | Your catch-all is [[...slug]]: leave out the head's page.tsx (step 7). |
The store finder looks unstyled until it starts, or the console shows insertBefore
|
Its head tags are not in <head>: check step 7. |
| Another page has the store finder's canonical link after a click from the store finder | One of the empty heads is missing (step 7). |
<title or rel= appears twice |
Your layout writes its own outside its metadata: leave it off the store finder's pages. |
When the store finder content does not arrive
The store finder keeps working in every case. If the content does not arrive, because your server cannot connect to Uberall, the connection takes too long or it returns an error, the page loads without it, and the store finder appears on the visitor's screen as usual.
After such a failure, your server serves the store finder's pages without the content for 30 seconds, and then asks Uberall again.
When changes show
A change at Uberall, to your stores or to your store finder's settings, takes a few minutes to show on these pages. A change to the store finder's story in Storyblok shows when your site fetches the story again, as on your other pages.
The store finder's pages are rendered for every visit, so Next.js does not keep them. If your CDN caches your pages, add the time it keeps them: each store finder page in that cache keeps the content it had when it was cached. And a page your cache stored while the content did not arrive stays without its stores, for search engines, until your cache stores it again.