Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

    Sign In
    • Home
    • User Guides
    • Locator + Pages

    Locator Upgrade - Next.js Static Export Steps

    Contact Us

    If you still have questions or prefer to get help directly from an agent, please submit a request.
    We’ll get back to you as soon as possible.

    Please fill out the contact form below and we will reply as soon as possible.

    English (US)
    FR French
    IT Italian
    JP Japanese
    DE German
    US English (US)
    ES Spanish
    • Getting Started
      New here Configuration and Connection Guides
    • Academy and Learning Resources
      Learning Resources - Best Practices Academy
    • User Guides
      AI What's New Platform Status and General FAQs Homepage The Dashboard Location Hub Review Management Messages Social Locator + Pages Analytics Directories Mobile App 'Near Me' 360
    • Connecting Tools
      Connection Troubleshooting API
    • Org Settings
      Users Billing API Keys Webhooks
    + More

    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.

    It works for a store finder already on your site and for a new one. It takes five steps: two in your site's code, and three on the host that serves it. They are written for the developer who maintains the site and its hosting.

    Is this the right guide?

    There are two guides for Next.js. This one is for sites exported as static files. A site whose pages are rendered on a server has its own guide.

    Find out: in your site's code, open next.config (.js, .mjs or .ts) and look for output: 'export'.

    • It is there: your site is exported as static files. This guide is yours.
    • It is not there: your pages are rendered on a server, on Node.js or on a host such as Vercel. Follow the Next.js guide.

    Both guides need the App Router (the app/ folder). For pages on the Pages Router (the pages/ folder), neither applies.

    What you need

    A site on Next.js 15 or newer, with the App Router, exported as static files (output: 'export' in next.config)

    A host or CDN that can run a function for each request, in front of those files, such as CloudFront with Lambda@Edge, Cloudflare Workers or Netlify Edge Functions

    Access to the site's code, and to the host's configuration

    The Uberall Store Finder package for Next.js, which you install in step 1: 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

    A static site has no server that builds a page when a visitor asks for it. So the function in front of the files does that part: for each address under the store finder, it takes the store finder page's file and puts that address's stores into it. Step 4 shows it on S3 and CloudFront; on another host, the same function runs in that host's edge functions.

    These steps do not work for:

    • pages on the Pages Router (the pages/ folder)
    • a host that cannot run a function in front of the files

    There, the store finder keeps working as it does today, on the visitor's screen.

    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 than data-key, data-language, data-countries and data-widgetoriginurl
    • settings your site's scripts pass to UberallStorefinderMount or UberallStorefinderRestart, other than withoutMap

    To find them, look in two places:

    • The store finder's div, in the page's source: any data- attribute other than the four above.
    • Your site's scripts, in your components and in the scripts your layout loads: calls to UberallStorefinderMount or UberallStorefinderRestart, and code of your own that loads the store finder.

    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 have your page's own title and description, from siteHead (step 2).
    • 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 a static site, the store finder's pages carry none of your site's own canonical link or Open Graph tags (step 2): which of them Uberall sends is only known at each visit. Your title and description, from siteHead (step 2), are used where Uberall sends none.

    Step 1: Install the Uberall Store Finder package

    In your site'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 function in front of the files (step 3) uses the same package.

    Step 2: Put the store finder on its page

    Add the store finder's settings as lib/store-finder-settings.ts, and replace YOUR_LOCATOR_KEY and the address with your own:

    import type { StoreFinderSettings } from '@uberall/store-finder-nextjs';
    
    export const storeFinderSettings: StoreFinderSettings = {
      locatorKey: 'YOUR_LOCATOR_KEY',
      widgetOriginUrl: 'https://www.example.com/store-locator',
    };

    For a store finder at /store-locator, add app/store-locator/page.tsx:

    import { StoreFinder, storeFinderMetadata } from '@uberall/store-finder-nextjs';
    import { storeFinderSettings } from '@/lib/store-finder-settings';
    
    export const metadata = storeFinderMetadata;
    
    export default function StoreLocatorPage() {
      return (
        <StoreFinder
          settings={storeFinderSettings}
          siteHead={{ title: 'Store locator | Example', description: 'Find our stores near you.' }}
        />
      );
    }

    next build writes this page as store-locator.html, with an empty store finder snippet that carries the settings. The function in front of the files fills it for each address.

    storeFinderMetadata takes your site's own title, description, canonical link and Open Graph tags off the page, since Uberall sends its own for each address. Without it, the browser would get yours back next to Uberall's. Put your page's title and description in siteHead instead: the function in front of the files uses each of them when Uberall sends none, and both when the stores do not arrive. If your layout writes its own structured data (application/ld+json), leave it off this page too: Uberall sends the store's.

    widgetOriginUrl is the store finder's full address, as visitors see it, without a slash at the end. If your page's content comes from a CMS, the settings can come from there too, like the rest of the page. The token cannot: it stays with the function in front of the files.

    Every address under the store finder's page belongs to the store finder. Do not put other pages under it.

    If the page already has the store finder snippet, remove it, once its settings are at Uberall (the section above): the snippet div, its storeFinderWidget-v2.js script, and any code of your own that loads the store finder. The component puts the snippet and the script on the page. If its addresses have #! in them today, this removes it.

    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="de" language: 'de'
    data-countries="US,DE" countries: 'US,DE'
    data-widgetoriginurl="https://www.example.com/store-locator" widgetOriginUrl: 'https://www.example.com/store-locator'

    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.

    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, so it goes through the function in front of the files.

    Step 3: Run the store finder's function in front of the files

    The package has the function for this, insertStoreFinderRender, in @uberall/store-finder-nextjs/edge. It needs no Next.js and no React, only Request, Response and fetch, so it runs in the edge functions of most hosts:

    import { insertStoreFinderRender } from '@uberall/store-finder-nextjs/edge';
    
    // request: the visitor's request. html: the content of store-locator.html. token: your render token.
    const response = await insertStoreFinderRender(request, html, token);

    It reads the store finder's settings from the page's snippet, asks Uberall for the stores of the address in request, puts them into the snippet, and puts Uberall's head tags into <head>. Its answer carries how long it may be cached. Without the stores, it answers with the page as it came, with the reason in a comment at its end.

    Set up your host so that:

    • Every address under the store finder reaches the function, as the visitor asked for it. The page itself (/store-locator), each store (/store-locator/l/...) and a search (/store-locator/s?...), with their query. A rewrite that sends these addresses to store-locator.html before the function, or before a cache, has to leave them alone: the function needs the address that was asked for.
    • The function gets store-locator.html for every one of them, and answers with what insertStoreFinderRender returns.
    • The .txt files under the store finder's address are served as files. Next.js fetches them, such as /store-locator/__next._tree.txt, when the visitor navigates in the browser.
    • The token stays with the host, in its secret store, never in the site's files.
    • A cache keeps each address on its own, path and query, for no longer than the answer says.

    Step 4: On S3 and CloudFront

    On CloudFront, the function is a Lambda@Edge function on the origin request of the store finder's addresses. It reads store-locator.html from the S3 bucket, and the token from AWS Systems Manager Parameter Store, since Lambda@Edge takes no environment variables.

    a) Keep the token in Parameter Store

    In us-east-1, create a parameter of type SecureString, named /uberall/store-finder/render-token, with your render token as its value.

    b) Make the function

    The package comes with this function as an example, in examples/lambda-edge. Take it out of the package:

    curl -sL https://locator.uberall.com/locator-assets/nextjs/uberall-store-finder-nextjs-0.2.1.tgz | tar -xz package/examples/lambda-edge
    cd package/examples/lambda-edge

    In its index.mjs, set your page's file in PAGE_KEY, if it is not store-locator.html. Then install the package and pack the folder:

    npm install
    zip -r store-finder-lambda-edge.zip index.mjs package.json node_modules

    In us-east-1, create a Lambda function on Node.js 22, with the handler index.handler, and upload the zip. Set its timeout to 15 seconds: the default, 3 seconds, is shorter than the function may wait for Uberall. Its execution role needs:

    • s3:GetObject on arn:aws:s3:::YOUR_BUCKET/store-locator.html, with the origin's path before the file name if it has one, such as YOUR_BUCKET/site/store-locator.html
    • ssm:GetParameter on the parameter from a), and kms:Decrypt on its key if it is not the default one
    • the trust of both lambda.amazonaws.com and edgelambda.amazonaws.com

    Publish a version of the function: CloudFront takes a version, not $LATEST.

    c) Put it in front of the store finder's addresses

    In your CloudFront distribution, add two behaviors with the S3 origin, one for the path pattern /store-locator and one for /store-locator/*. For each:

    • Cache policy: one that keys on the query string (all of it) and honors the origin's cache-control, such as a policy with a minimum TTL of 0. A search (/s?...) needs its query, and each address has its own page. Turn on its Gzip compression support: the function then sends the page gzipped, and a page with its stores stays well below the 1 MB CloudFront takes from a function.
    • Function associations: the function's version from b), on Origin request.

    If a CloudFront Function or another Lambda@Edge function rewrites /store-locator/l/... to store-locator.html today, leave the store finder's addresses out of it: the function from b) needs them as they were asked for, and serves the page's file itself.

    Step 5: Deploy and check

    Export and deploy the site, and wait for the distribution to deploy.

    Open one of your stores in the browser, such as /store-locator/l/..., right click, and choose View page source. Search the source for __ubSfSsr. If you find it, it works.

    Search the same source for <title and rel="canonical". Each should appear exactly once, with the store's name as the title. Then do the same for the store finder's main page.

    More than one store finder on the site

    Each store finder has its own render token and its own page. For the second one, follow steps 2 to 4 again: its own page and settings, a parameter for its token, a function with its page's file and its parameter, and behaviors for its address.

    If it does not work

    What you see What to do
    The source ends with no server render (no token) The function cannot read the token: check the parameter's name and region, and the role's ssm:GetParameter.
    The source ends with no server render (declined: unauthorised) The token is not the one Uberall gave you for this locator key.
    The source ends with no server render (request failed) The function cannot reach Uberall. It needs outgoing HTTPS to uberall.com.
    The source ends with no server render (no store finder snippet) The function reads another page: check PAGE_KEY, and that the page uses <StoreFinder /> (step 2).
    The source ends with no server render (response over 1 MB) The page with its stores is larger than CloudFront takes from a function: turn on Gzip in the cache policy (step 4 c).
    The source ends with another no server render (...) Contact Uberall, with that text.
    No no server render and no __ubSfSsr The function does not run on that address: check the behaviors and their association (step 4 c).
    A store's page answers "Access Denied" or "Not Found" The address does not reach the function: check the path patterns in step 4 c.
    A search (/s?...) shows the main page The cache policy drops the query string: key it on all of it (step 4 c).
    Every store's page shows the same store A rewrite or a cache before the function joins the addresses: see the end of step 4 c.

    When the store finder content does not arrive

    The store finder keeps working in every case. If the content does not arrive, because the function cannot reach Uberall, the connection takes too long or it returns an error, the page goes out without it, and the store finder appears on the visitor's screen as usual.

    After such a failure, the function serves the store finder's pages without the content for 30 seconds, and then asks Uberall again. A page larger than CloudFront takes from a function (1 MB, gzipped when the browser takes it) also goes out without the content.

    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.

    The function's answer says how long it may be cached: five minutes with the content, ten seconds without it, so a page without its stores is asked for again soon. With a cache policy that honors it, as in step 4 c, CloudFront keeps each page no longer than that.

    If the function cannot read store-locator.html, CloudFront takes the file from S3 as it is, with the Cache-Control it has in the bucket. Without one, CloudFront keeps it for the cache policy's default TTL. To keep it short, upload the file with --cache-control "public, max-age=10".

    next.js static export

    Was this article helpful?

    Yes
    No
    Give feedback about this article

    Related Articles

    • FAQ about Self Serve Locator & Pages
    • What is embedded Locator + Pages (Self Serve)?
    • Customizations of Locator + Pages via CSS
    • Locator and Pages attributes
    • Filters for Locator & Pages
     

    Copyright 2026 – uberall.

    Expand