Primeros pasos con la Copera Starter Application

La Copera Starter Application es un portal de referencia que muestra cómo construir una aplicación web orientada al cliente impulsada por tu espacio de trabajo de Copera. Usa un Board como base de datos, así que puedes gestionar usuarios y tickets directamente en Copera mientras tu portal maneja la autenticación, el envío y la visualización.

Requisitos previos

Antes de empezar, asegúrate de tener instalado y disponible lo siguiente:

Requisito	Versión / Notas
Node.js	>= 24.0.0
pnpm	10.16.1
Base de datos	Una instancia local o una base de datos gestionada en la nube
Espacio de trabajo de Copera	Un espacio de trabajo activo con un Board configurado (consulta el Paso 2)

Paso 1: Clonar el repositorio

La starter application se publicará en github.com/copera-ai. Una vez disponible, clónala en tu máquina local:

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

nota

Si el repositorio aún no es público, vuelve a comprobarlo en github.com/copera-ai o contacta con el equipo de Copera para obtener acceso anticipado.

Paso 2: Configurar tu Board en Copera

La starter application lee y escribe en un Copera Board. Necesitas crear un Board con dos tablas — Users y Tickets — y luego copiar los IDs correspondientes en el archivo de configuración de la aplicación.

Crear el Board

En tu espacio de trabajo de Copera, ve a Collaborate en la barra lateral y crea un nuevo Board. Dale un nombre como "Portal Data".

Configurar la tabla Users

Tu Board tendrá una tabla predeterminada. Renómbrala a Users y añade las siguientes columnas:

Nombre de columna	Tipo de campo	Notas
Name	Texto	El nombre visible del usuario
Identifier	Texto	La dirección de correo del usuario (usada para iniciar sesión)
Password	Contraseña	Almacenada de forma segura; usada para la autenticación del portal
Role	Select (Dropdown)	Añade dos opciones: admin y user

Configurar la tabla Tickets

Añade una segunda tabla al Board y nómbrala Tickets. Añade las siguientes columnas:

Nombre de columna	Tipo de campo	Notas
Title	Texto	Un resumen breve del ticket
Details	Párrafo (Texto)	Descripción completa de la solicitud
User	Link	Enlace a la tabla Users
Status	Select (Dropdown)	Añade opciones como open, in progress, closed
Request Type	Select (Dropdown)	Añade opciones relevantes para tu caso de uso

Encontrar tu Board ID, Table IDs y Column IDs

Necesitas copiar varios IDs en la configuración de la aplicación. Aquí tienes dónde encontrar cada uno:

• Board ID — El Board ID aparece en la URL cuando tienes el Board abierto. Se ve así: app.copera.ai/boards/6abc123.... Copia el segmento que sigue a /boards/.
• Table ID — Abre el Board y haz clic en la pestaña con el nombre de la tabla en la parte superior. El Table ID se muestra en el panel de configuración de la tabla, o puedes encontrarlo en la URL después de entrar en la tabla.
• Column ID — Haz clic en el icono de configuración (engranaje o menú de tres puntos) en cualquier encabezado de columna. El panel de configuración de la columna mostrará el ID de la columna. Copia este valor para cada columna que necesites referenciar.

consejo

Mantén un archivo de texto abierto mientras copias los IDs — necesitarás un Board ID, dos Table IDs y varios Column IDs antes de pasar al siguiente paso.

Editar src/config.ts

Abre src/config.ts en el repositorio clonado y rellena los IDs que recopilaste:

