Edición por @david: El sistema de temas de Discourse ahora tiene soporte integrado para múltiples archivos JS. Este método de webpack ya no es necesario.
¡Hola! Mientras estaba desarrollando mi componente handsfree-discourse, me encontré con algunos problemas relacionados con la gestión de archivos. Mi principal problema era que necesitaba una forma de dividir mi código en varios archivos. El otro problema era que necesitaba incluir bibliotecas de terceros sin tener que pedir a los administradores que habiliten CORS o desencadenen solicitudes HTTP adicionales.
Para resolver estos problemas, creé discourse-webpack, una plantilla para crear rápidamente componentes con muchos archivos JS. Las características incluyen:
- Servidor de desarrollo local con recarga en vivo
- Incluye un script de commit para mantener tu código fuente y el código compilado en ramas separadas.
El resto de este tema explica cómo usarlo y por qué funciona. Literalmente acabo de terminar de probar esto para otros componentes en los que estoy trabajando, así que avísame si tienes algún problema o alguna solicitud específica.
Crea rápidamente componentes con muchos archivos JavaScript para tu comunidad de Discourse, completo con un script de commit para mantener tu código fuente y el código de compilación en ramas separadas para ayudarte a seguir lanzando rápido.
Instalación
Primero, asegúrate de tener NodeJS >= 8 y git instalados localmente en tu máquina. Luego, escribe cada una de las líneas a continuación:
# Descarga este repositorio
git clone https://github.com/browsehandsfree/discourse-webpack
# Entra en el directorio
cd discourse-webpack
# Instala las dependencias
npm install
Luego necesitarás editar lo siguiente en package.json, reemplazando todos nuestros enlaces con los tuyos. Específicamente:
{
name: 'tu-proyecto',
repository: {
url: 'git+https://github.com/usuario/repo'
},
author: '',
bugs: {
url: 'https://github.com/usuario/repo/issues'
},
homepage: 'https://ejemplo.com'
}
Lo más importante de todo, asegúrate de que repository.url sea correcto y que esté precedido por git+. Cuando ejecutes npm run discourse, se hará commit y se enviará a ese repositorio.
También, no olvides configurar tu about.json de Discourse, que se encuentra en /src/discourse/about.json.
Desarrollo
Después de npm install, obtendrás la siguiente estructura de directorios:
discourse-webpack
|- node_modules/ # Dependencias
|- src/ # Los archivos fuente principales
|--|- discourse/ # Archivos de tema de Discourse
|--|--|- common/
|--|--|- desktop/
|--|--|- mobile/
|--|- main.css # La hoja de estilos principal
|--|- main.js # El punto de entrada principal de JavaScript
|--|- sandbox.html # Espacio de pruebas para desarrollo local
|- .gitignore
|- discourse-push.js # Script especial de commit
|- README.md
|- webpack.config.js # Configuración de Webpack
|- yarn.lock
Scripts de línea de comandos
Además, tienes acceso a los siguientes comandos desde la raíz del proyecto:
# Inicia un servidor de desarrollo en localhost:8080
# - Soporta recarga en vivo
# - Utiliza `/src/sandbox.html` para ayudarte a depurar localmente
npm run dev
# Compila tu componente en `/dist`
npm run build
# Compila tu componente en `/dist`
# - Luego hace commit de `/dist` en la rama `discourse`
npm run discourse
Cómo funciona
Una vez que hayas descargado el repositorio e instalado las dependencias, ¡es hora de empezar a desarrollar! Usa npm run dev para iniciar un servidor de recarga en vivo en localhost:8080.
Visitar esa URL cargará el archivo HTML ubicado en /src/sandbox.html. Este archivo no se utiliza realmente dentro de Discourse y solo está aquí para ayudarte a desarrollar tus scripts localmente (fuera del contexto de Discourse).
El punto de entrada principal de webpack es /src/main.js. Desde allí, puedes importar otros scripts y webpack agrupará todo e inyectará los archivos en los siguientes:
/src/sandbox.html/src/discourse/common/body_tag.html
main.js se compila e inyecta automáticamente en sandbox.html, pero se inyecta manualmente en línea con body_tag.html debido al siguiente código:
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Si quisieras inyectar tu script en otra plantilla, como after_header.html, solo tendrías que copiar esa etiqueta script en esa plantilla. Esto te permite mantener el HTML y el JavaScript de esa plantilla separados durante el desarrollo… ¡pero concatenados cuando se implementa!
Compilación
Cuando compiles con npm run build, lo que sucede es:
- Primero,
/src/main.jsy las dependencias se agrupan - Luego, todos los archivos en
/src/discourse/se copian a/dist/ - Al mismo tiempo,
main.jsse inyecta en línea en cualquier archivo de plantilla que contenga:
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Implementación
Cuando ejecutes npm run discourse, se llamará al script /discourse-push.js y hará lo siguiente:
- Primero compilará, como si fuera con
npm run build - Luego, inicializará un nuevo repositorio git dentro de
/dist - Luego hará commit de
/disten la ramadiscoursede tu proyecto (creará la rama si no existe)
Usando la rama discourse
Cada una de las siguientes
/url/relativas/son relativas a la URL base de tu foro, por ejemplo, https://ejemplo.com/url/relativas/
Instalar el componente
Instala tu componente visitando /admin/customize/themes y selecciona “Importar desde la web” desde el repositorio de tu proyecto, por ejemplo: https://github.com/mi-increible/componente-discourse.
Luego, establece la rama en discourse. No funcionará si la dejas en master, ya que Discourse intentará cargar los archivos no compilados (si es que funciona en absoluto).
Depuración de archivos específicos del tema en tu propio host
- Instala la CLI de temas de Discourse
- Inicia sesión en https://theme-creator.discourse.org
- CD en este directorio, luego ejecuta
discourse_theme watch . - Usa
https://theme-creator.discourse.orgcomo la URL base- Usa tu clave API de
theme-creator
- Usa tu clave API de
Si eres nuevo en Discourse y te gustaría bifurcar este proyecto, las siguientes lecturas podrían ser útiles.