Instalación

Hay tres formas de cargar <mapvx-website>. Todas llevan al mismo resultado: el código de main.js ejecutándose como módulo ES, styles.css cargado como hoja de estilos y un elemento <mapvx-website> en la página.

Los ejemplos usan la versión 1.6.1, la más reciente. Fija la versión exacta que probaste, tanto en las URL como en package.json.

Requisitos

• Credenciales de MapVX: una API key y un id de institución emitidos por MapVX. La API key es necesaria para los datos, el mapa, la búsqueda y las rutas. Sin un id de institución que coincida, el componente usa la primera ciudad configurada y no muestra pestañas de categorías en la primera carga. Consulta api-key e institution-id.
• Navegador: custom elements, módulos ES (<script type="module">) y container queries de CSS, de las que depende el diseño responsivo.
• WebGL para el mapa (vista de mapa, perfiles de lugares y rutas). La cuadrícula de tarjetas de lugares no lo necesita. La versión 1.6.1 usa WebGL2 y recurre a WebGL 1 si no está disponible; cuenta con que necesitarás WebGL2, porque el motor de mapas incluido en las próximas versiones lo exige.
• Un elemento por página. Usa un solo <mapvx-website> por página: todos los elementos de una página comparten una misma aplicación (router, datos cargados, mapa y SDK) y se interfieren entre sí. Consulta Varias instancias.
• Content Security Policy: si tu sitio envía una, permite las fuentes que se indican en Seguridad y privacidad.
• Node.js, solo para instalaciones con npm: el paquete declara engines.node como ^22.22.3 || >=24.15.0. No tiene efecto en el navegador. Con otras versiones de Node, npm muestra una advertencia EBADENGINE y pnpm una advertencia Unsupported engine (ambos fallan solo con engine-strict), y Yarn 1 detiene la instalación a menos que pases --ignore-engines.

Contenido del paquete

@mapvx/web-components-ssr publica estos archivos:

El paquete no incluye:

• Fuentes ni imágenes. El componente pide la fuente Open Sans, pero no la carga; consulta Fuentes. Las imágenes de los lugares vienen de los datos de MapVX.
• Una versión para servidor. El elemento se renderiza solo en el navegador, y evaluar main.js en Node lanza un error. Consulta SSR y datos iniciales.
• Una API de JavaScript en tiempo de ejecución. main.js solo exporta nombres internos que usan sus propios chunks. Las declaraciones sirven solo para import type; consulta Solo tipos.
• Tipos para el propio elemento (JSX o HTMLElementTagNameMap). Consulta Tipar el elemento.
• Polyfills. No incluye ninguno, y la página no necesita zone.js.
• Un archivo aparte para el worker del mapa. El worker del mapa viene dentro de main.js y se inicia desde una URL blob:, que una Content Security Policy debe permitir (CSP).
• Source maps.

El paquete no tiene campo exports, así que las importaciones profundas como @mapvx/web-components-ssr/dist/browser/styles.css se resuelven.

npm

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

--save-exact guarda la versión exacta en lugar de un rango, de modo que cada instalación obtenga la compilación que probaste. Después, importa el paquete con tu bundler (Bundlers) o copia sus archivos a tu carpeta pública (Alojamiento propio).

npm también instala los paquetes que el componente declara como dependencies (paquetes de Angular 22, Font Awesome, ngx-google-analytics, rxjs y tslib). El bundle del navegador no los usa: main.js ya contiene todo lo que ejecuta.

Para preparar el atributo initial-data en tu servidor, instala el paquete helper donde se ejecuta tu código de servidor. Consulta El helper.

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

CDN

<link
  rel="stylesheet"
  href="https://unpkg.com/@mapvx/web-components-ssr@1.6.1/dist/browser/styles.css"
/>
<script
  type="module"
  src="https://unpkg.com/@mapvx/web-components-ssr@1.6.1/dist/browser/main.js"
></script>
 
<style>
  /* El elemento es inline por defecto: dale una caja de bloque */
  mapvx-website {
    display: block;
    width: 100%;
  }
</style>
 
<mapvx-website api-key="YOUR_API_KEY" institution-id="YOUR_INSTITUTION_ID"></mapvx-website>

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@mapvx/web-components-ssr@1.6.1/dist/browser/styles.css"
/>
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@mapvx/web-components-ssr@1.6.1/dist/browser/main.js"
></script>
 