export const config = {
  boardId: 'YOUR_BOARD_ID',
  tables: {
    users: {
      tableId: 'YOUR_USERS_TABLE_ID',
      columns: {
        name: 'YOUR_NAME_COLUMN_ID',
        identifier: 'YOUR_IDENTIFIER_COLUMN_ID',
        password: 'YOUR_PASSWORD_COLUMN_ID',
        role: 'YOUR_ROLE_COLUMN_ID',
      },
    },
    tickets: {
      tableId: 'YOUR_TICKETS_TABLE_ID',
      columns: {
        title: 'YOUR_TITLE_COLUMN_ID',
        details: 'YOUR_DETAILS_COLUMN_ID',
        user: 'YOUR_USER_COLUMN_ID',
        status: 'YOUR_STATUS_COLUMN_ID',
        requestType: 'YOUR_REQUEST_TYPE_COLUMN_ID',
      },
    },
  },
};

Paso 3: Configurar las variables de entorno

La aplicación usa un archivo .env para almacenar secretos y detalles de conexión. Copia el archivo de ejemplo para empezar:

cp .env.example .env

Abre .env y rellena los siguientes valores:

Variable	Descripción
MONGODB_URI	La cadena de conexión de tu instancia de base de datos (p. ej., mongodb://localhost:27017/starter o tu URI de Atlas)
APP_TOKEN	Cualquier cadena secreta usada para firmar los JWT de la gestión de sesiones del portal (p. ej., una cadena aleatoria larga)
COPERA_API_KEY	La clave API de tu espacio de trabajo, que se encuentra en Configuración del espacio de trabajo > API en Copera

Para la app web (frontend), define una variable adicional:

Variable	Descripción
VITE_SERVER_URL	La URL donde se ejecutará el servidor de la API (p. ej., http://localhost:3000)

consejo

Puedes generar una cadena aleatoria segura para APP_TOKEN usando openssl rand -hex 32 en tu terminal.

Encontrar tu clave API de Copera

1. En Copera, haz clic en el nombre de tu espacio de trabajo en la esquina superior izquierda.
2. Ve a Configuración > API.
3. Genera o copia tu clave API.

Paso 4: Instalar dependencias y ejecutar

Con la configuración completa, instala las dependencias e inicia juntos la API y la app web:

pnpm install
pnpm dev

Esto inicia ambos servicios de forma concurrente:

• Servidor de API — se ejecuta en el puerto definido en tu .env (predeterminado: http://localhost:3000)
• App web — se ejecuta en el servidor de desarrollo (predeterminado: http://localhost:5173)

Abre tu navegador y dirígete a la URL de la app web. Verás la página de inicio de sesión del portal.

Paso 5: Crear tu primer usuario

El portal no tiene un formulario de registro público por defecto — los usuarios se gestionan directamente en tu Copera Board. Para crear el primer usuario:

1. En Copera, abre el Board que configuraste y navega a la tabla Users.
2. Añade una nueva fila y rellena las columnas Name, Identifier (correo), Password y Role.
3. Vuelve a la app web en tu navegador.
4. Inicia sesión con el correo y la contraseña que acabas de introducir.

nota

Las contraseñas introducidas en el Board son gestionadas por la capa de autenticación de la aplicación. El comportamiento exacto depende de cómo la starter app procese las credenciales — consulta el archivo src/config.ts y los archivos del servicio de autenticación para más detalles.

Qué sigue

Ahora que la aplicación está en funcionamiento, aquí tienes algunas direcciones para llevarla más lejos:

• Personaliza el portal para tu caso de uso — Ajusta la UI, añade nuevas páginas o cambia los campos del formulario de tickets para que se adapten a tu flujo de trabajo.
• Añade columnas a tu Board — Cualquier columna nueva que añadas en Copera puede referenciarse en la app añadiendo su Column ID a src/config.ts.
• Usa herramientas de IA para construir nuevas funciones — La starter app está diseñada para ser un punto de partida. Usa asistentes de programación con IA junto a la API de Copera para acelerar el desarrollo.
• Explora la API de Copera — Revisa la referencia de la API para entender qué operaciones de datos están disponibles más allá de lo que demuestra la starter app.

consejo

Cuando añadas una nueva columna a tu Board en Copera, recuerda añadir también su Column ID a la sección correspondiente de src/config.ts para que la aplicación pueda leer y escribir ese campo.