Skip to content

Preparar tu build de página personalizada ​

Esta página explica cómo preparar un build que funcione a la primera. Lee la regla de oro de abajo: es lo que más confunde a la gente. Si creas tu página con una herramienta de IA, ve directo a Usa IA para crearla y copia el prompt.

La regla de oro: compila para la ruta base ​

Tu Página personalizada se sirve desde una subcarpeta de tu dominio, no desde la raíz:

https://tudominio.com/c/tu-slug/

Por eso, cada recurso que carga tu página (CSS, JavaScript, imágenes, fuentes) debe resolverse bajo esa subcarpeta. Si tu build referencia recursos desde la raíz del dominio (una barra inicial, como /assets/app.js), el navegador los buscará en https://tudominio.com/assets/app.js (que no existe) y tu página cargará en blanco o sin estilos.

La solución es un solo ajuste: dile a tu herramienta de compilación que su ruta base (también llamada public path, homepage o base href) es /c/tu-slug/. Incluso lo verificamos por ti al subir y rechazamos un build cuyos recursos apunten al lugar equivocado, con un mensaje que te dice exactamente qué cambiar.

Paso 1: Crea la página primero para obtener tu slug ​

  1. Crea la Página personalizada (nombre interno + dominio + slug) y guarda.
  2. En el formulario verás tu Ruta base del build exacta: /c/tu-slug/. Cópiala.
  3. Tu slug se bloquea tras la primera subida, así que esta ruta es estable: solo la defines una vez.

Paso 2: Define la ruta base en tu herramienta ​

Usa la que corresponda a tu stack (reemplaza tu-slug):

  • Vite: en vite.config.js:
    js
    export default { base: '/c/tu-slug/' }
  • Create React App: en package.json:
    json
    { "homepage": "/c/tu-slug/" }
  • Astro: en astro.config.mjs:
    js
    export default { base: '/c/tu-slug/' }
  • VitePress: en .vitepress/config (¿estás creando un sitio de documentación? ver Sitios de documentación más abajo):
    js
    export default { base: '/c/tu-slug/' }
  • Next.js (exportación estática): en next.config.js, luego ejecuta next build && next export:
    js
    module.exports = { basePath: '/c/tu-slug', assetPrefix: '/c/tu-slug/', output: 'export' }
  • HTML simple: referencia cada recurso con una ruta relativa (assets/app.js, no /assets/app.js), o agrega una etiqueta base al inicio del <head>:
    html
    <base href="/c/tu-slug/">

¿Ya compilaste sin esto? Solo define la ruta base y vuelve a compilar: no se arregla editando el zip.

Paso 3: Compila y comprime ​

  1. Ejecuta tu build (produce una carpeta, normalmente dist/ o build/).
  2. Comprime el contenido de esa carpeta, con tu documento de entrada (index.html) arriba. Una sola carpeta envolvente (como dist/) está bien: la detectamos y la quitamos automáticamente.
  3. Sube el .zip en el formulario de la Página personalizada. Lo validamos, extraemos y publicamos, y te avisamos cuando está en vivo.

Paso 4: Declara tus incrustaciones y servicios externos (si los hay) ​

Si tu página usa analíticas, un widget de reservas o formularios, un video incrustado, o llama a cualquier API desde el navegador, declara esos servicios en Incrustaciones y dominios externos en el formulario de la Página personalizada: de lo contrario cargarán pero no harán nada. Consulta Incrustaciones, analíticas y servicios externos más abajo para ver cómo funciona. Puedes editar esta lista en cualquier momento sin volver a subir tu build. Una página totalmente autocontenida se salta este paso.

Lo que debe contener tu build ​

  • Un documento de entrada en la raíz: index.html por defecto. Si el tuyo tiene otro nombre, ajusta el campo Archivo de entrada del formulario (un error común es indext.html en vez de index.html).
  • Recursos referenciados bajo la ruta base o de forma relativa: nunca desde la raíz del dominio.
  • Solo archivos estáticos: HTML, CSS, JS, JSON, imágenes (PNG/JPG/WebP/SVG/GIF/AVIF/ICO), fuentes (WOFF/WOFF2/TTF/OTF) y medios (MP4/WebM/MP3). Sin código del lado del servidor.
  • Un tamaño razonable: mantenlo ligero; los medios pesados sin optimizar son la razón habitual de que un build sea demasiado grande.

