Añade un agente de voz con IA a una app de Qwik (guía 2026)

Cómo añadir AnveVoice a una app de Qwik

En un proyecto de Qwik, el head del documento se escribe en src/root.tsx. Añade la etiqueta de script de AnveVoice dentro de ese elemento head y todas las rutas se servirán con ella. Cárgala como un script async normal y deja Partytown fuera. Pasos comprobados con la documentación oficial el 2026-10-14.

En resumen

• Dónde va el código: El elemento head en src/root.tsx
• Programación necesaria: Una línea de JSX
• Límites del plan: Ninguno por parte de Qwik. El plan Free de AnveVoice es suficiente
• Tiempo: Unos 3 minutos más una compilación

Dónde escribe Qwik el head

La referencia de estructura de proyectos de Qwik describe src/root.tsx como la raíz del árbol de la aplicación, el punto de entrada y el primer componente que se renderiza. En el starter generado, root.tsx contiene los elementos head y body del documento alrededor del outlet del router, por eso una etiqueta colocada en ese head aparece en todas las páginas. Existen dos generaciones en paralelo. Las versiones estables publicadas como @builder.io/qwik y create-qwik 1.x usan Qwik City, y las versiones candidatas de la 2.0 usan @qwik.dev/core con Qwik Router. La edición es la misma en ambas: root.tsx, dentro de head. Revisa tu package.json para ver qué nombres usas.

• 1. Copia la etiqueta de instalación — Crea un bot en app.anvevoice.app y sustituye su ID de incrustación. Opciones: &position=bottom-left, &theme=dark. <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script>

Método 1: editar src/root.tsx

Crea una app con npm create qwik@latest (existen variantes con pnpm, yarn y bun), elige el starter vacío o básico, y abre src/root.tsx. El código siguiente muestra la estructura de Qwik 1.x. En Qwik 2, el archivo raíz importa DocumentHeadTags, RouterOutlet y useQwikRouter desde @qwik.dev/router, y el head contiene DocumentHeadTags. Añade el elemento script junto a él, en el mismo head.

• 1. Abre root.tsx y localiza el head — Dentro de QwikCityProvider (v1) o del fragmento devuelto después de useQwikRouter (v2), localiza el elemento head. En v1 contiene una metaetiqueta charset, un enlace a manifest y el componente RouterHead.
• 2. Añade el script después de RouterHead — Conserva los hijos existentes y añade un elemento script al final del head. Es una etiqueta JSX simple con el atributo async. import { component$, isDev } from "@builder.io/qwik"; import { QwikCityProvider, RouterOutlet } from "@builder.io/qwik-city"; import { RouterHead } from "./components/router-head/router-head"; import "./global.css"; export default component$(() => { return ( <QwikCityProvider> <head> <meta charset="utf-8" /> {!isDev && ( <link rel="manifest" href={`${import.meta.env.BASE_URL}manifest.json`} /> )} <RouterHead /> <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async /> </head> <body lang="en"> <RouterOutlet /> </body> </QwikCityProvider> ); });
• 3. Previsualiza una compilación de producción — La guía de primeros pasos de Qwik indica que el comando preview crea una compilación de producción y la sirve en localhost:4173. El modo de desarrollo (npm run start) también funciona, pero preview muestra lo que recibirán los visitantes.

Omite Partytown para esta etiqueta

La página de integración de Partytown de Qwik muestra scripts de terceros colocados en el head con type="text/partytown" para que se ejecuten en un web worker, y dice que el comando qwik add partytown configura la integración. Eso encaja bien con analítica y gestores de etiquetas que solo leen y envían datos. AnveVoice dibuja un botón, abre un panel y usa el micrófono y la salida de audio, cosas que pertenecen al hilo principal de la página. No lo hemos probado bajo Partytown, así que cárgalo como un script async normal, tal como se muestra arriba, en lugar de añadir el tipo partytown.

Reanudabilidad y navegación

• Qwik renderiza las páginas en el servidor y se reanuda en el navegador en lugar de hidratarse. Una etiqueta script simple en el head es solo HTML, así que se carga como lo haría en cualquier página estática y no aumenta la cantidad de JavaScript que Qwik tiene que reanudar.
• La navegación entre rutas la gestiona el router sin recargar el documento, así que el agente de voz se carga una vez por cada carga completa de la página.
• La salida estática de un adaptador (SSG) incluye el head de root.tsx en cada página generada.
• El directorio public se copia a dist durante la compilación y se sirve desde la raíz, pero no contiene tu plantilla de página. Edita root.tsx, no los archivos de public.

Comprueba que funciona

• 1. Compila y previsualiza — Ejecuta el comando preview y abre la dirección que muestra en una ventana privada. Se requiere HTTPS para el acceso al micrófono en un sitio desplegado.
• 2. Ve el código fuente — Usa View Source (Ver código fuente) y busca anvevoice.app. Debería aparecer en el head del HTML sin procesar.
• 3. Prueba el botón — Haz clic en el botón redondo del micrófono abajo a la derecha, permite el micrófono y di una pregunta.

Problemas comunes

• El script no aparece en la página: la etiqueta se añadió a un componente de ruta, donde se renderiza en el body y puede no ejecutarse. Colócala en el head de root.tsx.
• El botón no aparece en desarrollo: reinicia el servidor de desarrollo tras editar root.tsx y haz una recarga forzada.
• Dos botones: existen una copia de Partytown y otra normal. Elimina la que tiene type="text/partytown".
• El edge o el CDN devuelve páginas antiguas: purga el HTML en caché después de desplegar la nueva compilación.

Fuentes

• Documentación de Qwik: estructura del proyecto (src/root.tsx, public) (https://qwik.dev/docs/project-structure/) — consultado el 2026-10-14
• Documentación de Qwik: primeros pasos (create-qwik, preview) (https://qwik.dev/docs/getting-started/) — consultado el 2026-10-14
• Documentación de Qwik: integración de Partytown (https://qwik.dev/docs/integrations/partytown/) — consultado el 2026-10-14

Relacionado

• Cómo añadir AnveVoice a una aplicación de SolidStart
• Cómo añadir AnveVoice a una app de React
• Cómo añadir AnveVoice a un sitio de Astro
• Cómo añadir AnveVoice a un sitio web HTML sencillo

Prueba AnveVoice en tu sitio

Plan gratuito: 0 US$, 50.000 tokens al mes, sin tarjeta. Obtén tu ID de inserción en el panel y pega una etiqueta.