CSS y JavaScript personalizados en PrestaShop sin romper las actualizaciones

Actualizado en junio de 2026, los cuatro métodos seguros frente a actualizaciones que explicamos abajo se aplican desde PrestaShop 1.7 hasta PrestaShop 9 (incluida la canalización SCSS de Hummingbird). Los ejemplos de código usan la API register* de recursos de PrestaShop 1.7+.

Cambias el color de un botón. Abres la hoja de estilos del tema, la editas y el botón queda como querías. Tres semanas después actualizas el tema para aplicar un parche de seguridad, y tu cambio desaparece: sobrescrito en silencio, sin aviso y sin ningún registro de lo que habías tocado. Todo comerciante de PrestaShop que personaliza editando archivos del núcleo acaba chocando con este muro, y lo frustrante es que se puede evitar por completo. La plataforma te ofrece varios lugares seguros frente a actualizaciones donde colocar CSS y JavaScript personalizados; la clave está en saber cuál encaja con el cambio que vas a hacer y por qué eso de "editar el tema directamente" suele fallar sin hacer ruido. Esta guía trata exactamente de eso: dónde puede vivir tu código personalizado para que una actualización del tema, del núcleo o de un módulo nunca lo borre.

Por qué editar archivos del tema y de los módulos es una trampa

Un tema de PrestaShop es un conjunto de archivos en disco: plantillas Smarty (.tpl), hojas de estilos y JavaScript, todos dentro de /themes/your-theme/. Cuando actualizas ese tema, ya sea subiendo de nuevo un ZIP más reciente o aplicando un parche del proveedor, el proceso de actualización sustituye esos archivos por completo por la nueva versión. No fusiona tus cambios: los sobrescribe. Lo mismo ocurre con cualquier módulo: sus recursos están en /modules/module-name/views/, y una actualización del módulo sustituye ese directorio entero. No hay diff, no hay aviso, no hay copia de seguridad. Tu trabajo simplemente desaparece y, como no se produce ningún error, a menudo no te das cuenta hasta que lo detecta un cliente.

¿Qué significa eso para ti? Cada hora dedicada a editar archivos del núcleo es una hora que volverás a invertir en la siguiente actualización; y "la siguiente actualización" no es opcional, porque así llegan a tu tienda las correcciones de seguridad y de errores. El objetivo de los métodos siguientes es romper ese ciclo: escribir tu personalización una sola vez, en un lugar que el actualizador no toque nunca, y dejar de rehacer trabajo perdido.

Elige el método según el cambio

No existe una única forma "correcta" de añadir código personalizado: existe una forma correcta para tu cambio. Un ajuste de color de una línea y una renovación visual completa pertenecen a sitios totalmente distintos. Elige el método más ligero que sobreviva a las actualizaciones y resuelva lo que necesitas:

Las secciones siguientes cubren cada método con detalle específico de PrestaShop. Dos de ellos tocan temas que ya tienen sus propias guías dedicadas, los temas hijo y los bloques HTML del back office, , así que, en lugar de repetir aquí toda esa profundidad, este artículo se centra en lo que comparten los cuatro: mantener tu código a salvo de las actualizaciones.

Método 1, el archivo custom.css (para pequeños ajustes CSS)

La mayoría de los temas modernos de PrestaShop incluyen un archivo custom.css vacío que el tema carga después de todas las demás hojas de estilos. Como se carga al final, tus reglas ganan la cascada de forma natural, lo que lo convierte en un lugar cómodo para algunos ajustes rápidos. Eso sí: ten en cuenta que custom.css suele vivir dentro del árbol del tema, por lo que no es seguro frente a actualizaciones por sí mismo; un ZIP del tema o una actualización del proveedor puede sustituirlo. Para una seguridad real frente a actualizaciones, coloca tus reglas en un tema hijo o en un bloque de código del back office; reserva el custom.css propio del tema para cambios de color, espaciado o tipografía prescindibles que puedas volver a aplicar sin demasiado coste.

