Edição por @david: O sistema de temas do Discourse agora possui suporte nativo para múltiplos arquivos JS. Este método do webpack não é mais necessário.
Olá! Enquanto eu estava desenvolvendo meu componente handsfree-discourse, encontrei alguns problemas relacionados ao gerenciamento de arquivos. Meu principal problema era a necessidade de dividir meu código em vários arquivos. Outro problema era a necessidade de incluir bibliotecas de terceiros sem precisar pedir aos administradores para habilitar CORS ou disparar solicitações HTTP adicionais.
Para resolver esses problemas, criei o discourse-webpack, um modelo para configurar rapidamente componentes ricos em JS! As funcionalidades incluem:
- Servidor de desenvolvimento local com recarregamento ao vivo (live reloading)
- Inclui um script de commit para manter seu código-fonte e código compilado em ramos separados!
O restante deste tópico explica como usá-lo e por que funciona. Acabei de terminar de testar isso em alguns outros componentes com os quais estou trabalhando, então me avise se você encontrar algum problema ou tiver solicitações específicas!
Configure rapidamente componentes ricos em JavaScript para sua Comunidade Discourse, completo com um script de commit para manter seu código-fonte e código de build em ramos separados para ajudá-lo a continuar entregando \u003ci\u003erápido\u003c/i\u003e!
Instalação
Primeiro, certifique-se de ter o NodeJS >= 8 e o git instalados localmente na sua máquina. Em seguida, digite cada uma das linhas abaixo:
# Baixe este repositório
git clone https://github.com/browsehandsfree/discourse-webpack
# Entre no diretório
cd discourse-webpack
# Instale as dependências
npm install
Depois, você precisará editar o seguinte em package.json, substituindo todos os nossos links pelos seus. Especificamente:
{
name: 'seu-projeto',
repository: {
url: 'git+https://github.com/usuario/repo'
},
author: '',
bugs: {
url: 'https://github.com/usuario/repo/issues'
},
homepage: 'https://exemplo.com'
}
Mais importante de tudo, certifique-se de que repository.url esteja correto e seja precedido por git+. Quando você executar npm run discourse, ele fará commit e push para aquele repositório.
Também, não se esqueça de configurar o about.json do seu Discourse, que está localizado em /src/discourse/about.json.
Desenvolvimento
Após o npm install, você terá a seguinte estrutura de diretórios:
discourse-webpack
|- node_modules/ # Dependências
|- src/ # Arquivos fonte principais
|--|- discourse/ # Arquivos de tema do Discourse
|--|--|- common/
|--|--|- desktop/
|--|--|- mobile/
|--|- main.css # A folha de estilos principal
|--|- main.js # O ponto de entrada principal do JavaScript
|--|- sandbox.html # Sandbox para desenvolvimento local
|- .gitignore
|- discourse-push.js # Script especial de commit
|- README.md
|- webpack.config.js # Configuração do Webpack
|- yarn.lock
Scripts de Linha de Comando
Além disso, você tem acesso aos seguintes comandos a partir da raiz do projeto:
# Inicia um servidor de desenvolvimento em localhost:8080
# - Suporta recarregamento ao vivo (livereload)
# - Usa `/src/sandbox.html` para ajudá-lo a depurar localmente
npm run dev
# Compila seu componente para `/dist`
npm run build
# Compila seu componente para `/dist`
# - Em seguida, faz commit de `/dist` no ramo `discourse`
npm run discourse
Como funciona
Depois de baixar o repositório e instalar as dependências, é hora de começar a desenvolver! Use npm run dev para iniciar um servidor de recarregamento ao vivo em localhost:8080.
Acessar essa URL carregará o arquivo HTML localizado em /src/sandbox.html. Este arquivo não é realmente usado dentro do Discourse; está aqui apenas para ajudá-lo a desenvolver seus scripts localmente (fora do contexto do Discourse).
O ponto de entrada principal do webpack é /src/main.js. A partir daí, você pode importar outros scripts e o webpack agrupará tudo e injetará nos seguintes arquivos:
/src/sandbox.html/src/discourse/common/body_tag.html
O main.js é compilado e injetado no sandbox.html automaticamente, mas é injetado manualmente inline no body_tag.html por causa do seguinte código:
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Se você quisesse injetar seu script em outro modelo, como after_header.html, bastaria copiar essa tag script para aquele modelo. Isso permite que você mantenha o HTML e o JavaScript separados durante o desenvolvimento… mas concatenados quando implantados!
Compilação
Quando você compila com npm run build, o que está acontecendo é:
- Primeiro,
/src/main.jse as dependências são agrupados - Em seguida, todos os arquivos em
/src/discourse/são copiados para/dist/ - Ao mesmo tempo,
main.jsé injetado inline em qualquer arquivo de modelo que contenha:
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Implantação
Quando você executa npm run discourse, o script /discourse-push.js é chamado e faz o seguinte:
- Primeiro, ele compila, como se fosse com
npm run build - Em seguida, inicializa um novo repositório git dentro de
/dist - Em seguida, faz commit de
/distno ramodiscoursedo seu projeto (ele criará o ramo se ele não existir)
Usando o ramo discourse
Cada uma das seguintes
/urls/relativas/é relativa à URL base do seu fórum, por exemplo, https://exemplo.com/urls/relativas/
Instalar o componente
Instale seu componente acessando /admin/customize/themes e selecionando “Importar da web” a partir do repositório do seu projeto, por exemplo: https://github.com/meu-incrivel/componente-discourse.
Em seguida, defina o ramo como discourse. Não funcionará se você deixá-lo como master, pois o Discourse tentará carregar os arquivos não compilados (se funcionar de alguma forma).
Depurando arquivos específicos de tema no seu próprio host
- Instale o Discourse Theme CLI
- Faça login em https://theme-creator.discourse.org
- Entre neste diretório e execute
discourse_theme watch . - Use
https://theme-creator.discourse.orgcomo a URL base- Use sua chave de API do
theme-creator
- Use sua chave de API do
Se você é novo no Discourse e gostaria de fazer um fork deste projeto, as seguintes leituras podem ser úteis.