SSR and initial data

<mapvx-website> works in server-rendered sites (Next.js, Nuxt, SvelteKit, Angular SSR and others), but it renders only in the browser. This page explains what the server can do for it, the optional initial-data attribute with its helper package, and one recipe per framework.

How it works

• The server outputs only the tag. Your framework renders <mapvx-website> with its attributes and nothing inside it. Cards, profiles and the map are built in the browser, so the server HTML contains no place markup for crawlers, with or without initial-data. If you need crawlable content, render it yourself outside the element.
• The element replaces its content. When main.js defines the element in the browser, the component builds its interface inside the tag and removes anything you put there, such as fallback text.
• Never import the bundle in server code. Evaluating main.js in Node.js throws ReferenceError: HTMLElement is not defined. That includes top-level imports in components that are also rendered on the server, such as Next.js 'use client' components. Load it with a <script type="module"> or with a dynamic import() that runs only in the browser. Type-only imports (import type) are safe anywhere, because they are removed at compile time.
• With React, load it after hydration. With React 19, if the element upgrades before React hydrates the page, React reports a recoverable hydration error and re-creates the tree on the client (hydration mismatch). Loading the bundle after hydration avoids it. The Next.js recipe below does this, and in SvelteKit onMount also runs after hydration.
• Attributes are strings. The server can only pass attributes, so booleans must be the strings "true" or "false" (boolean attributes).
• CSP nonce. If your policy uses a nonce for styles, render the ngCspNonce attribute on the element from the server (Security and privacy).

Once the bundle runs in the browser:

1. The element upgrades and reads its attributes. If initial-data contains places, their cards render right away.
2. With api-key set, the component starts the MapVX SDK and requests the available places, the configuration and the institutions, whether or not initial-data is present.
3. The map is created the first time one is on screen (map view, a place profile or a route), once the configuration has arrived. Search, place details and routes also go through the SDK.

Versions before 1.5.4 could show a blank map on the first map-view load in server-rendered hosts (What’s new).

What initial-data changes

initial-data is only a head start for the first cards: it doesn’t reduce API traffic and it doesn’t replace api-key. Without api-key, the grid renders from initial-data, but the map, search, place details and routes don’t work.

The attribute value

• initial-data takes a JSON string with two keys, availablePlaces and institutions (the InitialData type). prepareInitialData returns exactly that string. Other keys are ignored.
• Invalid JSON is ignored without any console message in the published build, and the component loads normally from the API.
• If you set the initialData JS property instead, it must also be a string: an object throws a TypeError inside the component.
• The category tabs come from the institution in the data whose id equals institution-id exactly, so pass the id without surrounding spaces.
• Every change to the value is parsed again and adds its places again (see the known issue). Set it once, on the first render.
• The category row has nothing on at the start either way, so the grid opens unfiltered whether or not initial-data is used. To open on specific categories, add ?tab= to the page URL (deep links).

Attribute reference: Attributes.

The helper package

@mapvx/web-components-ssr-helpers prepares the initial-data string on your server. Install it next to the component and pin the exact versions you tested (0.1.1 is the helper’s current version):

npm install --save-exact @mapvx/web-components-ssr@1.6.1 @mapvx/web-components-ssr-helpers@0.1.1

Its only export is prepareInitialData. The package ships ESM and CommonJS builds with TypeScript declarations, plus an IIFE build for script tags (dist/helpers.iife.js, global Helper):

import { prepareInitialData } from '@mapvx/web-components-ssr-helpers'
 
const initialData = await prepareInitialData('YOUR_API_KEY')

const { prepareInitialData } = require('@mapvx/web-components-ssr-helpers')
 
prepareInitialData('YOUR_API_KEY').then((initialData) => {
  // Render <mapvx-website initial-data="..."> with this string
})

Requirements:

• A server runtime with a global fetch: Node.js 18 or later, or an edge or worker runtime. The helper has no runtime dependencies and declares no engines. The component package does declare engines.node, which only affects installation (Requirements).
• Outbound HTTPS access from your server to https://api.mapvx.com.
• Server-side use. The helper also works in a browser, but gains nothing there: the component requests the same data itself.

It has no options: the data is always in English, and there is no setting for the base URL, a timeout or an institution. It returns every place and institution available to the API key.

If you still use the legacy @mapvx/website-component-helpers package, switch to this one: the legacy 0.1.1 throws instead of returning null when the API key is invalid or missing (migration from 0.x).

