Pular para o conteúdo principal

Guia de Fork de Marca

Antes de tudo: você precisa de um fork?​

Há duas formas de subir uma marca nova, e escolher errado custa caro depois.

CaminhoQuandoCusto de manutenção
Brand override no front-web-baseA marca cabe no template: tema, paths, layout, flags, conteúdoBaixo — a marca acompanha o template automaticamente
Fork (repo separado)A marca precisa divergir em código de forma que o template não suportaAlto — updates só entram por cherry-pick, um a um

O caso comum é override, não fork: hoje há 13 brands convivendo no front-web-base sem fork nenhum. Comece por Pontos de Customização Rápida e só considere fork se algo lá for genuinamente insuficiente.

Quantos forks existem hoje: zero​

Não há nenhum fork ativo do front-web-base. Toda marca em produção é um brand override dentro do template compartilhado. Este guia existe pro dia em que um fork for genuinamente inevitável — não porque haja um em operação.

:::danger A regra que define um fork: cherry-pick, nunca merge Se um fork for criado, updates do front-web-base entram nele por cherry-pick de commits específicos. Nunca por merge da branch do base.

Essa é a restrição mais consequente de manter um fork. Um merge do base traria de volta código que o fork removeu de propósito. :::

Vale ler Trunks de marca antes de forkar: o front-web-base já opera com várias trunks paralelas, e às vezes o que se quer é uma trunk, não um repo novo.

O que um fork pode fazer​

Um fork é cópia completa do front-web-base — liberdade total:

  • Criar componentes, páginas, hooks, stores, serviços próprios
  • Adicionar/remover/reescrever páginas
  • Redesenhar o layout inteiro
  • Adicionar bibliotecas e integrações

Única restrição real: não alterar pacotes @cactus-agents/* diretamente — são dependências npm, e qualquer mudança local se perde no próximo pnpm update. Se falta algo no SDK, peça pro time Cactus: entra pra todos.

Pontos de customização preparados​

ArquivoO que facilita
app/config/theme/colors.tsPaleta de cores (tokens Tailwind por seção)
app/config/routes/paths.tsURL paths das páginas existentes (/games → /cassino)
app/config/layout/composition.tsShell, variantes de header/sidebar/footer e slots

:::caution routes/paths.ts renomeia páginas — não adiciona nem remove Pra adicionar ou remover páginas edite app/router/routes.ts diretamente: é uma lista explícita de route()/index(), não é overrideable por brand, e não existe helper que a gere. :::

São atalhos, não limites — e há muito mais config overrideable além desses três (22 subpastas em app/config/). Ver Pontos de Customização Rápida.

Processo​

  1. Clonar front-web-base como novo repositório (front-web-<marca>)
  2. Configurar .env / .dev.vars com as variáveis da marca (ver env-vars)
  3. Configurar .npmrc com token de acesso ao GitHub Packages
  4. pnpm install para resolver os pacotes @cactus-agents/*
  5. Personalizar tema, paths, layout — e o que mais for necessário
  6. Testar localmente com pnpm dev
  7. Validar com pnpm quality (lint + typecheck + testes — o mesmo que o CI roda)
  8. Configurar deploy no front-ops e no GitHub:
    • Registrar o repo no front-ops: config/brands/<repo-key>/brand.yml (com brand: e repo:) + um config/brands/<repo-key>/environments/<env>/deploy.yml por ambiente (com cf_account, worker_name, origin_domain, …)
    • Adicionar o novo repo à lista de Repository access de cada org secret relevante (GH_PACKAGES_TOKEN, FRONT_GH_ACTIONS_TOKEN, FRONT_{XX}_CF_*) em Settings → Secrets → Actions
    • Se a marca usa domínio novo, editar o API Token da conta CF correspondente pra incluir a nova zona em Zone Resources
    • Subir o Worker e configurar vars/secrets (API_BASE_URL, CF_WORKER_KEY, …)

:::info config/brands/ é indexado por REPO, não por marca Em front-ops, uma pasta de config/brands/ == um repositório. Hoje existe exatamente uma: web-base.

Então, brand nova no template compartilhado não cria pasta nova: cria só um config/brands/web-base/environments/<env>/deploy.yml. Um brand.yml novo só faz sentido pra um repo novo de verdade — ou seja, pra um fork. :::

:::tip Passo a passo detalhado O fluxo completo de deploy está em Deploy → Adicionar brand/fork e Deploy → Adicionar environment. :::

Atualização de lógica de negócio​

A lógica de plataforma vive nos pacotes @cactus-agents/* — atualizar é pnpm update, sem merge conflict, porque são dependências npm e não código copiado:

# pacotes específicos
pnpm update @cactus-agents/accounts @cactus-agents/brand

# todos
pnpm update "@cactus-agents/*"

Dois avisos:

  • @cactus-agents/auth, user e wallet não existem mais. Foram unificados em @cactus-agents/accounts. Comando com esses nomes falha.
  • @cactus-agents/sports-rogue não mora no front-cactus-core. É dependência real do base (^0.29.2) publicada de outro lugar — não procure por ela em front-cactus-core/packages/.

A lista de dependências reais é o package.json:

grep '@cactus-agents/' package.json

Atualização de template​

Para mudanças na UI/estrutura do front-web-base, a propagação é cherry-pick dos commits desejados — ver a regra de cherry-pick acima. A superfície de conflito cresce com o quanto o fork divergiu, o que é o principal argumento pra resolver por brand override em vez de fork sempre que der.