Instalar un tema y cargar su contenido de ejemplo

Un tema es el escaparate: lo que ve el cliente. El panel y la tienda van por separado, así que cambiar de tema no toca tus productos ni tus pedidos.

Instalarlo

Hay dos maneras.

Subiendo su .zip. Panel → Temas → Instalar tema, y eliges el archivo. Todavía no se instala nada: el paquete se descomprime en una carpeta de cuarentena y primero se te enseña un informe —

• La firma: firmado por quién, sin firmar, o «La firma no es válida» (el paquete cambió después de publicarse, y no se instala). Uno sin firmar se instala, con aviso; con THEMES_EXIGIR_FIRMA=1 solo se instalan los firmados por una clave de tu lista de confianza.
• Qué se ejecutaría: las órdenes de instalar, construir y arrancar. Las decide el sistema a partir del tipo de tema, no las escribe el tema.
• El contrato y la revisión: errores y avisos del theme.json, lo que impide instalar, lo que conviene mirar y los dominios con los que habla.

Solo si nada lo impide puedes pulsar Instalar. Si ya hay un tema con el mismo id, se te ofrece Reemplazar el instalado; tu personalización se guarda aparte y no se pierde.

El paquete tiene límites, y pasarse de cualquiera lo rechaza: 100 MB el .zip, 400 MB descomprimido y 20.000 ficheros. Un fichero que intenta escribir fuera de su carpeta también se rechaza.

Copiando la carpeta. Copia la carpeta del tema dentro de themes/. El panel lee esa carpeta del disco: en cuanto tenga un theme.json válido, aparece en Panel → Temas. Así no hay informe: te fías de lo que has copiado.

Si tus temas viven en otro sitio, dilo con THEMES_DIR en el .env. Lo leen el panel y el backend, así que los dos tienen que apuntar a la misma carpeta: en Docker es /app/themes.

Cada tema declara en su theme.json qué stack usa (Next, Astro, Vite, Nuxt…), qué páginas trae y qué variables de entorno necesita. Eso es el contrato de tema, y es lo que permite que convivan temas de tecnologías distintas en el mismo catálogo.

Cargar su contenido de ejemplo

Solo para una tienda recién instalada. El contenido de ejemplo sirve para probar un tema en una tienda vacía, no para meter productos de muestra en una tienda que ya vende.

La ficha del tema tiene un botón Añadir su contenido de ejemplo. Te enseña lo que trae antes de meterlo —cuántos productos, cuántas categorías y si el contenido es válido— y Añadir a mi catálogo lo importa.

Se rechaza (con un 409 y el motivo) en cuanto la tienda tiene un solo producto propio —uno que no vino de un ejemplo— o un solo pedido. Y cuando eso pasa la tienda queda marcada como en uso, para siempre: borrar después esos productos no la vuelve a dejar recién instalada.

Al importar:

• No borra nada. Lo que ya tenías se queda.

• Es idempotente. Si ya existe un producto con el mismo identificador, se actualiza en vez de duplicarse. Puedes importar dos veces sin miedo.

• Va al primer canal de venta que exista en la tienda (el más antiguo). No a un canal propio del tema.

• No te da ninguna clave publicable. La clave que necesita tu tema es la de la tienda, la que se creó al instalar:

  docker compose exec backend cat /app/data/clave-publicable.txt

  Ponla en el .env del tema (COMMERCE_KEY, o VITE_… / NEXT_PUBLIC_… según el stack): sin esa clave su web no ve ni un producto, y el error no dice que falte una clave.

La ventana de importar todavía habla de «un canal de venta propio del tema» y de una clave que copiar. Ese texto está desfasado: lo que pasa es lo que se cuenta aquí.

Activarlo

Activar solo cambia cuál es el tema activo: es el que el panel personaliza a partir de ahí. No cambia la web pública, y no construye ni arranca nada.

Publicarlo: lo que ve el cliente

El escaparate es una aplicación aparte. Para poner un tema delante de los clientes, la ficha del tema tiene Publicar, que abre una ventana con estos botones:

• Publicar — instala sus dependencias, lo construye, lo arranca en un puerto libre y comprueba que responde. Solo si responde se conmuta; si algo falla por el camino, lo que hay ahora sigue sirviendo. Un tema que se vende con licencia y no la tiene válida se rechaza aquí.
• Probar sin publicar — la misma construcción, dejada como borrador. Con el enrutador en marcha, te da un enlace de vista previa (?vista=<token>) que funciona en el dominio público y caduca a las 48 horas. Sin enrutador, te da http://localhost:<puerto>, y nada más.
• Volver a la anterior — vuelve a poner la publicación anterior. Solo aparece cuando la hay, y necesita el enrutador.
• Parar — para un borrador que está corriendo y libera su puerto.

El enrutador

El enrutador es un pequeño proxy que escucha en el puerto público (THEMES_PUERTO_PUBLICO, 3000 por defecto) y reenvía a la versión que esté publicada. Es lo que hace que conmutar no deje la tienda sin servicio, y lo que hace posibles los borradores y volver atrás:

cd apps/admin && npm run enrutador

Sin él, publicar tiene que parar el proceso anterior antes de arrancar el nuevo —unos segundos sin servicio— y Volver a la anterior se rechaza.

🔴 docker-compose.full.yml no arranca el enrutador. Ninguno de los ficheros de compose lo hace. Si lo quieres, lo arrancas tú.

Personalizarlo

Personalizar abre el editor: colores, tipografías, textos y bloques de la portada, según lo que el tema declare en su settings.schema.json. Se guarda por tienda, así que actualizar el tema no pisa tu configuración.

Cuando algo no cuadra

«0 productos» en la web → falta la clave publicable en el .env del tema, o apunta a un canal de venta que no es donde están los productos.

El contenido de ejemplo no se importa → la tienda ya no está recién instalada: tiene productos propios o pedidos. El panel dice cuál de las dos.

«Este tema no trae contenido de ejemplo.» → no tiene demo/contenido.json. No es un error, simplemente no lo trae.

Volver a la anterior se rechaza → el enrutador no está en marcha.

Ver también

• Contrato de tema — lo que tiene que cumplir un tema
• Seguridad de los temas — el riesgo de instalar uno de terceros
• Crear un tema