prepareInitialData

function prepareInitialData(apiKey: string): Promise<string>

It sends two parallel GET requests to the MapVX API at https://api.mapvx.com: the places available to apiKey, and its institutions. Both carry the key and lang=en in the query string. The key is public anyway: the browser receives it in the api-key attribute.

Return value

It resolves to a JSON string, not an object. Once parsed, the string has this shape:

// InitialData, exported as a type by @mapvx/web-components-ssr
interface InitialData {
  availablePlaces: PlaceResponse[] | null
  institutions: InstitutionResponse[] | null
}

PlaceResponse and InstitutionResponse are the raw API objects. Their types are exported by @mapvx/web-components-ssr for import type (TypeScript types); the helper itself types the result only as string.

• Pass the string to initial-data unchanged. There’s no need to parse it and serialize it again.
• It’s large. With an API key of 255 places and 4 institutions it measured about 557 KB, and about 830 KB once escaped into the HTML attribute (about 164 KB gzipped). Frameworks that also serialize page data for hydration (the RSC payload in Next.js, the Nuxt payload, SvelteKit load data, Angular TransferState) send it a second time.

Errors

The component ignores a null half; with api-key set, it loads all its data from the API in any case. To keep a failure or a slow API from breaking the render, wrap the call with a timeout and fall back to no initial-data. The recipes below import this wrapper:

// mapvx-initial-data.ts
import { prepareInitialData } from '@mapvx/web-components-ssr-helpers'
 
// Resolves to the initial-data string, or undefined when it can't be prepared in time.
// With undefined, render the element without initial-data: it loads the data itself.
export async function getMapvxInitialData(
  apiKey: string,
  timeoutMs = 3000,
): Promise<string | undefined> {
  let timer: ReturnType<typeof setTimeout> | undefined
  const timeout = new Promise<never>((_, reject) => {
    timer = setTimeout(() => reject(new Error('MapVX initial data timed out')), timeoutMs)
  })
  try {
    return await Promise.race([prepareInitialData(apiKey), timeout])
  } catch {
    return undefined
  } finally {
    clearTimeout(timer)
  }
}

The timeout only stops the wait: the requests aren’t cancelled and finish in the background.

Caching and freshness

• Each call makes two API requests and returns hundreds of KB; one measurement took about 1.5 s. Avoid calling it on every request: cache the string on the server for a few minutes, for example with your framework’s revalidation (revalidate in Next.js).
• If the page is prerendered at build time (Next.js without revalidate or dynamic rendering, Angular RenderMode.Prerender, static exports), the data is fixed at build time. The component still loads current data in the browser and appends it, so places removed after the build keep showing next to the current ones.

Known issue: duplicated place cards

Next.js (App Router)

A Server Component prepares the data, and a Client Component renders the element and loads the bundle from public/ after hydration.

npm install --save-exact @mapvx/web-components-ssr@1.6.1 @mapvx/web-components-ssr-helpers@0.1.1

// scripts/copy-mapvx.mjs
import { cpSync, readFileSync, rmSync } from 'node:fs'
 
const pkgDir = 'node_modules/@mapvx/web-components-ssr'
const { version } = JSON.parse(readFileSync(`${pkgDir}/package.json`, 'utf8'))
const target = `public/mapvx-website/${version}`
 
rmSync('public/mapvx-website', { recursive: true, force: true })
// main.js, every chunk-*.js and styles.css, with their published names
cpSync(`${pkgDir}/dist/browser`, target, { recursive: true })
console.log(`Copied @mapvx/web-components-ssr@${version} to ${target}`)

{
  "scripts": {
    "predev": "node scripts/copy-mapvx.mjs",
    "prebuild": "node scripts/copy-mapvx.mjs"
  }
}

// app/layout.tsx
import '@mapvx/web-components-ssr/dist/browser/styles.css'

// types/mapvx-website-react.d.ts (the default Next.js tsconfig includes it)
import type { DetailedHTMLProps, HTMLAttributes } from 'react'
import type { UserAction } from '@mapvx/web-components-ssr'
 
type BoolAttr = 'true' | 'false'
 
