name: chatwoot-sidebar-menu-item

description: Adicionar item de menu no sidebar do Chatwoot self-hosted (Dashboard App + rota + i18n)

category: devops

Chatwoot Self-Hosted: Adicionar Item de Menu no Sidebar

Contexto

Chatwoot self-hosted (4.12.x) não suporta Dashboard Apps como itens de menu — isso é feature exclusiva do Chatwoot Cloud. A alternativa é adicionar uma rota interna + item de menu manualmente no componente sidebar.

Passo a Passo

1. Criar a Rota

Criar /app/app/javascript/dashboard/routes/dashboard/kanban/kanban.routes.js:

`javascript

import { frontendURL } from '../../../helper/URLHelper';

const meta = {

permissions: ['administrator', 'agent'],

};

export const routes = [

{

path: frontendURL('accounts/:accountId/kanban'),

name: 'kanban_comercial',

component: () => import('./pages/KanbanPage.vue'),

meta,

},

];

`

Criar o componente da página /app/app/javascript/dashboard/routes/dashboard/kanban/pages/KanbanPage.vue:

`vue

`

2. Registrar a Rota no Dashboard

Em /app/app/javascript/dashboard/routes/dashboard/dashboard.routes.js:

`javascript

import { routes as kanbanRoutes } from './kanban/kanban.routes';

// Dentro do children array:

...kanbanRoutes,

`

3. Adicionar Item no Sidebar

Em /app/app/javascript/dashboard/components-next/sidebar/Sidebar.vue, o menu é definido no computed menuItems. Localizar o bloco correto (ex: após Reports, antes de Campaigns) e adicionar:

`javascript

{

name: 'Kanban',

label: t('SIDEBAR.KANBAN'),

icon: 'i-lucide-layout-dashboard',

to: accountScopedRoute('kanban_comercial'),

},

`

Para editar dentro do container Docker (Python3 não disponível, usar Node.js):

`bash

docker exec root-rails-1 node -e "

const fs = require('fs');

let c = fs.readFileSync('/app/app/javascript/dashboard/components-next/sidebar/Sidebar.vue', 'utf8');

const old = \"],\\n },\\n {\\n name: 'Campaigns'\";

const rep = \"],\\n },\\n {\\n name: 'Kanban',\\n label: t('SIDEBAR.KANBAN'),\\n icon: 'i-lucide-layout-dashboard',\\n to: accountScopedRoute('kanban_comercial'),\\n },\\n {\\n name: 'Campaigns'\";

if (c.includes(old)) { c = c.replace(old, rep, 1); fs.writeFileSync('/app/app/javascript/dashboard/components-next/sidebar/Sidebar.vue', c); console.log('OK'); } else { console.log('NOT FOUND'); }

"

`

4. Adicionar Tradução

Em /app/app/javascript/dashboard/i18n/locale/pt_BR/settings.json, adicionar dentro da seção SIDEBAR:

`json

"KANBAN": "Kanban Comercial",

`

Passo 5 — Rebuild e Restart

⚠️ ERRO COMUM: docker restart sozinho NÃO basta. Assets pré-compilados precisam ser regerados explicitamente.

`bash

1. Compilar assets (precisa RAILS_ENV=production)

docker exec root-rails-1 sh -c "RAILS_ENV=production bundle exec rails assets:precompile 2>&1 | tail -20"

⚠️ Demora 2-3 minutos. "Binary assets must be regenerated" é normal.

2. Restart do container

docker restart root-rails-1

3. Aguardar ~15s até Rails estar de pé

sleep 15

4. Hard refresh no navegador (Ctrl+Shift+R / Cmd+Shift+R)

`

Se aparecer "Binary assets must be regenerated", rodar bundle exec rails assets:clobber && RAILS_ENV=production bundle exec rails assets:precompile.

Tradução — Onde Colocar

A chave SIDEBAR.KANBAN deve estar na seção SIDEBAR do arquivo settings.json:

`json

{

"SIDEBAR": {

"HELP": "...",

...

"KANBAN": "Kanban Comercial"

}

}

`

Se a tradução não aparecer, verificar que o Sidebar.vue usa this.$t('SIDEBAR.KANBAN') (não apenas t('SIDEBAR.KANBAN')). No Sidebar.vue o computed menuItems é buildado com label: this.$t(...).

Armadilhas

