Docs
Instalacion
Instalacion
Como instalar tu aplication.
Guía de Instalación Completa
Requisitos del Sistema
Software Requerido
- Node.js 20.11.1 o superior
- Redis 6.0+ (para caché)
- MeiliSearch 1.0+ (para búsqueda)
- VS Code (recomendado)
Hardware Recomendado
- CPU: 4 cores o superior
- RAM: 8GB mínimo (16GB recomendado)
- Almacenamiento: 10GB libre mínimo
- Conexión Internet: 10Mbps+
Cuentas Necesarias
- Vercel (para hosting)
- Shopify Partner (para desarrollo)
- MeiliSearch Cloud (o self-hosted)
- Upstash (opcional, para Redis)
1. Preparación del Entorno
Windows
- Instala Node.js:
# Usando winget
winget install OpenJS.NodeJS.LTS
# Verifica instalación
node --version # debe mostrar 20.x+
npm --version # debe mostrar 10.x+
- Instala MeiliSearch:
# Usando Docker
docker run -d -p 7700:7700 getmeili/meilisearch:latest
# Verifica MeiliSearch
curl http://localhost:7700/health
macOS
# Instala Homebrew si no lo tienes
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Instala dependencias
brew install node
brew install meilisearch
brew install redis
# Verifica instalaciones
node --version
meilisearch --version
redis-cli ping
Linux (Ubuntu/Debian)
# Actualiza sistema
sudo apt update && sudo apt upgrade
# Instala Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Instala MeiliSearch
curl -L https://install.meilisearch.com | sh
2. Configuración del Proyecto
- Accede a la carpeta del repositorio:
# Instala con nuestro CLI
cd store
yarn create commerce
- Instala dependencias:
npm install
# Verifica instalación
npm run verify
- Configura Variables de Entorno:
# Copia el template
cp .env.example .env.local
# Estructura completa del .env.local:
# Shopify
SHOPIFY_APP_API_SECRET_KEY=xxx # Requerido
SHOPIFY_STORE_DOMAIN=xxx # Requerido
SHOPIFY_STOREFRONT_ACCESS_TOKEN=xxx # Requerido
SHOPIFY_ADMIN_ACCESS_TOKEN=xxx # Requerido
# MeiliSearch
MEILISEARCH_HOST=http://localhost:7700 # URL MeiliSearch
MEILISEARCH_ADMIN_API_KEY=xxx # API key
MEILISEARCH_SEARCH_API_KEY=xxx # API key pública
# Redis (elige una opción)
USE_LOCAL_REDIS=true # Para Redis local
LOCAL_REDIS_URL=redis://localhost:6379 # URL Redis local
# O
UPSTASH_REDIS_REST_URL=xxx # Para Upstash
UPSTASH_REDIS_REST_TOKEN=xxx # Para Upstash
# Site Configuration
LIVE_URL=http://localhost:3000
NEXT_PUBLIC_DEMO_MODE=false
3. Configuración de Servicios
Configuración Shopify
-
Crea una app en Shopify Partners:
- Ve a Partners Dashboard
- Crea nueva app
- Configura URLs de redirección
- Obtén credenciales
-
Configura Webhooks:
- Products create/update/delete
- Collections update
- Inventory update
-
Configura Storefront API:
- Habilita acceso a Storefront API
- Genera token de acceso
- Define scopes necesarios
Configuración MeiliSearch
- Crea índices:
# Inicia indexación inicial
npm run meilisearch:init
# Estructura de índices
- products
- collections
- pages
- Configura búsqueda:
# Atributos buscables
title
description
vendor
tags
# Atributos filtrables
price
categories
vendor
- Verifica indexación:
# Prueba búsqueda
curl http://localhost:7700/indexes/products/search \
-H "Authorization: Bearer $MEILISEARCH_SEARCH_API_KEY" \
-d '{"q": "test"}'
4. Desarrollo Local
- Inicia servicios:
# Redis
redis-server
# MeiliSearch
meilisearch
# Next.js
npm run dev
-
Verifica en http://localhost:3000
-
Prueba funcionalidades:
- Navegación de categorías
- Búsqueda de productos
- Carrito de compras
- Favoritos
- Checkout
5. Despliegue en Vercel
- Prepara el proyecto:
npm run build # Verifica build local primero
- Configura Vercel:
- Crea cuenta en Vercel
- Instala Vercel CLI:
npm i -g vercel
- Login:
vercel login
- Deploy:
vercel
# Configura:
# - Importa variables de entorno
# - Configura dominio personalizado
# - Habilita análisis
6. Scripts Disponibles
# Desarrollo
npm run dev # Servidor desarrollo
npm run build # Construye app
npm run start # Inicia producción
npm run lint # Ejecuta linter
npm run type-check # Verifica tipos
# MeiliSearch
npm run meilisearch:init # Inicializa índices
npm run meilisearch:sync # Sincroniza productos
npm run meilisearch:reindex # Reindexación completa
# Testing
npm run test # Ejecuta tests
npm run test:e2e # Tests E2E
npm run test:watch # Tests en watch mode
# Utilidades
npm run analyze # Analiza bundle
npm run clean # Limpia build
7. Solución de Problemas
Errores Comunes
# Error: Cannot find module
npm install # Reinstala módulos
rm -rf .next node_modules
npm install # Reinstalación limpia
# Error: API Connection
- Verifica credenciales
- Comprueba URLs
- Revisa permisos API
# Error: MeiliSearch
- Verifica servicio activo
- Comprueba permisos
- Reindexar si necesario
Verificación
# Estado de servicios
systemctl status redis
curl http://localhost:7700/health
npm run verify
# Logs
tail -f logs/error.log
vercel logs
8. Mantenimiento
Actualizaciones
- Actualiza dependencias regularmente
- Monitorea cambios en APIs
- Mantén indices sincronizados
- Actualiza cache según necesidad
Backups
- Configura respaldo de Redis
- Exporta datos de MeiliSearch
- Respalda configuraciones
- Documenta cambios
Monitoreo
- Configura alertas de error
- Monitorea uso de API
- Revisa métricas de performance
- Analiza logs regularmente