export interface MapvxWebsiteAttributes
  extends DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> {
  'api-key'?: string
  'institution-id'?: string
  'initial-data'?: string
  'default-to-map'?: BoolAttr
  'show-category-filters'?: BoolAttr
  'show-city-filter'?: BoolAttr
  'inherit-font-family'?: BoolAttr
  'hide-deals'?: BoolAttr
  'show-deal-labels'?: BoolAttr
  'card-width'?: number | string
  'rows-per-page'?: number | string
  onuserAction?: (event: CustomEvent<UserAction>) => void
  oncardSelected?: (event: CustomEvent<string>) => void
}
 
declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'mapvx-website': MapvxWebsiteAttributes
    }
  }
}

// app/mapvx-website.tsx
'use client'
 
import Script from 'next/script'
import type { UserAction } from '@mapvx/web-components-ssr'
 
// Must match the folder created by scripts/copy-mapvx.mjs
const MAPVX_VERSION = '1.6.1'
 
type Props = {
  apiKey: string
  institutionId: string
  initialData?: string
}
 
export function MapvxWebsite({ apiKey, institutionId, initialData }: Props) {
  return (
    <>
      {/* next/script loads it after hydration by default (afterInteractive) */}
      <Script type="module" src={`/mapvx-website/${MAPVX_VERSION}/main.js`} />
      <mapvx-website
        api-key={apiKey}
        institution-id={institutionId}
        initial-data={initialData}
        default-to-map="true"
        onuserAction={(event: CustomEvent<UserAction>) => console.log(event.detail)}
      />
    </>
  )
}

# .env.local
MAPVX_API_KEY=YOUR_API_KEY
MAPVX_INSTITUTION_ID=YOUR_INSTITUTION_ID

// app/page.tsx (Server Component)
import { getMapvxInitialData } from '../lib/mapvx-initial-data'
import { MapvxWebsite } from './mapvx-website'
 
// Regenerate at most every 5 minutes. Without it, Next.js prerenders the page once, at build time
export const revalidate = 300
 
export default async function Page() {
  const apiKey = process.env.MAPVX_API_KEY ?? ''
  const initialData = await getMapvxInitialData(apiKey)
 
  return (
    <MapvxWebsite
      apiKey={apiKey}
      institutionId={process.env.MAPVX_INSTITUTION_ID ?? ''}
      initialData={initialData}
    />
  )
}

Nuxt

A server route prepares the data, so the helper runs on the server both during SSR and during client-side navigation. A .client plugin loads the bundle in the browser only.

The steps use APIs that Nuxt 3 and Nuxt 4 share. In a Nuxt 4 project with the default app/ directory, put pages/ and plugins/ inside app/; server/ stays at the project root.

// nuxt.config.ts
export default defineNuxtConfig({
  css: ['@mapvx/web-components-ssr/dist/browser/styles.css'],
  vue: {
    compilerOptions: {
      // Without this, Vue warns about an unknown component and @userAction listeners don't fire
      isCustomElement: (tag) => tag === 'mapvx-website',
    },
  },
  runtimeConfig: {
    // The browser needs both values as attributes, so they are public.
    // Set them with NUXT_PUBLIC_MAPVX_API_KEY and NUXT_PUBLIC_MAPVX_INSTITUTION_ID
    public: {
      mapvxApiKey: '',
      mapvxInstitutionId: '',
    },
  },
})

// plugins/mapvx.client.ts (the .client suffix keeps it off the server)
export default defineNuxtPlugin(() => {
  // Not awaited, so hydration doesn't wait for the download
  import('@mapvx/web-components-ssr')
})

// server/api/mapvx-initial-data.get.ts
import { getMapvxInitialData } from '../utils/mapvx-initial-data'
 
export default defineEventHandler(async (event) => {
  const { mapvxApiKey } = useRuntimeConfig(event).public
  return { initialData: (await getMapvxInitialData(mapvxApiKey)) ?? null }
})

<!-- pages/index.vue -->
<script setup lang="ts">
const config = useRuntimeConfig()
const { data } = await useAsyncData('mapvx-initial-data', () => $fetch('/api/mapvx-initial-data'))
</script>
 
<template>
  <mapvx-website
    :api-key="config.public.mapvxApiKey"
    :institution-id="config.public.mapvxInstitutionId"
    :initial-data="data?.initialData ?? undefined"
    default-to-map="true"
  />
</template>

SvelteKit

A server load function prepares the data and passes it to the page, and the page imports the bundle in onMount, which runs only in the browser.