El sandbox de seguridad: compila dentro de él ​

Las Páginas personalizadas se ejecutan dentro de un sandbox de seguridad del navegador (para que los archivos subidos no confiables nunca alcancen los datos de otras páginas). Compila teniendo en cuenta estas restricciones; una página que las ignore cargará, pero algunas partes no funcionarán:

  • Sin almacenamiento del navegador: cookies, localStorage, sessionStorage e IndexedDB no están disponibles (la página se ejecuta en un origen aislado). No dependas de ellos para banners de consentimiento, carritos, "recuérdame", etc.
  • Sin eval() / new Function(): usa un bundle moderno; evita bibliotecas que hacen eval en tiempo de ejecución.
  • Sin llamadas del lado del cliente a APIs de terceros por defecto: fetch/XHR/WebSocket a otros orígenes están bloqueados a menos que declares el servicio en Incrustaciones y dominios externos (ver abajo). De lo contrario, renderiza el contenido en tiempo de compilación en lugar de obtenerlo en tiempo de ejecución.
  • Permitido: JS/CSS en línea y empaquetado, scripts de módulo (<script type="module">, cualquier build de Vite o Astro), fuentes web alojadas por ti, fetch() en tiempo de ejecución de los archivos propios de tu página (por ejemplo un data.json que incluiste), fuentes/imágenes/hojas de estilo/bibliotecas de JS externas por https, formularios que se envían (POST) a un servicio externo, enlaces en la misma pestaña y en nueva pestaña, y descargas.

Páginas privadas: un paso extra para las fuentes y los scripts de módulo. Por la forma en que los navegadores solicitan las fuentes web y los scripts de módulo, esas peticiones no pueden llevar las credenciales de acceso de tu página, así que en una página privada no cargan, y la página se ve sin estilos o inerte. Activa «Permitir que carguen las fuentes y los scripts de módulo» en el formulario de la Página personalizada para solucionarlo. Lee primero la advertencia que aparece ahí: sirve tus archivos de fuentes y .js sin la verificación de acceso, así que cualquiera que conozca una de esas URL podrá leerla, y los archivos .js de un build normalmente contienen el texto y la maquetación de tu página. Tu documento de entrada y los archivos de datos .json siguen protegidos en ambos casos. Para una página realmente confidencial, déjalo desactivado y haz que tu build incruste las fuentes directamente en el CSS. Las páginas públicas no necesitan nada: todo funciona sin más.

Incrustaciones, analíticas y servicios externos ​

¿Necesitas analíticas, un widget de reservas o un servicio de formularios que envía por JavaScript? Abre Incrustaciones y dominios externos en el formulario de la Página personalizada y declara lo que tu página usa:

  • Proveedores conocidos: elige servicios como Google Analytics, Calendly, Tally, HubSpot o YouTube de la lista; nosotros mantenemos los dominios que cada uno necesita.
  • Dominios personalizados: agrega cualquier otro hostname al que tu página llame (p. ej. api.tuservicio.com). Un *. inicial cubre los subdominios.

Dos cosas que debes saber:

  • Declarar algo cambia la página a modo gobernado: a partir de ahí solo puede llamar APIs, incrustar iframes y enviar formularios a sí misma y a los dominios declarados. Así que si declaras tus analíticas, declara también tu servicio de formularios y cualquier iframe incrustado: todo lo externo que tu página toca va en la lista. Si no declaras nada, la página conserva las reglas por defecto de arriba.
  • Los dominios declarados cubren los scripts propios de tu página (beacons de analíticas, envíos de formularios por JS, tu propia API). Las incrustaciones por iframe y los widgets que usan cookies (YouTube, Google Calendar, Tally, reCAPTCHA, checkouts incrustados) no funcionan bajo el sandbox, declares los dominios que declares: el navegador lo extiende a cada iframe. Publica la página Aislada para ellos (ver «Publicación: Aislada o Clásica» en Páginas personalizadas); ahí se ejecuta en su propia dirección y sin sandbox.