<style>
  /* El elemento es inline por defecto: dale una caja de bloque */
  mapvx-website {
    display: block;
    width: 100%;
  }
</style>
 
<mapvx-website api-key="YOUR_API_KEY" institution-id="YOUR_INSTITUTION_ID"></mapvx-website>

Los patrones de URL son https://unpkg.com/@mapvx/web-components-ssr@VERSION/dist/browser/FILE y https://cdn.jsdelivr.net/npm/@mapvx/web-components-ssr@VERSION/dist/browser/FILE.

• type="module" es obligatorio. main.js es un módulo ES. Cargado como script clásico, falla (en Chromium, con SyntaxError: Unexpected token 'export') y el elemento queda vacío (detalles). Los scripts de módulo se difieren automáticamente, así que defer no hace falta.
• styles.css es obligatorio. Sin él, se rompen los colores, las fuentes, el mapa y los íconos. Es una hoja de estilos global que también se aplica al resto de tu página; consulta Estilos globales.
• Fija una versión exacta. jsDelivr sirve @latest sin redirigir y permite que los navegadores lo guarden en caché hasta 7 días, así que un visitante puede conservar un main.js antiguo después de que una versión nueva haya cambiado los nombres de los chunks. unpkg redirige @latest a la versión exacta. No uses las etiquetas dev ni rc en producción; consulta Canales de publicación.
• Ambas CDN envían Access-Control-Allow-Origin: * y un tipo de contenido JavaScript, así que main.js puede cargar sus chunks desde la misma URL versionada.
• Con una Content Security Policy, permite el host de la CDN en script-src y style-src (Política con lista de permitidos).
• La regla display: block le da al elemento un ancho en el que distribuir su contenido; consulta Tamaño.

Alojamiento propio

Sirve los archivos desde tu propio origen cuando no quieras depender de una CDN de terceros, o cuando tu framework sirva archivos estáticos desde una carpeta pública.

