Pular para o conteúdo principal

FAQ

Geral​

O que é um "fork"?​

Um fork é a sua própria cópia completa do template base do Cactus. Você tem total liberdade para customizá-lo — criar componentes, adicionar páginas, mudar estilos, redesenhar o layout, etc.

Por onde começo a customizar?​

Os pontos de entrada mais comuns são:

  • app/config/theme/colors.ts — Cores e tokens do tema
  • overrides/<sua-marca>/app/config/routes/paths.ts — URLs das páginas
  • overrides/<sua-marca>/app/config/layout/composition.ts — Componentes do layout

Mas você não está limitado a esses arquivos. Pode modificar qualquer arquivo, criar novos componentes, adicionar bibliotecas — o fork é completamente seu.

Posso adicionar páginas customizadas?​

Sim. Crie um novo arquivo em app/routes/ e registre-o em routes.config.ts. Você também pode criar componentes, hooks e stores customizados. Consulte Customização de Rotas.

O que não posso modificar?​

A única coisa que você deve evitar modificar diretamente são os pacotes @cactus-agents/* — eles são dependências npm atualizadas via pnpm update. Se precisar de algo que o SDK ainda não suporta, entre em contato com o time Cactus.

SDK e dependências​

Como atualizo o SDK (@cactus-agents/*)?​

Execute o seguinte comando na raiz do projeto:

pnpm update "@cactus-agents/*"

Isso atualiza todos os pacotes do SDK para a versão mais recente compatível com os ranges definidos no package.json. Após atualizar, verifique o changelog do SDK para breaking changes e teste o build localmente antes de fazer deploy.

Para atualizar para uma versão específica:

pnpm update @cactus-agents/api-client@0.5.0

Consulte SDK Updates para o guia completo.

Como instalo e testo localmente?​

  1. Clone seu repositório fork
  2. Instale as dependências: 
    pnpm install
  3. Copie o arquivo de variáveis de ambiente: 
    cp .env.example .env
    cp .dev.vars.example .dev.vars
  4. Preencha as variáveis obrigatórias (principalmente API_BASE_URL)
  5. Inicie o servidor de desenvolvimento: 
    pnpm dev

O servidor estará disponível em http://localhost:5173 (Vite) ou http://localhost:8787 (Wrangler, para testar o SSR completo).

:::tip Por que dois arquivos de env? .dev.vars é lido pelo servidor SSR (Wrangler/Cloudflare Workers) e .env é lido pelo Vite. Ambos são necessários localmente. :::

Tema e customização visual​

Como customizo as cores e o tema?​

Edite o arquivo app/config/theme/colors.ts (ou a versão no seu diretório de overrides). Ele exporta um objeto com tokens de design que sobrescrevem os padrões do Cactus:

// overrides/<sua-marca>/app/config/theme/colors.ts
export const themeConfig = {
  colors: {
    primary: "#FF5500",
    secondary: "#1A1A2E",
    // ...
  },
  fonts: {
    heading: "Montserrat, sans-serif",
    body: "Inter, sans-serif",
  },
};

Os tokens são aplicados via variáveis CSS e Tailwind. Consulte a documentação de Theming para a lista completa de tokens disponíveis.

Como funciona o sistema de overrides por marca?​

Cada marca tem seu próprio diretório em overrides/<brand-key>/. Arquivos nesse diretório sobrescrevem os equivalentes em app/config/ sem alterar o template base.

Estrutura típica de overrides:

overrides/
└── minha-marca/
    └── app/
        └── config/
            ├── routes.paths.ts   ← URLs customizadas
            ├── theme.config.ts   ← Cores e tokens
            └── layout.config.ts  ← Componentes de layout

O sistema de build detecta automaticamente qual brand está sendo compilado (via variável de ambiente BRAND_KEY) e aplica os overrides correspondentes. Arquivos não presentes no diretório de override usam os valores padrão do template.

Rotas e navegação​

Como adiciono novas rotas?​

Para adicionar uma página nova ao seu fork:

  1. Crie o arquivo de página em app/routes/:

    // app/routes/minha-pagina.tsx
    export default function MinhaPagina() {
      return <div>Minha página customizada</div>;
    }

  2. Registre a rota em app/config/routes.config.ts:

    route("/minha-pagina", "routes/minha-pagina.tsx")

Para páginas que fazem parte do layout principal (header/footer/providers), aninhei dentro do layout('routes/_layout.tsx', [...]).

Como renomeio as URLs das páginas existentes?​

Crie ou edite overrides/<sua-marca>/app/config/routes/paths.ts com as URLs customizadas. Consulte Customização de Rotas para o exemplo completo e a lista de todas as chaves disponíveis.

Gamificação (Smartico)​

Como configuro a gamificação com Smartico?​

A integração com Smartico requer duas configurações:

1. Variável de ambiente (server-side)

Configure SMARTICO_SALT_KEY no painel do Cloudflare Workers (ou no .dev.vars localmente). Essa chave é usada para gerar o hash do usuário no servidor — nunca a exponha no client.

2. Configuração de feature

Habilite a gamificação no config da sua marca:

// overrides/<sua-marca>/app/config/features/features.ts
export const featuresConfig = {
  gamification: {
    enabled: true,
    provider: "smartico",
  },
};

Após habilitar, as rotas de gamificação (/vip, /vip/missions, etc.) ficam ativas. Para customizar as URLs, use o prefixo gamification.* no routes.paths.ts.

cuidado

SMARTICO_SALT_KEY é uma chave secreta — configure via wrangler secret put SMARTICO_SALT_KEY ou pelo painel do Cloudflare, nunca commitada no repositório.

Técnico​

Por que preciso de .dev.vars e .env?​

.dev.vars é lido pelo servidor SSR (Wrangler/Cloudflare Workers) e .env é lido pela ferramenta de build (Vite). Ambos são necessários localmente.

Em produção, apenas variáveis configuradas no painel do Cloudflare Workers são utilizadas.

Como atualizo a lógica de negócio?​

Execute pnpm update "@cactus-agents/*" para obter os pacotes mais recentes. Consulte SDK Updates.

Onde configuro variáveis de ambiente em produção?​

No painel do Cloudflare Workers. Consulte Deployment.

Suporte​

Entre em contato com o time Cactus para:

  • Tokens de acesso ao GitHub Packages
  • Credenciais de API
  • Assistência com deploy
  • Reportar bugs
  • Solicitar novos ambientes (staging, homolog, etc.)