Imansi

Apariencia

Quickstart ​

Empezá tu primer proyecto con Imansi en menos de 5 minutos.

Requisitos ​

  • Node.js 18 o superior
  • npm o pnpm
  • Un editor de código (recomendado: VS Code)

Verificá que tenés Node instalado:

bash
node --version

Debería responder algo como v18.20.0 o superior.

Paso 1 — Crear el proyecto ​

Ejecutá el CLI oficial de Imansi:

bash
npx create-imansi-app@latest mi-app

El CLI te va a hacer 7 preguntas:

  1. ¿Cómo se llamará tu proyecto? — Nombre de la carpeta (ej: mi-app)
  2. ¿Qué querés generar? — Auth + Dashboard, Solo Auth, o Solo Dashboard
  3. ¿Qué diseño de Login querés? — Split, Centered, Card o Minimal
  4. ¿Qué diseño de Dashboard querés? — Classic, Collapsed, Topbar o Dual
  5. ¿Qué tema querés por defecto? — minimal, modern, compact, warm, red o yellow
  6. ¿Qué modo querés por defecto? — light, dark o system
  7. ¿Cuál es el nombre de tu marca? — Se usa en el título, sidebar, login, etc.

Elegí las opciones que quieras. Siempre podés cambiarlas después.

Paso 2 — Entrar al proyecto ​

bash
cd mi-app

Vas a ver esta estructura:

mi-app/
├── public/
│   └── logo.png
├── src/
│   ├── imansi/         ← CSS editable (tokens, themes, base)
│   ├── auth/           ← Capa de autenticación
│   ├── pages/          ← Páginas editables
│   ├── lib/
│   ├── App.jsx
│   └── main.jsx
├── theme.imansi.json   ← Config de tema y modo
├── config-imansi.json  ← Config de marca y variantes
├── .env                ← URL del backend
└── package.json

Paso 3 — Instalar dependencias ​

El CLI ya las instala automáticamente, pero por las dudas:

bash
npm install

Paso 4 — Arrancar el dev server ​

bash
npm run dev

Abrí http://localhost:5173 en tu navegador.

Vas a ver tu proyecto funcionando con:

  • ✅ Página de inicio (placeholder — reemplazala con tu landing)
  • ✅ Login funcional
  • ✅ Registro funcional
  • ✅ Dashboard completo con sidebar, stats y gráficos
  • ✅ Sistema de 6 temas × 2 modos

Paso 5 — Cambiar el tema ​

Abrí theme.imansi.json y editá:

json
{
  "theme": "warm",
  "mode": "dark",
  "overrides": {}
}

Reiniciá Vite (Ctrl+C y de nuevo npm run dev) y todo cambia.

Valores de theme: minimal, modern, compact, warm, red, yellow Valores de mode: light, dark, system

Paso 6 — Conectar el backend ​

Si querés que el login y el registro funcionen de verdad, necesitás un backend de autenticación.

Opción A — Usar imansi-auth-node (recomendado) ​

En otra carpeta:

bash
mkdir mi-backend
cd mi-backend
npm init -y
npm install imansi-auth-node

Creá un index.js:

javascript
import express from 'express';
import 'dotenv/config';
import { crearServidorAutenticacion } from 'imansi-auth-node';

const app = express();
app.use('/', crearServidorAutenticacion());

app.listen(3000, () => {
  console.log('Backend escuchando en http://localhost:3000');
});

Creá un .env con tus credenciales de PostgreSQL:

env
PG_HOST=localhost
PG_USUARIO=postgres
PG_CONTRASENA=tu-contraseña
PG_BASE_DE_DATOS=mi-app
JWT_SECRETO=generá-una-cadena-larga-y-aleatoria
URL_FRONTEND=http://localhost:5173

Corré las migraciones:

bash
npx imansi-auth-node migrar

Y arrancá el backend:

bash
node index.js

Opción B — Conectar tu propio backend ​

Editá .env en el proyecto del frontend:

env
VITE_URL_API_AUTENTICACION=http://localhost:3000

Reiniciá Vite después de cambiar .env.

Paso 7 — Probar el flujo completo ​

  1. Andá a http://localhost:5173/registro
  2. Creá una cuenta con un correo real
  3. Si tenés 2FA activado, revisá la consola del backend para ver el código
  4. Ingresá el código
  5. Vas a entrar al dashboard

¡Listo! Ya tenés un proyecto completo con autenticación funcional.

Próximos pasos ​

Reemplazá public/logo.png con tu propio logo. Se usa en:

  • Favicon del navegador
  • Panel de branding del login
  • Sidebar del dashboard
  • Página Home

Personalizar la marca ​

Editá config-imansi.json:

json
{
  "brandName": "Mi Empresa",
  "brandTagline": "Bienvenido a tu panel",
  "brandLogo": "/logo.png"
}

Editar las páginas ​

Todos los templates viven en src/pages/. Son 100% editables.

  • src/pages/auth/Login.jsx — Página de login
  • src/pages/auth/Register.jsx — Página de registro
  • src/pages/dashboard/Home.jsx — Home del dashboard

Editar los datos del dashboard ​

En src/pages/dashboard-data.jsx están los datos demo (stats, chart, actividad). Reemplazalos por datos reales de tu backend.

Editar el CSS ​

Si necesitás control total sobre el sistema de diseño, editá los archivos en src/imansi/:

  • tokens.css — Valores por defecto
  • themes.css — Overrides por tema
  • base.css — Reset y utilidades

Deploy ​

Frontend en Vercel ​

bash
npm run build

Y deployá la carpeta dist/ a Vercel:

bash
vercel --prod

O conectá el repo a Vercel para deploy automático.

Backend en Railway / Render / Fly.io ​

Tu backend con imansi-auth-node es un servidor Express estándar. Podés deployarlo en cualquier servicio que soporte Node.js + PostgreSQL.

No olvides configurar las variables de entorno (.env) en el servicio de deploy.

Problemas comunes ​

"no such file or directory: package.json" ​

Estás corriendo el comando en la carpeta equivocada. Asegurate de estar en la carpeta del proyecto.

Vite no refresca los cambios del .env ​

Vite lee .env solo al arrancar. Después de cambiarlo, reiniciá con Ctrl+C y npm run dev.

"Error: connect ECONNREFUSED" al hacer login ​

El backend no está corriendo o la URL en .env es incorrecta. Verificá que VITE_URL_API_AUTENTICACION apunte al backend correcto.

El logo no se actualiza ​

Si reemplazaste public/logo.png pero seguís viendo el viejo, es caché del navegador. Refrescá con Ctrl + Shift + R.

Recursos ​

Siguiente paso ​

Explorá la documentación de cada paquete para personalizar tu proyecto al máximo:

👉 Ver todos los paquetes

Hecho con ❤️ en Argentina

MIT © 2026 Imansi