// copy-mapvx.mjs: ejecútalo después de npm install y antes de compilar tu sitio
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}`
 
// Borra las versiones anteriores y copia main.js, cada chunk-*.js y styles.css sin cambiar sus nombres
rmSync('public/mapvx-website', { recursive: true, force: true })
cpSync(`${pkgDir}/dist/browser`, target, { recursive: true })
console.log(`Se copió @mapvx/web-components-ssr@${version} en ${target}`)

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

<link rel="stylesheet" href="/mapvx-website/1.6.1/styles.css" />
<script type="module" src="/mapvx-website/1.6.1/main.js"></script>

Caché. main.js y styles.css conservan el mismo nombre en todas las versiones, mientras que los nombres de los chunks cambian. Por eso la caché larga de arriba solo es segura en una ruta que incluya la versión. Si sirves los archivos desde una ruta fija, una caché larga puede combinar un main.js desactualizado con los archivos de otra versión: en ese caso, usa una caché corta o no-cache para main.js y styles.css.

Tipo de contenido. Un servidor que responde a un archivo inexistente con una página HTML de respaldo (algo típico en las aplicaciones de una sola página) hace que el navegador rechace el módulo; revisa la ruta si ves un error de tipo MIME o Unexpected token '<' (detalles).

Otro origen. Los navegadores descargan los scripts de módulo y sus importaciones en modo CORS, así que si main.js y los chunks están en un origen distinto al de la página (tu propia CDN, por ejemplo), ese origen debe enviar Access-Control-Allow-Origin. No hace falta el atributo crossorigin. Si agregas crossorigin="use-credentials", el servidor debe devolver tu origen exacto en lugar de *, además de Access-Control-Allow-Credentials: true. styles.css, cargado con un enlace de hoja de estilos normal, no necesita cabeceras CORS.

Bundlers

// Archivo de entrada de una app renderizada en el cliente
import '@mapvx/web-components-ssr'
import '@mapvx/web-components-ssr/dist/browser/styles.css'

• La importación con solo el nombre del paquete se resuelve, mediante su campo main, a dist/browser/main.js; importar @mapvx/web-components-ssr/dist/browser/main.js es equivalente.
• Verificado con Vite 7 (compilación y ejecución en el navegador). Vite vuelve a empaquetar los chunks con sus propios nombres de archivo, así que las reglas de nombres de Alojamiento propio no se aplican a su salida.
• No verificado: webpack, Turbopack y Angular CLI. Si tu bundler tiene problemas con el paquete, aloja los archivos tú mismo; no necesitan procesamiento.
• Carga una sola copia por página. No importes el paquete y además agregues una etiqueta script para una copia de CDN o alojada por ti. La segunda copia inicia una segunda aplicación y no logra registrar el elemento (Elemento ya definido).

// Solo en código que corre en el navegador: useEffect, onMounted, onMount, un plugin .client de Nuxt…
import('@mapvx/web-components-ssr')

Esperar al elemento

main.js primero inicia su aplicación y registra <mapvx-website> un momento después, de forma asíncrona. Los elementos que ya están en la página se actualizan (upgrade) en ese momento. La mayoría de las integraciones no necesita esperarlo:

• Los atributos definidos antes del upgrade se leen cuando este ocurre.
• Las propiedades de JavaScript asignadas al elemento antes del upgrade también se toman en cuenta.
• Los listeners de eventos se pueden agregar de inmediato, porque los eventos son eventos DOM comunes que se despachan en el mismo elemento. Agrégalos cuanto antes: los eventos ya emitidos no se vuelven a emitir, y un deep link puede emitir show-place durante el arranque. Consulta Escuchar eventos.

Usa customElements.whenDefined() cuando necesites el elemento ya actualizado, por ejemplo para leer el valor actual de una propiedad o para ocultar un indicador de carga propio:

// En un script de módulo, donde se permite await en el nivel superior
const el = document.querySelector('mapvx-website')
 
// No hace falta esperar para esto
el.setAttribute('default-to-map', 'true')
el.addEventListener('userAction', (event) => console.log(event.detail))
 
await customElements.whenDefined('mapvx-website')
console.log(el.rowsPerPage) // el valor actual del componente

• No hagas polling con setTimeout ni con customElements.get(): whenDefined() se resuelve en cuanto el elemento queda registrado.
• Si main.js no se carga, o se carga como script clásico, la promesa nunca se resuelve. Consulta No se muestra nada.
• El contenido que pongas dentro de <mapvx-website> se elimina cuando el elemento se actualiza, así que no coloques ahí marcado de respaldo ni de SEO.

React

React 18 y 19 renderizan <mapvx-website> como un elemento DOM común. Se aplican tres reglas:

1. Pasa atributos en kebab-case con valores de texto: default-to-map="true", nunca default-to-map={true}. React 19 renderiza {true} como un atributo vacío, que el elemento interpreta como false, y omite {false}, así que se aplica el valor por defecto. React 18 convierte los booleanos en texto, pero los valores de texto funcionan en ambas versiones.
2. No uses props en camelCase como apiKey o defaultToMap. React 19 las asigna como propiedades solo si el elemento ya está definido al renderizar; si no, terminan como atributos en minúsculas que el elemento ignora.
3. Escucha los eventos mediante un ref con addEventListener. React 18 no tiene props de eventos para custom elements. React 19 sí, pero la prop debe ser on seguido del nombre exacto del evento, onuserAction; onUserAction nunca se dispara.

En una app renderizada en el cliente, importa el paquete una sola vez en el archivo de entrada:

// main.tsx (por ejemplo, una app de Vite)
import '@mapvx/web-components-ssr'
import '@mapvx/web-components-ssr/dist/browser/styles.css'

// MapvxWebsite.tsx
import { useEffect, useRef } from 'react'
import type { UserAction } from '@mapvx/web-components-ssr'
 
export function MapvxWebsite() {
  const ref = useRef<HTMLElement>(null)
 
  useEffect(() => {
    const el = ref.current
    if (!el) return
    const onUserAction = (event: Event) => {
      const action = (event as CustomEvent<UserAction>).detail
      console.log(action.type, action.data)
    }
    el.addEventListener('userAction', onUserAction)
    return () => el.removeEventListener('userAction', onUserAction)
  }, [])
 
  return (
    <mapvx-website
      ref={ref}
      api-key="YOUR_API_KEY"
      institution-id="YOUR_INSTITUTION_ID"
      default-to-map="true"
      show-city-filter="false"
    />
  )
}

Solo con React 19, la prop de evento es una alternativa al ref:

<mapvx-website
  api-key="YOUR_API_KEY"
  institution-id="YOUR_INSTITUTION_ID"
  onuserAction={(event: CustomEvent<UserAction>) => console.log(event.detail)}
/>

Con renderizado en el servidor, carga el bundle como se muestra en Next.js.

TypeScript

El paquete no incluye tipos JSX para el elemento, así que TSX marca mapvx-website como un elemento desconocido. Agrega un archivo de declaraciones que quede cubierto por el include de tu tsconfig.json. No le pongas el mismo nombre que a un archivo .ts o .tsx de la misma carpeta (por ejemplo, mapvx-website.d.ts junto al componente mapvx-website.tsx de Next.js): TypeScript omite entonces el archivo .d.ts sin ninguna advertencia (Tipar el elemento). Este se verificó con @types/react 19. Tipar los booleanos como los textos 'true' y 'false' también detecta en compilación el problema de los booleanos de React 19.

// types/mapvx-website-react.d.ts
import type { DetailedHTMLProps, HTMLAttributes } from 'react'
import type { UserAction } from '@mapvx/web-components-ssr'
 
type BoolAttr = 'true' | 'false' // React 19 convierte true en "" y omite false: pasa textos
 
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
  /** React 19+: escucha el evento 'userAction', que distingue mayúsculas y minúsculas */
  onuserAction?: (event: CustomEvent<UserAction>) => void
  /** React 19+: escucha el evento 'cardSelected' */
  oncardSelected?: (event: CustomEvent<string>) => void
}
 
declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'mapvx-website': MapvxWebsiteAttributes
    }
  }
}

Para las propiedades de JavaScript del elemento (HTMLElementTagNameMap), consulta Tipar el elemento.

Vue

Vue 3 debe saber que mapvx-website es un custom element. Sin compilerOptions.isCustomElement, Vue muestra la advertencia Failed to resolve component: mapvx-website, y los listeners @userAction en componentes de un solo archivo nunca se disparan.

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
 
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'mapvx-website',
        },
      },
    }),
  ],
})

// main.ts
import { createApp } from 'vue'
import '@mapvx/web-components-ssr'
import '@mapvx/web-components-ssr/dist/browser/styles.css'
import App from './App.vue'
 
createApp(App).mount('#app')

<script setup lang="ts">
import type { UserAction } from '@mapvx/web-components-ssr'
 
function onUserAction(event: Event) {
  const action = (event as CustomEvent<UserAction>).detail
  console.log(action.type, action.data)
}
</script>
 
<template>
  <mapvx-website
    api-key="YOUR_API_KEY"
    institution-id="YOUR_INSTITUTION_ID"
    default-to-map="true"
    show-city-filter="false"
    @userAction="onUserAction"
  />
</template>

• Funcionan los atributos de texto estáticos y también los bindings: :default-to-map="true" asigna el atributo como "true", y :show-city-filter="false" lo asigna como "false".
• Con isCustomElement configurado, @userAction y @cardSelected conservan las mayúsculas y minúsculas del nombre del evento.
• Esta configuración se verificó con Vue 3.5. En otras configuraciones de compilación, define la misma opción donde se configure el compilador de plantillas de Vue; consulta Using custom elements in Vue  (en inglés).
• Para Nuxt, consulta SSR y datos iniciales.

Angular

Copia los archivos publicados con una entrada assets en angular.json y cárgalos desde index.html. Así los archivos quedan exactamente como se publican y, en apps con Angular SSR, main.js queda fuera del bundle del servidor. La importación del paquete desde TypeScript a través de Angular CLI no se ha verificado. El elemento trae su propio Angular y se ejecuta junto al de tu aplicación; esta configuración se probó con una app anfitriona en Angular 20 que usa zone.js.

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

<!-- src/index.html, dentro de <head>. Al actualizar, cambia la versión aquí y en angular.json. -->
<link rel="stylesheet" href="mapvx-website/1.6.1/styles.css" />
<script type="module" src="mapvx-website/1.6.1/main.js"></script>

import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core'
import type { UserAction } from '@mapvx/web-components-ssr'
 
@Component({
  selector: 'app-mapvx',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <mapvx-website
      [attr.api-key]="apiKey"
      [attr.institution-id]="institutionId()"
      [attr.default-to-map]="defaultToMap()"
      [attr.show-city-filter]="false"
      (userAction)="onUserAction($event)"
    ></mapvx-website>
  `,
})
export class MapvxComponent {
  readonly apiKey = 'YOUR_API_KEY'
  readonly institutionId = signal('YOUR_INSTITUTION_ID')
  readonly defaultToMap = signal(true)
 