• - Dashboard Apps não aparecem no menu em self-hosted — a documentação do Chatwoot induz a erro pois só funciona no Cloud. A rota criada carrega o Dashboard App via iframe dentro da página.
• - Padrão de item simples (sem children) é diferente de item com children — não usar children: [...], usar to: accountScopedRoute(...).
• - Container Chatwoot não tem Python3 — usar Node.js para editing programático.
• - Hard refresh no navegador (Ctrl+Shift+R) é necessário após restart para limpar cache do service worker.
• - docker restart sozinho não basta — assets pré-compilados não são regenerados no restart. É preciso rodar assets:precompile explicitamente.
• - pnpm build não existe — Chatwoot 4.12.1 não tem script build no package.json. Usar bundle exec rails assets:precompile.

Problema Crítico: Overlay Docker + Rebuild de Assets

Diagnóstico — dois modos de operação do Chatwoot

O Chatwoot container pode rodar em modo produção (assets pré-compilados via Vite, servidos como arquivos estáticos) ou modo desenvolvimento (Vite dev server com hot-reload). O sintoma de cada um é diferente:

Modo Produção (assets pré-compilados):

• - Arquivos JS em /app/public/vite/ com data antiga (ex: mar/2026)
• - Após editar arquivos-fonte, precisa rebuild manual senão o navegador carrega o JS antigo
• - pnpm build funciona (existe script em package.json? — NAO EXISTE em 4.12.1, apenas build:sdk)
• - Acesso direto ao JS: headers mostram

Modo Desenvolvimento (Vite dev server):

• - Container usa overmind start -f ./Procfile.dev (não rails s)
• - Assets servidos pelo Vite dev server via WebSocket (hot reload)
• - Arquivos JS do overlayfs são "vista" pelo dev server? Depende — às vezes o dev server não recarrega.
• - Acesso direto ao JS: headers mostram /app/javascripts/chunk-vendors.js (sem hash do Vite)

Como identificar qual modo seu container usa:

`bash

Se voltar "assets pré-compilados", é modo produção

curl -sI https://chat.rochasalesseguros.com.br/app/javascripts/chunk-vendors.js 2>/dev/null | grep -i content-length

Ver data dos assets

docker exec root-rails-1 ls -la /app/public/vite/ 2>/dev/null

Ver se npm existe

docker exec root-rails-1 which npm

Ver o que está rodando (Ruby/Rails server vs Overmind/Vite dev)

docker logs root-rails-1 2>&1 | grep -E 'overmind|vite|rails s|3000'

Se mostrar "overmind start -f ./Procfile.dev" → dev mode

Se mostrar "bundle exec rails s" → produção (Puma na porta 3000)

`

O sintoma em modo produção

Após editar Sidebar.vue, settings.json e as rotas, o docker restart root-rails-1 é executado mas o menu não aparece. O navegador continua usando o bundle JavaScript antigo (aquele com hash como dashboard-B6RGXI4Y.js).

Solução: rebuild dos assets (modo produção)

Passo 1 — Instalar npm no container Alpine:

`bash

docker exec root-rails-1 sh -c "apk add --no-cache nodejs npm"

`

Passo 2 — Instalar pnpm:

`bash

docker exec root-rails-1 npm install -g pnpm

`

Passo 3 — Rebuild (CENÁRIO ATUAL: sem script "build" no package.json!):

O package.json do Chatwoot 4.12.1 NÃO TEM script pnpm build. Os scripts disponíveis são: dev, start:dev, build:sdk, ruby:prettier, story:dev, story:build. Para rebuildar os assets em modo produção, é preciso:

`bash

NÃO rode "pnpm build" — não existe

Em modo produção (bundle exec rails s), rode:

docker exec root-rails-1 bundle exec rake assets:precompile

`

Se assets:precompile não funcionar (cenário desenvolvimento):

`bash

CentOS/RHEL (não Alpine)

docker exec root-rails-1 yum install -y nodejs npm

Depois rebuild

docker exec root-rails-1 sh -c "cd /app && pnpm install && pnpm build:sdk"

`

Passo 4 — Restart e hard refresh:

`bash

docker restart root-rails-1

Esperar ~15s até o Rails estar de pé

No navegador: Ctrl+Shift+R (hard refresh) ou Cmd+Shift+R

`

Alternativa: modo desenvolvimento (overlayfs + dev server)

Se o container roda com Overmind + Vite dev server (overmind start -f ./Procfile.dev), as alterações nos arquivos .vue do overlayfs podem não ser vistas pelo dev server porque:

1. O Vite no dev server serve do código-fonte, mas se o overlayfs Copia-só-leitura (COW) sobrepõe os arquivos base com uma camada superior de escrita, o dev server pode não recarregar corretamente.

2. Solução encontrada: Restart do container força o Overmind/Vite a recarregar:

`bash

docker restart root-rails-1

Aguardar 15-20s até totalmente iniciado

Hard refresh no navegador

`

Se mesmo assim não aparecer, a solução é buildar os assets manualmente conforme acima.

Resumo prático