Primeiros Passos com a Copera Starter Application

A Copera Starter Application é um portal de referência que mostra como construir um aplicativo web voltado ao cliente, alimentado pelo seu workspace da Copera. Ela usa um Board como banco de dados, permitindo que você gerencie usuários e tickets diretamente na Copera enquanto o portal cuida da autenticação, envio e exibição.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte instalado e disponível:

Requisito	Versão / Observações
Node.js	>= 24.0.0
pnpm	10.16.1
Banco de dados	Uma instância local ou um banco de dados gerenciado na nuvem
Workspace da Copera	Um workspace ativo com um Board configurado (veja o Passo 2)

Passo 1: Clonar o Repositório

A starter application será publicada em github.com/copera-ai. Quando estiver disponível, clone-a para sua máquina local:

git clone https://github.com/copera-ai/starter-application.git
cd starter-application

observação

Se o repositório ainda não estiver público, verifique novamente em github.com/copera-ai ou entre em contato com a equipe da Copera para acesso antecipado.

Passo 2: Configurar Seu Board na Copera

A starter application lê e escreve dados em um Board da Copera. Você precisa criar um Board com duas tabelas — Users e Tickets — e depois copiar os IDs relevantes para o arquivo de configuração da aplicação.

Criar o Board

No seu workspace da Copera, acesse Colaborar na barra lateral e crie um novo Board. Dê um nome como "Portal Data".

Configurar a Tabela Users

O seu Board terá uma tabela padrão. Renomeie-a para Users e adicione as seguintes colunas:

Nome da Coluna	Tipo de Campo	Observações
Name	Text	O nome de exibição do usuário
Identifier	Text	O endereço de email do usuário (usado para autenticação)
Password	Password	Armazenado com segurança; usado para autenticação no portal
Role	Select (Dropdown)	Adicione duas opções: admin e user

Configurar a Tabela Tickets

Adicione uma segunda tabela ao Board e nomeie-a Tickets. Adicione as seguintes colunas:

Nome da Coluna	Tipo de Campo	Observações
Title	Text	Um resumo curto do ticket
Details	Paragraph (Text)	Descrição completa da solicitação
User	Link	Vínculo com a tabela Users
Status	Select (Dropdown)	Adicione opções como open, in progress, closed
Request Type	Select (Dropdown)	Adicione opções relevantes para o seu caso de uso

Encontrar os IDs do Board, das Tabelas e das Colunas

Você precisará copiar vários IDs para a configuração da aplicação. Veja onde encontrar cada um:

• Board ID — O ID do Board aparece na URL quando o Board está aberto. Ele tem o formato: app.copera.ai/boards/6abc123.... Copie o trecho após /boards/.
• Table ID — Abra o Board e clique na aba com o nome da tabela na parte superior. O Table ID é exibido no painel de configurações da tabela, ou pode ser encontrado na URL após navegar até a tabela.
• Column ID — Clique no ícone de configurações (engrenagem ou menu de três pontos) no cabeçalho de qualquer coluna. O painel de configurações da coluna exibirá o ID da coluna. Copie esse valor para cada coluna que você precisar referenciar.

dica

Mantenha um arquivo de texto aberto enquanto copia os IDs — você precisará de um Board ID, dois Table IDs e vários Column IDs antes de passar para o próximo passo.

Editar src/config.ts

Abra src/config.ts no repositório clonado e preencha os IDs coletados:

export const config = {
  boardId: 'SEU_BOARD_ID',
  tables: {
    users: {
      tableId: 'SEU_USERS_TABLE_ID',
      columns: {
        name: 'SEU_NAME_COLUMN_ID',
        identifier: 'SEU_IDENTIFIER_COLUMN_ID',
        password: 'SEU_PASSWORD_COLUMN_ID',
        role: 'SEU_ROLE_COLUMN_ID',
      },
    },
    tickets: {
      tableId: 'SEU_TICKETS_TABLE_ID',
      columns: {
        title: 'SEU_TITLE_COLUMN_ID',
        details: 'SEU_DETAILS_COLUMN_ID',
        user: 'SEU_USER_COLUMN_ID',
        status: 'SEU_STATUS_COLUMN_ID',
        requestType: 'SEU_REQUEST_TYPE_COLUMN_ID',
      },
    },
  },
};

Passo 3: Configurar as Variáveis de Ambiente

A aplicação usa um arquivo .env para armazenar segredos e detalhes de conexão. Copie o arquivo de exemplo para começar:

cp .env.example .env

Abra o .env e preencha os seguintes valores:

Variável	Descrição
MONGODB_URI	A string de conexão para a sua instância de banco de dados (ex.: mongodb://localhost:27017/starter ou o URI do Atlas)
APP_TOKEN	Qualquer string secreta usada para assinar JWTs para o gerenciamento de sessões do portal (ex.: uma string aleatória longa)
COPERA_API_KEY	Sua chave de API do workspace, encontrada em Configurações do Workspace > API na Copera

Para o aplicativo web (frontend), defina uma variável adicional:

Variável	Descrição
VITE_SERVER_URL	A URL onde o servidor de API será executado (ex.: http://localhost:3000)

dica

Você pode gerar uma string aleatória segura para APP_TOKEN usando openssl rand -hex 32 no seu terminal.

Encontrar Sua Chave de API da Copera

1. Na Copera, clique no nome do seu workspace no canto superior esquerdo.
2. Vá para Configurações > API.
3. Gere ou copie sua chave de API.

Passo 4: Instalar Dependências e Executar

Com a configuração concluída, instale as dependências e inicie tanto a API quanto o aplicativo web juntos:

pnpm install
pnpm dev

Isso inicia ambos os serviços simultaneamente:

• Servidor de API — executado na porta definida no seu .env (padrão: http://localhost:3000)
• Aplicativo web — executado no servidor de desenvolvimento (padrão: http://localhost:5173)

Abra seu navegador e acesse a URL do aplicativo web. Você verá a página de autenticação do portal.

Passo 5: Criar Seu Primeiro Usuário

O portal não possui um formulário de registro público por padrão — os usuários são gerenciados diretamente no seu Board da Copera. Para criar o primeiro usuário:

1. Na Copera, abra o Board configurado e navegue até a tabela Users.
2. Adicione uma nova linha e preencha as colunas Name, Identifier (email), Password e Role.
3. Retorne ao aplicativo web no seu navegador.
4. Faça login usando o email e a senha que você acabou de inserir.

observação

As senhas inseridas no Board são tratadas pela camada de autenticação da aplicação. O comportamento exato depende de como a starter app processa as credenciais — consulte os arquivos src/config.ts e do serviço de autenticação para mais detalhes.

O Que Vem a Seguir

Agora que a aplicação está em execução, veja algumas direções para ir mais além:

• Personalizar o portal para o seu caso de uso — Ajuste a interface, adicione novas páginas ou modifique os campos do formulário de tickets para corresponder ao seu fluxo de trabalho.
• Adicionar colunas ao seu Board — Qualquer nova coluna adicionada na Copera pode ser referenciada no aplicativo incluindo seu Column ID em src/config.ts.
• Usar ferramentas de IA para construir novos recursos — A starter app é projetada como ponto de partida. Use assistentes de codificação por IA junto com a API da Copera para acelerar o desenvolvimento.
• Explorar a API da Copera — Consulte a referência de API para entender quais operações de dados estão disponíveis além do que a starter app demonstra.

dica

Ao adicionar uma nova coluna ao seu Board na Copera, lembre-se de também adicionar seu Column ID na seção relevante de src/config.ts para que a aplicação possa ler e gravar esse campo.