Skip to content

development-setup.mdx

Latest commit

 

History

History
290 lines (209 loc) · 6.31 KB

development-setup.mdx

File metadata and controls

290 lines (209 loc) · 6.31 KB

Configuración de Desarrollo

Esta guía te ayudará a configurar tu entorno de desarrollo local para Fasttify.

Prerrequisitos

Software Requerido

  • Node.js: Versión 20.18.3 o superior
  • pnpm: Versión 10.18.0 o superior (gestor de paquetes)
  • AWS CLI: Configurado con credenciales válidas
  • Git: Para clonar el repositorio

Cuenta AWS

  • Cuenta AWS con permisos para AWS Amplify Gen2
  • Acceso a servicios: DynamoDB, Lambda, S3, CloudFront, SES, Cognito

Instalación

1. Clonar el Repositorio

git clone https://github.com/Fasttify/fasttify.git
cd fasttify

2. Instalar Dependencias

# Instalar pnpm globalmente si no lo tienes
npm install -g pnpm@10.18.0

# Instalar dependencias del proyecto
pnpm install

3. Configurar Variables de Entorno

Crea un archivo .env.local en la raíz del proyecto:

# AWS Amplify
NEXT_PUBLIC_S3_URL="YOU BUCKET URL"
NEXT_PUBLIC_AWS_REGION="YOU AWS REGION"
BUCKET_NAME="YOU BUCKET NAME"
AWS_REGION="YOU AWS REGION"
CLOUDFRONT_MULTI_TENANT_DISTRIBUTION_ID="YOU CLOUDFRONT MULTI TENANT DISTRIBUTION ID"
CLOUDFRONT_DISTRIBUTION_ID="YOU CLOUDFRONT DISTRIBUTION ID"
JWT_SECRET="YOU JWT KEY"
LAMBDA_EMAIL_BULK="YOU LAMBDA FOR EMAILS"
ANALYTICS_WEBHOOK_JWT_SECRET="YOU GENERATE API KEY"
# Desarrollo
APP_ENV=development
NEXT_PUBLIC_APP_ENV=development
TEMPLATES_DEV_ROOT=packages/example-themes/fasttify/theme
DEV_CACHE_ENABLED=true
POLAR_ACCESS_TOKEN=YOU POLAR ACCESS TOKEN
POLAR_WEBHOOK_SECRET=YOU POLAR WEBHOOK SECRET
POLAR_ORGANIZATION_ID=YOU POLAR ORGANIZATION ID
SUCCESS_URL=YOU SUCCESS URL
USER_POOL_ID=YOU USER POOL ID
RUST_BACKTRACE=1x

4. Configurar AWS Amplify Gen2

# Instalar Amplify CLI Gen2
npm install -g @aws-amplify/backend-cli

# Inicializar sandbox de desarrollo
npx ampx sandbox --identifier tu-identificador --stream-function-logs

Scripts de Desarrollo

Comandos Principales

# Servidor de desarrollo con Turbopack
pnpm run dev

# Build del proyecto
pnpm run build

# Tests unitarios
pnpm run test

# Tests con coverage
pnpm run test:coverage

# Linting
pnpm run lint

# Verificación de tipos TypeScript
pnpm run type-check

Scripts de Amplify

# Iniciar sandbox de desarrollo
pnpm run sandbox

# Deploy a sandbox
pnpm run sandbox:deploy

# Ver logs de funciones Lambda
pnpm run sandbox:logs

Scripts de Workspace

# Instalar dependencias en todos los workspaces
pnpm run workspace:install

# Actualizar dependencias
pnpm run workspace:update

# Build de todos los packages
pnpm run build:packages

# Tests de todos los packages
pnpm run test:packages

Estructura del Proyecto

fasttify/
├── amplify/                    # Backend AWS Amplify Gen2
│   ├── auth/                   # Configuración de autenticación
│   ├── data/                   # Esquemas GraphQL y funciones IA
│   ├── functions/              # Funciones Lambda
│   └── storage/                # Configuración S3
├── app/                        # Next.js App Router
│   ├── (main-layout)/         # Landing y páginas públicas
│   ├── (setup-layout)/        # Wizard de configuración
│   ├── [store]/               # Rutas dinámicas de tiendas
│   └── api/                   # API Routes
├── packages/                   # Workspaces del monorepo
│   ├── liquid-forge/          # Motor de plantillas Liquid
│   ├── orders-app/            # Gestión de pedidos
│   ├── theme-editor/          # Editor de temas
│   └── tenant-domains/        # Gestión de dominios
├── components/                 # Componentes UI reutilizables
├── lib/                       # Servicios y utilidades
└── docs/                      # Documentación

Desarrollo de Temas

Sincronización en Tiempo Real

# Sincronizar plantillas para una tienda específica
pnpm run template-sync -- start STORE_ID

# El sistema observa cambios y sincroniza automáticamente

Compilación de Emails

# Compilar plantillas de email
pnpm run email:compile

# Probar sistema de emails
pnpm run email:test

# Desarrollo completo de emails
pnpm run email:dev

Configuración de IDE

VS Code (Recomendado)

Instala las siguientes extensiones:

  • ES7+ React/Redux/React-Native snippets
  • TypeScript Importer
  • Tailwind CSS IntelliSense
  • Prettier - Code formatter
  • ESLint

Configuración de Prettier

El proyecto incluye configuración de Prettier. Asegúrate de tener:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Debugging

Frontend

# Desarrollo con logs detallados
DEBUG=* pnpm run dev

# Build con análisis de bundle
ANALYZE=true pnpm run build

Backend (Lambda Functions)

# Ver logs en tiempo real
pnpm run sandbox:logs

# Logs específicos de una función
npx ampx logs --function-name nombre-funcion

Solución de Problemas

Error: "Cannot find module"

# Limpiar node_modules y reinstalar
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

Error: "AWS credentials not found"

# Configurar credenciales AWS
aws configure

# O usar variables de entorno
export AWS_ACCESS_KEY_ID=tu-access-key
export AWS_SECRET_ACCESS_KEY=tu-secret-key
export AWS_DEFAULT_REGION=us-east-1

Error: "Amplify sandbox not found"

# Reinicializar sandbox
npx ampx sandbox --identifier nuevo-identificador

Variables de Entorno Críticas

JWT_SECRET

IMPORTANTE: Genera un secret seguro:

# Generar secret seguro
openssl rand -base64 64

AWS_REGION

Asegúrate de usar la región correcta (us-east-2):

# Verificar región actual
aws configure get region

# Cambiar región si es necesario
aws configure set region us-east-1

Próximos Pasos

Una vez configurado el entorno de desarrollo:

  1. Guía de desarrollo de temas
  2. Arquitectura del sistema
  3. API Reference
  4. Solución de problemas

Recursos Adicionales