Aplicaciones de una sola página y formularios ​

  • ¿Enrutamiento del lado del cliente? Activa Aplicación de una sola página (SPA) en el formulario para que los enlaces profundos y los refrescos sirvan tu documento de entrada. (El enrutamiento que lee de la URL está bien; recuerda que las llamadas a APIs en tiempo de ejecución están bloqueadas, ver las reglas del sandbox arriba.)
  • ¿Tienes un formulario? Apúntalo a tu propia API o a un servicio de terceros (p. ej. Formspree) con un method="POST" normal. Aquí no hay servidor que reciba envíos, y el envío por fetch está bloqueado: usa un envío de formulario clásico.

Sitios de documentación (VitePress y similares) ​

Los generadores estáticos de documentación, como VitePress, Astro Starlight, Docusaurus (build estático) y similares, funcionan como Páginas personalizadas. Algunos detalles además de los pasos anteriores:

  • Define la ruta base exactamente como en el Paso 2 (VitePress: base: '/c/tu-slug/' en .vitepress/config).
  • Las URLs «limpias» funcionan de ambas formas. Tanto los enlaces que terminan en .html (el modo por defecto de VitePress) como los enlaces sin extensión (cleanUrls: true) se resuelven, cuando un enlace no tiene extensión, servimos automáticamente la página .html correspondiente, y un enlace a una carpeta redirige a su índice (en la publicación Clásica; en una página Aislada, enlaza las carpetas con barra final, como hace VitePress). No necesitas el modo SPA para un sitio de documentación.
  • Quita los archivos del proveedor de hosting antes de comprimir. Los archivos sin extensión (como _headers o _redirects de Netlify/Cloudflare) no son recursos web estáticos y hacen que falle toda la subida. Comprime solo los archivos propios del sitio.
  • La preferencia de tema claro/oscuro no se guarda. El sandbox de seguridad no tiene almacenamiento del navegador, así que el interruptor de tema funciona mientras lees pero se reinicia en la siguiente visita. Es cosmético y esperado: no hay nada que corregir en tu build.
  • Búsqueda: la búsqueda local integrada del generador funciona sin más. Un servicio de búsqueda alojado (p. ej. Algolia DocSearch) llama a una API de terceros: decláralo en Incrustaciones y dominios externos.
  • La documentación confidencial no va en una página privada con el interruptor de fuentes y scripts. Un generador de documentación empaqueta el texto completo de cada página en sus archivos .js, así que en una página privada el interruptor descrito arriba deja tu contenido legible para cualquiera que conozca las URLs. Si tu documentación es realmente confidencial, mantenla fuera de las Páginas personalizadas por ahora.

Usa IA para crearla ​

Si generas tu página con una herramienta de IA (o un asistente de código), pega este prompt y reemplaza tu-slug por el slug de tu página. Le indica a la IA todo lo necesario para producir un build que se suba sin problemas:

text
Build me a self-contained STATIC website that will be hosted at the sub-path "/c/tu-slug/" (NOT the domain root) and served inside a browser security SANDBOX (isolated/opaque origin). Follow these rules exactly.

ASSET ROUTING
1. Entry document: produce index.html at the ROOT of the build output.
2. Base path: configure the build's base / public path / homepage to "/c/tu-slug/" so every asset (CSS, JS, images, fonts) is referenced under that prefix.
   - Vite: set base: "/c/tu-slug/" in vite.config.
   - Create React App: set "homepage": "/c/tu-slug/" in package.json.
   - Astro: set base: "/c/tu-slug/".
   - VitePress: set base: "/c/tu-slug/" in .vitepress/config.
   - Next.js: set basePath and assetPrefix to "/c/tu-slug/" and use static export (output: "export").
   - Plain HTML: use relative asset paths (e.g. "assets/app.js"), or add <base href="/c/tu-slug/"> in <head>.
3. NEVER reference an asset from the domain root with a leading slash (e.g. "/assets/...", "/favicon.ico"). Use the base path or relative paths only.

FILE TYPES
4. Use only static files: html, css, js, json, images (png/jpg/jpeg/webp/svg/gif/avif/ico), fonts (woff/woff2/ttf/otf), media (mp4/webm/mp3). No server-side code (no PHP, Node endpoints, APIs).