# .env
MAPVX_API_KEY=YOUR_API_KEY
MAPVX_INSTITUTION_ID=YOUR_INSTITUTION_ID

// src/routes/+page.server.ts
import { MAPVX_API_KEY, MAPVX_INSTITUTION_ID } from '$env/static/private'
import { getMapvxInitialData } from '$lib/server/mapvx-initial-data'
import type { PageServerLoad } from './$types'
 
export const load: PageServerLoad = async () => ({
  // The browser needs the key as the api-key attribute, so returning it is fine
  apiKey: MAPVX_API_KEY,
  institutionId: MAPVX_INSTITUTION_ID,
  initialData: await getMapvxInitialData(MAPVX_API_KEY),
})

<!-- src/routes/+page.svelte (Svelte 5) -->
<script lang="ts">
  import { onMount } from 'svelte'
  import '@mapvx/web-components-ssr/dist/browser/styles.css'
 
  let { data } = $props()
 
  // onMount runs only in the browser, after hydration
  onMount(() => {
    import('@mapvx/web-components-ssr')
  })
</script>
 
<mapvx-website
  api-key={data.apiKey}
  institution-id={data.institutionId}
  initial-data={data.initialData}
  default-to-map="true"
></mapvx-website>

Angular SSR

The host app copies the bundle as an asset and loads it from index.html, so the server never evaluates it. The element bundles its own Angular and runs independently of your app’s Angular version and change detection setup (for example, an Angular 20 app with zone.js). The server-side code below uses PendingTasks.run and the RenderMode server routes, which need Angular 19 or later.

{
  "glob": "**/*",
  "input": "node_modules/@mapvx/web-components-ssr/dist/browser",
  "output": "mapvx-website/1.6.1"
}

<!-- src/index.html, inside <head> -->
<link rel="stylesheet" href="mapvx-website/1.6.1/styles.css" />
<script type="module" src="mapvx-website/1.6.1/main.js"></script>

// src/app/mapvx.component.ts
import { isPlatformServer } from '@angular/common'
import {
  Component,
  CUSTOM_ELEMENTS_SCHEMA,
  PLATFORM_ID,
  PendingTasks,
  TransferState,
  inject,
  makeStateKey,
  signal,
} from '@angular/core'
import { getMapvxInitialData } from './mapvx-initial-data'
 
const MAPVX_INITIAL_DATA = makeStateKey<string>('mapvx-initial-data')
 
@Component({
  selector: 'app-mapvx',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <mapvx-website
      [attr.api-key]="apiKey"
      [attr.institution-id]="institutionId"
      [attr.initial-data]="initialData() || null"
      default-to-map="true"
    ></mapvx-website>
  `,
})
export class MapvxComponent {
  readonly apiKey = 'YOUR_API_KEY'
  // Never bind institution-id to null or undefined: removing it throws inside the component
  readonly institutionId = 'YOUR_INSTITUTION_ID'
 
  private readonly transferState = inject(TransferState)
  // In the browser, this reads the string the server rendered with
  readonly initialData = signal(this.transferState.get(MAPVX_INITIAL_DATA, ''))
 
  constructor() {
    if (isPlatformServer(inject(PLATFORM_ID)) && !this.initialData()) {
      // The server waits for this task before it serializes the page
      inject(PendingTasks).run(async () => {
        const data = await getMapvxInitialData(this.apiKey)
        if (data) {
          this.transferState.set(MAPVX_INITIAL_DATA, data)
          this.initialData.set(data)
        }
      })
    }
  }
}

// src/app/app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr'
 
export const serverRoutes: ServerRoute[] = [
  // RenderMode.Prerender would fix the data at build time
  { path: '**', renderMode: RenderMode.Server },
]

Client-only setup (no initial data)

Every recipe above also works without initial-data: remove the helper and the server-side data code, and keep the browser-only loading. You don’t need @mapvx/web-components-ssr-helpers then. The component requests its data in the browser, and the cards appear once, when the API responds.

In Next.js, for example, a Server Component is enough. Keep the copy into public/, the styles import and the TypeScript declaration from the Next.js recipe:

// app/page.tsx
import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script type="module" src="/mapvx-website/1.6.1/main.js" />
      <mapvx-website
        api-key={process.env.MAPVX_API_KEY ?? ''}
        institution-id={process.env.MAPVX_INSTITUTION_ID ?? ''}
        default-to-map="true"
      />
    </>
  )
}