  onUserAction(event: Event) {
    const action = (event as CustomEvent<UserAction>).detail
    console.log(action.type, action.data)
  }
}

• schemas: [CUSTOM_ELEMENTS_SCHEMA] es obligatorio en cada componente cuya plantilla usa el elemento. Sin él, la compilación falla con 'mapvx-website' is not a known element.
• Usa bindings [attr.*]. Angular escribe los booleanos como "true" y "false", que el elemento interpreta correctamente.
• Nunca enlaces un atributo a null o undefined: Angular lo elimina, lo que desactiva show-category-filters y show-city-filter en lugar de restaurar sus valores por defecto, y provoca un error en el caso de institution-id. Consulta Eliminar atributos.
• El binding de plantilla (userAction) escucha en el propio elemento, con el nombre exacto del evento.
• Si el navegador recibe HTML en lugar de main.js (Unexpected token '<' o un error de tipo MIME), la entrada de assets o la ruta en index.html es incorrecta. Consulta Unexpected token '<'.
• Para apps de Angular renderizadas en el servidor, consulta Angular SSR.

Next.js

Con el App Router, sirve los archivos publicados desde public, carga main.js con next/script y renderiza el elemento desde un componente de cliente.

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

// app/directory/mapvx-website.tsx
'use client'
 