Muchos temas, incluidos los temas de estilo Classic (Classic es el tema predeterminado de PrestaShop 8), cargan /themes/your-theme/assets/css/custom.css; el tema más reciente Hummingbird es otra opción moderna. Pero el soporte de custom.css y su ruta exacta dependen del tema, así que no lo des por sentado como comportamiento nativo universal: algunos temas antiguos o comerciales usan /themes/your-theme/css/custom.css en su lugar, y una minoría no lo conecta en absoluto. Verifica el registro de recursos o la documentación del tema activo, y busca un custom.css existente (a menudo vacío) antes de crear el tuyo. Añade tus reglas, por ejemplo una sobrescritura del botón principal como .btn-primary { background-color: #2c3e50; border-color: #2c3e50; }, limpia la caché y listo.

Conoce sus límites antes de apoyarte demasiado en él. custom.css es solo CSS: no JavaScript. Se carga en todas las páginas, haga falta esa regla allí o no, y no te da forma de apuntar a un tipo de página, grupo de clientes o tienda concretos. Además, una minoría de temas no lo conecta en absoluto. Para unos pocos ajustes, esos límites no importan; en cuanto empiecen a pesar, sube a uno de los métodos siguientes.

Método 2, un tema hijo (para personalización intensa y continua)

Cuando vas a hacer más que unos pocos cambios, editar plantillas, rediseñar secciones enteras, añadir tu propio JavaScript, , un tema hijo es el hogar seguro frente a actualizaciones para todo ello. Un tema hijo hereda todo de su tema padre y te permite sobrescribir solo los archivos concretos que te interesan, en un directorio separado al que las actualizaciones del padre no pueden llegar. Apuntas un config/theme.yml al padre (con la clave parent: indicando el nombre de la carpeta del tema padre), copias solo los archivos que vas a sobrescribir y añades tus propios custom.css y .js junto a ellos.

Esta es la respuesta correcta para personalizaciones serias, y merece un tratamiento propio en vez de un párrafo apresurado, incluida la razón crucial por la que se crea uno en lugar de editar directamente el tema padre. Lo explicamos a fondo en temas hijo en PrestaShop: por qué nunca deberías editar el tema padre. Si todavía no has elegido el tema que vas a personalizar, empieza un paso antes con cómo elegir el tema de PrestaShop adecuado para tu negocio: un tema padre preparado para temas hijo te ahorrará muchos problemas después.

Método 3, inyectar código desde el back office (sin acceso a archivos)

Los bloques del back office mantienen pequeños fragmentos de HTML, CSS y JavaScript fuera de los archivos del tema.

Si no tienes acceso por SSH o FTP, no lo quieres, o simplemente no quieres redesplegar archivos por un snippet de seguimiento de una línea, un módulo de bloques de código te permite añadir CSS, JavaScript y HTML personalizados directamente desde el back office de PrestaShop. El código vive en la base de datos en lugar de en un archivo del tema o de un módulo, y precisamente por eso una actualización del tema o del núcleo no puede tocarlo; también por eso puedes desactivar un bloque para deshacer su efecto al instante, sin borrar nada.

Es la herramienta diaria para añadir un script de Google Analytics o Meta Pixel, insertar una sobrescritura CSS de temporada en la cabecera de la página o colocar un banner promocional, y merece una guía propia más que un párrafo aquí. Lo explicamos paso a paso en bloques HTML: añadir contenido personalizado en cualquier lugar de tu tienda PrestaShop, donde cubrimos cómo asignar bloques a hooks y mostrarlos solo en las páginas o grupos de clientes que elijas. Nuestro propio módulo mprhtmlblocks está pensado exactamente para eso: código personalizado, gestionado desde el back office, dirigido a hooks y mostrado de forma condicional, sin nada que la próxima actualización pueda sobrescribir.

Método 4, un pequeño módulo personalizado con hooks de recursos (para desarrolladores)

Para desarrolladores, el hogar más limpio y controlable para recursos personalizados es un módulo muy pequeño que los registre mediante la propia canalización de recursos de PrestaShop. Es completamente independiente del tema, no hay nada dentro del árbol del tema que sobrescribir, , así que sobrevive tanto a cambios de tema como a actualizaciones del núcleo, y además desbloquea una carga condicional que custom.css no puede ofrecer.

El trabajo ocurre en un único hook, hookActionFrontControllerSetMedia(). Dentro de él llamas a registerStylesheet() y registerJavascript() en el controlador, pasando un id de recurso, la ruta dentro de tu módulo y un array de opciones. Esas opciones son la ventaja frente a las llamadas antiguas de la era 1.6 addCSS() / addJS(): una priority (los números más altos cargan más tarde, que es como garantizas que tu script se ejecute después del del tema), una consulta media, una position JS de bottom y atributos async/defer. En PrestaShop 1.7 y superiores, prefiere los métodos register*; recurre a addCSS/addJS solo cuando mantengas una tienda 1.6.

public function install()
{
    return parent::install()
        && $this->registerHook('actionFrontControllerSetMedia');
}

public function hookActionFrontControllerSetMedia($params)
{
    if (!$this->context->controller instanceof ProductController) {
        return;
    }

    $this->context->controller->registerStylesheet(
        'module-' . $this->name . '-product',
        'modules/' . $this->name . '/views/css/product.css',
        ['media' => 'all', 'priority' => 200]
    );

    $this->context->controller->registerJavascript(
        'module-' . $this->name . '-product',
        'modules/' . $this->name . '/views/js/product.js',
        ['position' => 'bottom', 'priority' => 200]
    );
}

El fallo de addCSS con cadenas de consulta que conviene conocer

Hay una trampa de largo recorrido: addCSS() con una cadena de consulta para romper caché (algo como ?v=1.2.3) puede generar una ruta que PrestaShop manipula mal, de modo que la hoja de estilos aparece en el código fuente de la página pero el navegador nunca la aplica. Es desesperante de depurar porque nada devuelve un 404. Si usas versionado para romper caché en tus recursos, utiliza registerStylesheet(), que gestiona correctamente la versión.

Carga condicional. Solo donde hace falta

La verdadera razón por la que los desarrolladores recurren a un módulo es la carga condicional. Dentro del mismo hook puedes inspeccionar $this->context->controller y registrar recursos solo cuando coincida: por ejemplo, comprobando instanceof ProductController antes de añadir CSS para páginas de producto, o instanceof OrderController antes de añadir JavaScript al proceso de compra. El beneficio es concreto: tu código personalizado queda fuera del 90% de las páginas que no lo necesitan, así que no lo pagas en el tiempo de carga de cada página. Ese mismo principio, cargar poco, cargar tarde, es lo que mantiene rápida una tienda personalizada, y es el espíritu detrás de pequeños detalles de front-end como un botón de volver arriba entregados como recursos condicionales correctos, en lugar de como scripts en línea volcados en una plantilla.

JavaScript necesita más cuidado que CSS

CSS rara vez se defiende; JavaScript sí puede hacerlo. Dos cosas causan la mayoría de los problemas. Primero, jQuery: PrestaShop 1.7+ incluye jQuery 3.x en el front office, así que, si tu script depende de jQuery, dale una prioridad lo bastante alta para que cargue después de jQuery; de lo contrario verás "$ is not defined" en el primer render. El back office es otro mundo (las versiones antiguas llevaban jQuery 1.x, las nuevas 3.x), así que revisa el código fuente de la página antes de escribir scripts de administración suponiendo una versión.

Segundo, y esta es la regla que más cuesta respetar: nunca pongas una etiqueta <script> sin procesar dentro de una plantilla Smarty. Parece rápido, pero un script en línea se salta la gestión de recursos de PrestaShop, CCC (Combine, Compress, Cache) no lo gestionará ni combinará, y puede entrar en conflicto con la Content Security Policy en tiendas que establecen una cabecera CSP. Envía siempre JavaScript como un archivo .js externo registrado mediante el hook adecuado. En cuanto a la sintaxis moderna. Arrow functions, async/await, módulos ES. , Está bien en PrestaShop 8 y 9, donde IE11 ya no es una preocupación; si todavía das soporte a tiendas 1.7 con tráfico de navegadores antiguos, quizá tengas que transpilar con Babel.

Cuando el CSS personalizado "no funciona": especificidad

La situación más común de "mi CSS personalizado se está ignorando" no es un problema de actualización en absoluto: es especificidad. Tu regla carga correctamente, pero el selector del tema es más específico, así que el navegador aplica el del tema. La solución, por orden de preferencia:

• Iguala el selector del tema. Abre las herramientas de desarrollo, encuentra el selector exacto que usa el tema y escribe el tuyo para igualarlo. Como custom.css carga al final, un selector igual de específico ya gana.
• Añade un padre para darle peso. Si igualarlo no basta, delimítalo: #wrapper .btn-primary gana a un .btn-primary aislado sin recurrir a la fuerza bruta.
• Usa !important solo como último recurso real. Funciona, pero cada !important que añades dificulta la siguiente sobrescritura, y acabas en una carrera de especificidad que tu yo del futuro tendrá que desenredar.

Pruebas: por qué "lo he cambiado y no ha pasado nada"

Los cambios de CSS y JS personalizados que parecen no hacer nada casi siempre se deben a una capa de caché, no a tu código. Revisa esto en orden:

• Limpia la caché de PrestaShop. Ve a Parámetros avanzados → Rendimiento y haz clic en Limpiar caché después de cada cambio. Mientras desarrollas plantillas, activa Forzar compilación para que Smarty vuelva a renderizar.
• Vigila CCC. Con Combine, Compress, Cache activado, tus archivos individuales se fusionan en paquetes, lo que puede cambiar el orden de carga. Si algo se comporta raro, desactiva CCC temporalmente para aislarlo y vuelve a activarlo en producción.
• Usa el navegador. La pestaña Red confirma que tu archivo se ha cargado realmente (200, no 404); la pestaña Elementos muestra si tu regla se aplica o queda tachada por otra más específica.
• Purga el CDN. Si usas Cloudflare u otro CDN, púrgalo después de cambiar recursos: las copias antiguas en el borde explican una gran parte de los informes de "pero si ya lo había cambiado".

La versión corta

• Nunca edites directamente archivos del tema o de módulos: la próxima actualización los sobrescribe sin avisar.
• 1-5 pequeños ajustes CSS: colócalos en custom.css.
• Cambios grandes y continuos: crea un tema hijo.
• Sin acceso a archivos, o fragmentos rápidos: usa un bloque HTML/código del back office.
• Desarrollador, carga condicional: un pequeño módulo con registerStylesheet() / registerJavascript().
• Envía el JS como archivos externos, carga al final, limpia todas las cachés después de los cambios y mantén tus personalizaciones respaldadas fuera del directorio del tema.

Personalizar PrestaShop y sobrevivir a las actualizaciones no son objetivos opuestos; solo lo parecen cuando tu código vive en el lugar equivocado. Elige el método más ligero y seguro frente a actualizaciones para el cambio que tienes delante, y una actualización del tema se convierte en lo que debería ser: un clic rutinario, no un día rehaciendo trabajo perdido. Si prefieres gestionar código personalizado desde el back office en vez de tocar archivos, nuestro módulo mprhtmlblocks te permite inyectar y activar o desactivar bloques de HTML, CSS y JavaScript uno a uno: guardados en la base de datos e intactos tras la próxima actualización.

Preguntas frecuentes

¿El archivo custom.css del tema es realmente seguro frente a actualizaciones?

No del todo. Como custom.css suele vivir dentro del árbol del tema, un ZIP del tema o una actualización del proveedor puede sustituirlo junto con todo lo demás. Es cómodo, carga al final, así que tus reglas ganan en la cascada, , pero trátalo como el lugar para ajustes prescindibles que puedes permitirte volver a aplicar. Para una seguridad real frente a actualizaciones, coloca las reglas en un tema hijo o en un bloque de código del back office donde el actualizador no pueda alcanzarlas.

Mi CSS personalizado carga, pero sigue ganando el estilo del tema. ¿Qué falla?

Es un problema de especificidad, no de actualización ni de caché. El selector del tema es más específico que el tuyo, así que el navegador aplica el del tema. Abre las herramientas de desarrollo, encuentra el selector exacto que usa el tema y escribe el tuyo para igualarlo; como custom.css carga al final, un selector equivalente ya gana. Añade un padre de ámbito como #wrapper solo si igualarlo no basta, y recurre a !important únicamente como último recurso real.

¿Puedo simplemente pegar una etiqueta <script> en una plantilla?

No. Un script en línea se salta la gestión de recursos de PrestaShop, así que CCC no lo combinará, y puede fallar en tiendas que establecen una cabecera Content Security Policy. Envía siempre JavaScript como un archivo externo .js registrado mediante hookActionFrontControllerSetMedia() con registerJavascript(), o mediante un bloque de código del back office; nunca como marcado sin procesar en un .tpl.

¿Cómo cargo mi CSS o JS solo en ciertas páginas?

Esa es la razón principal para usar un pequeño módulo en lugar de custom.css. Dentro de hookActionFrontControllerSetMedia(), inspecciona $this->context->controller y registra el asset solo cuando coincida: por ejemplo, instanceof ProductController para CSS de páginas de producto, o instanceof OrderController para JS del proceso de compra. Así tu código queda fuera de las páginas que no lo necesitan, y no lo pagas en cada carga de página.

¿Por qué mi script lanza "$ is not defined"?

Tu JavaScript se está ejecutando antes de que jQuery haya cargado. PrestaShop 1.7+ incluye jQuery 3.x en el front office, así que da a tu script una priority lo bastante alta en registerJavascript() para que cargue después de jQuery. El back office es un mundo aparte, las versiones antiguas llevaban jQuery 1.x, , así que revisa el código fuente de la página antes de escribir scripts de administración suponiendo una versión concreta.

He cambiado mi CSS y no ha pasado nada. ¿Dónde miro?

Casi siempre es una capa de caché, no tu código. Revisa en orden: limpia la caché de PrestaShop en Parámetros avanzados → Rendimiento; desactiva temporalmente CCC (Combine, Compress, Cache) si el orden de carga parece incorrecto; confirma en la pestaña Red del navegador que tu archivo ha cargado con un 200, no con un 404; y purga tu CDN (Cloudflare y similares), porque las copias antiguas en el borde causan una enorme parte de los informes de "pero si ya lo había cambiado".

¿Debería seguir usando addCSS() y addJS()?

Solo en una tienda 1.6. En PrestaShop 1.7 y superiores, prefiere registerStylesheet() y registerJavascript(): te dan prioridad, consultas media, posición inferior para JS y async/defer, además de gestionar correctamente el versionado para romper caché. El antiguo addCSS() tiene un fallo de largo recorrido por el que una cadena de consulta ?v= puede deformar la ruta, de modo que el archivo aparece en el código fuente pero nunca se aplica, sin ningún 404 que te dé la pista.

Guías relacionadas

• Temas hijo en PrestaShop: por qué nunca deberías editar el tema padre
• Bloques HTML: añadir contenido personalizado en cualquier lugar de tu tienda PrestaShop
• Botón de volver arriba: un pequeño detalle de UX que importa más de lo que parece