SANDBOX CONSTRAINTS (the page runs in an isolated origin: ignoring these makes features silently fail)
5. Do NOT use cookies, localStorage, sessionStorage or IndexedDB: browser storage is unavailable. Don't build cookie-consent persistence, carts, or "remember me".
6. Do NOT use eval() or new Function(); use a modern build that does not eval at runtime.
7. Third-party APIs (fetch / XHR / WebSocket) and iframe embeds only work for domains I explicitly allow in the hosting platform. List every external domain the page calls or embeds (analytics endpoints, form APIs, widget iframes) at the end of your answer so I can allow them. When in doubt, render data at build time instead of fetching at runtime.
8. Forms must submit to an external service (e.g. Formspree): a plain <form method="POST" action="https://..."> always works; fetch-based submission works only if the service's domain is on my allowed list (include it in the domain list from rule 7). There is no backend here.
8b. Iframe embeds (YouTube, calendars, form widgets) and anything needing cookies or storage inside the page only work when the hosting platform serves the page "Isolated" (its own origin, no sandbox). If the page uses any of these, say so explicitly at the end of your answer (next to the domain list from rule 7) so I can choose that mode.
9. Allowed: inline and bundled JS/CSS; external fonts/images/stylesheets/JS libraries loaded over HTTPS from their own CDNs; same-tab and new-tab links; downloads.

OUTPUT
10. Keep the build small (ideally under ~50 MB zipped); optimize images and avoid huge media.
11. If it uses client-side routing, ensure deep links work by serving index.html for unknown routes (I will enable "Single-page app" mode on upload).

Deliver the final build folder, ready to zip (with index.html at its root) and upload.

El prompt se deja en inglés a propósito para obtener los mejores resultados con la mayoría de las herramientas de IA; solo reemplaza tu-slug.

Solución de problemas ​

  • La página carga en blanco o sin estilos → la ruta base no está definida. Vuelve a compilar con base / homepage / <base href> = /c/tu-slug/.
  • "Al build le falta su documento de entrada" → no hay index.html en la raíz del zip, o está mal nombrado. Corrige el nombre (o ajusta el campo Archivo de entrada) y vuelve a comprimir.
  • "Tipo de archivo no permitido" → quita cualquier archivo del lado del servidor o ejecutable, y cualquier archivo del proveedor de hosting sin extensión (_headers, _redirects); deja solo recursos web estáticos.
  • Los enlaces profundos o el refresco muestran "no encontrado" → para una aplicación con enrutamiento del lado del cliente, activa el modo Aplicación de una sola página (SPA). (Los enlaces sin .html de un sitio de documentación se resuelven automáticamente: no necesitas el modo SPA.)
  • El interruptor de tema claro/oscuro no se guarda entre visitas → es lo esperado: el sandbox no tiene almacenamiento del navegador donde recordarlo. No hay nada que corregir.
  • "Los recursos apuntan a la raíz del dominio" → tu build aún usa rutas con barra inicial; define la ruta base y vuelve a compilar.
  • Un widget o las analíticas cargan pero no hacen nada → sus llamadas a la API están bloqueadas. Declara el servicio en Incrustaciones y dominios externos, y recuerda que en cuanto declaras algo, todo dominio externo al que la página llame, incruste o envíe formularios debe estar en la lista.
  • Una incrustación por iframe (YouTube, Google Calendar, Tally, reCAPTCHA, un checkout incrustado) muestra errores o queda en blanco → los widgets incrustados no pueden ejecutarse dentro del sandbox. Publica la página Aislada.
  • ¿Cambiaste la configuración de incrustaciones y no pasó nada? → recarga forzada: el navegador cachea los archivos de las páginas públicas hasta por 5 minutos.

Con Claude ​

Con el conector de Claude, Claude puede crear el sitio contigo y subir el resultado como una versión de tu Custom Page, siguiendo esta guía (ruta base, sin solicitudes externas, el entorno aislado).

  • Permisos de la conexión: Crear y editar páginas personalizadas para subir a una página privada; Hacer públicas las páginas personalizadas para una pública.
  • Se aplica al instante: subir a una página pública y activar la versión la publica.

Prueba a pedir:

  • "Crea un sitio Astro de una página para nuestro evento con base /c/evento/ y súbelo a la Custom Page del evento."
  • "Mi versión muestra una página en blanco después de subirla: revísala con las reglas de Custom Pages."