import Script from 'next/script'
import { useEffect, useRef } from 'react'
import type { UserAction } from '@mapvx/web-components-ssr'
 
export function MapvxWebsite() {
  const ref = useRef<HTMLElement>(null)
 
  useEffect(() => {
    const el = ref.current
    if (!el) return
    const onUserAction = (event: Event) => {
      const action = (event as CustomEvent<UserAction>).detail
      console.log(action.type, action.data)
    }
    el.addEventListener('userAction', onUserAction)
    return () => el.removeEventListener('userAction', onUserAction)
  }, [])
 
  return (
    <>
      <Script type="module" src="/mapvx-website/1.6.1/main.js" />
      <mapvx-website
        ref={ref}
        api-key="YOUR_API_KEY"
        institution-id="YOUR_INSTITUTION_ID"
        default-to-map="true"
      />
    </>
  )
}

// app/directory/page.tsx
import { MapvxWebsite } from './mapvx-website'
 
export default function Page() {
  return <MapvxWebsite />
}

• Carga main.js solo mediante next/script. Nunca pongas import '@mapvx/web-components-ssr' al principio de un archivo de componente: Next.js también renderiza los componentes de cliente en el servidor, y la importación lanza un error ahí.
• Mantén la strategy por defecto (afterInteractive), que inserta el script desde el cliente después de la hidratación. Si el elemento se actualiza antes de la hidratación, React 19 informa Hydration failed because the server rendered HTML didn't match the client y vuelve a crear el árbol en el cliente.
• Conserva los nombres de archivo. Algunos ejemplos antiguos copian main.js como bundle.js, lo que rompe las importaciones de ./main.js que hacen los chunks cuando estos se cargan; consulta Alojamiento propio.
• Las mismas reglas de React se aplican a los atributos y los eventos. Para TypeScript, agrega el archivo de declaraciones de TypeScript.
• Para pasar por initial-data datos preparados en el servidor, consulta Next.js en SSR y datos iniciales.

Otros frameworks

• Nuxt, SvelteKit y Angular SSR: consulta SSR y datos iniciales, con recetas para Nuxt, SvelteKit y Angular SSR. La regla para cualquier framework con SSR es cargar main.js solo en el navegador (Carga solo en el cliente).
• Otros frameworks renderizados en el cliente: importa el paquete con tu bundler, o agrega a tu HTML las etiquetas de la CDN o del alojamiento propio. Pasa atributos en kebab-case con valores de texto, y agrega los listeners al propio elemento, porque sus eventos no se propagan a los elementos padre (no hacen bubbling) (Escuchar eventos).
• HTML renderizado en el servidor sin un framework de JavaScript (PHP, Rails, Django, temas de CMS): el fragmento de la CDN o del alojamiento propio funciona tal cual.