DEV Community

Cover image for EverShop 2.1: plataforma TypeScript de e-commerce con React y GraphQL
lu1tr0n
lu1tr0n

Posted on • Originally published at elsolitario.org

EverShop 2.1: plataforma TypeScript de e-commerce con React y GraphQL

#webdev #beginners #tutorial #programming

EverShop apunta a ser la plataforma de e-commerce por defecto para equipos que viven en el ecosistema Node.js.

Montar una tienda en linea sigue siendo una de las tareas mas exigentes en el desarrollo web. No basta con mostrar productos: hay que manejar inventario, impuestos, envios, cupones, pagos, SEO, internacionalizacion, roles de administrador, dashboards y una capa de personalizacion infinita porque ningun negocio vende igual que otro. Durante anios la respuesta estandar ha sido Shopify (SaaS cerrado) o WooCommerce (PHP sobre WordPress). Las opciones modernas en Node.js venian siendo pocas, y casi siempre pensadas para equipos que ya manejaban React del lado del cliente pero terminaban peleando con un backend en otro lenguaje.

EverShop nace justamente en ese hueco: una plataforma de e-commerce open source, escrita de punta a punta en TypeScript, con Express del lado del servidor, React del lado del cliente, GraphQL como capa de datos y PostgreSQL como base. El repositorio evershopcommerce/evershop supera las 10.000 estrellas en GitHub, tiene mas de 2.300 forks y se mantiene activo (su ultimo push fue el 15 de abril de 2026). En este articulo vamos a instalarlo en los tres sistemas operativos principales, construir nuestro primer flujo funcional y compararlo con las alternativas mas fuertes del mercado: Medusa, Saleor y WooCommerce.

Que es EverShop

EverShop es un framework de e-commerce modular. En su descripcion oficial se presenta como una «modern, TypeScript-first eCommerce platform built with GraphQL and React», pero esa frase no le hace del todo justicia. La clave esta en la palabra modular: cada funcionalidad (catalogo, carrito, checkout, pagos, ordenes, clientes, promociones) esta implementada como una extension que se puede activar, desactivar o sobreescribir. Esto permite que una tienda basica y una tienda con 50 reglas fiscales compartan el mismo nucleo sin forzar a nadie.

Tecnicamente se apoya en un stack conocido por la mayoria de desarrolladores Node:

  • Express como servidor HTTP con un sistema de middlewares enrutables.
  • React para la tienda publica (storefront) y el panel de administracion.
  • GraphQL como unica API publica, lo que elimina el clasico problema de over-fetching cuando el storefront necesita combinar producto, categoria, inventario y precios en una sola vista.
  • PostgreSQL como base de datos principal, con migraciones versionadas.
  • TypeScript en todo el codigo, incluidos los temas, lo que acorta enormemente la curva de aprendizaje para equipos que vienen de Next.js o NestJS.

Lo interesante es que el proyecto ya llego a la version 2.1.0 y esta empezando a construir EverShop Cloud, una oferta SaaS complementaria para equipos que no quieren gestionar infraestructura. La licencia del core sigue siendo GPL-3.0, asi que el codigo se puede usar, modificar y redistribuir siempre que los cambios se mantengan bajo la misma licencia copyleft.

Instalacion multi-OS

La forma recomendada por el proyecto es Docker, porque levanta PostgreSQL, el servidor Node y las migraciones en un solo comando. Pero tambien es perfectamente posible instalarlo de forma nativa con Node 20+ y una base PostgreSQL local. Veamos ambos caminos en los tres sistemas operativos.

Windows

En Windows la ruta mas estable es usar WSL2 junto con Docker Desktop. Esto evita los clasicos problemas con terminadores de linea y permisos de archivos que aparecen al correr PostgreSQL nativo en Windows.

# Dentro de una terminal PowerShell (con Docker Desktop corriendo)
wsl --install -d Ubuntu
# Luego, dentro de Ubuntu:
curl -sSL https://raw.githubusercontent.com/evershopcommerce/evershop/main/docker-compose.yml > docker-compose.yml
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Una vez levantados los contenedores, la tienda queda disponible en http://localhost:3000 y el panel admin en http://localhost:3000/admin.

macOS

En macOS el camino es directo con Homebrew. Si ya tenes Docker Desktop instalado, el flujo es identico al de Linux:

brew install --cask docker
open -a Docker
curl -sSL https://raw.githubusercontent.com/evershopcommerce/evershop/main/docker-compose.yml > docker-compose.yml
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Si preferis instalarlo de forma nativa (util cuando vas a desarrollar extensiones propias), necesitas Node 20 o superior y PostgreSQL 14+:

brew install node@20 postgresql@16
brew services start postgresql@16
npx create-evershop-app mi-tienda
cd mi-tienda
npm run setup
npm run dev
Enter fullscreen mode Exit fullscreen mode

Linux

En cualquier distribucion con Docker, el arranque es una sola linea. Este es el metodo oficial que aparece en el README:

curl -sSL https://raw.githubusercontent.com/evershopcommerce/evershop/main/docker-compose.yml > docker-compose.yml
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Para instalacion nativa en Ubuntu o Debian:

sudo apt update
sudo apt install -y nodejs npm postgresql
sudo systemctl start postgresql
sudo -u postgres createuser --superuser evershop
sudo -u postgres createdb evershop
npx create-evershop-app mi-tienda
cd mi-tienda
npm run setup
npm run dev
Enter fullscreen mode Exit fullscreen mode

Durante npm run setup el CLI pide los datos de conexion a PostgreSQL, crea las tablas, ejecuta todas las migraciones y te pide que definas el primer usuario administrador. Es el unico paso interactivo de toda la instalacion.

Uso basico: creando tu primer producto

Una vez arriba el servidor, el primer paso es autenticarte en el admin y crear una categoria y un producto. Pero como este es un articulo para desarrolladores, vamos directo a la API. Toda la comunicacion publica ocurre via GraphQL en /graphql. Este es un ejemplo minimo que consulta los 10 productos mas recientes:

query {
  products(limit: 10, sortBy: "created_at", sortOrder: "DESC") {
    items {
      productId
      name
      sku
      price {
        regular {
          value
          currency
        }
      }
      url
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Y asi se crea un producto via mutation, pasando el token de administrador en el header Authorization:

mutation {
  createProduct(data: {
    name: "Camiseta LATAM Dev"
    sku: "TSHIRT-LATAM-001"
    price: 19.99
    status: 1
    visibility: 1
    qty: 100
    categories: [1]
  }) {
    productId
    uuid
    name
  }
}
Enter fullscreen mode Exit fullscreen mode

Todo lo que hace el admin de EverShop ocurre contra la misma API GraphQL publica, lo que facilita construir apps moviles o integraciones externas.

Integracion en proyectos reales: crear una extension

Donde EverShop brilla es en la creacion de extensiones. Una extension es una carpeta con una estructura convencional: rutas, componentes React, resolvers GraphQL y migraciones de base. Supongamos que queremos agregar un campo maker_country a los productos para filtrar articulos «Hecho en LATAM». La estructura seria:

extensions/
  maker-country/
    bootstrap.ts
    migrations/
      Version-1.0.0.js
    graphql/
      types/
        Product.graphql
      resolvers/
        product.ts
    pages/
      admin/
        productEdit/
          MakerCountry.tsx
Enter fullscreen mode Exit fullscreen mode

El archivo de migracion agrega la columna en PostgreSQL:

const { execute } = require('@evershop/postgres-query-builder');

module.exports = exports = async (connection) => {
  await execute(
    connection,
    `ALTER TABLE product ADD COLUMN maker_country VARCHAR(64)`
  );
};
Enter fullscreen mode Exit fullscreen mode

Y el resolver expone el campo en GraphQL:

module.exports = {
  Product: {
    makerCountry: (product) => product.maker_country
  }
};
Enter fullscreen mode Exit fullscreen mode

En el archivo de tipos extendes el schema de producto:

extend type Product {
  makerCountry: String
}
Enter fullscreen mode Exit fullscreen mode

Y listo: al reiniciar el servidor la nueva columna existe, el campo aparece en GraphQL, el admin tiene un input personalizado y el storefront puede consumirlo. Este patron es identico al que usan extensiones oficiales como impuestos, promociones, cupones o envios, lo cual facilita muchisimo leer el codigo del proyecto para aprender buenas practicas.

Cuando usarlo y cuando no

EverShop no es la respuesta a todos los proyectos de e-commerce. Es importante ser honesto sobre sus puntos fuertes y sus limitaciones actuales.

  • Usalo cuando tu equipo ya vive en el ecosistema Node/TypeScript y quiere owership total del codigo. La licencia GPL-3.0 permite auto-hostearlo sin pagar licencias por cada tienda y la API GraphQL facilita construir apps moviles, paneles custom o integraciones B2B sin romper contratos.
  • Usalo cuando necesitas un storefront altamente personalizado. Como el frontend ya es React, no tenes que pelearte con templates Liquid ni con plugins PHP.
  • Usalo cuando estas construyendo un marketplace o una tienda multiregion con reglas fiscales complejas. La arquitectura modular se adapta bien a casos en los que una tienda basica tradicional se queda corta.
  • Evitalo cuando necesitas lanzar en 48 horas sin equipo tecnico. Shopify o Tiendanube te daran mejor resultado con cero codigo.
  • Evitalo cuando tu infraestructura esta anclada en WordPress o PHP. Integrar EverShop ahi significa mantener dos stacks en paralelo.
  • Evitalo cuando la licencia GPL-3.0 es un problema para tu modelo de negocio. El copyleft exige que cualquier distribucion publica mantenga el codigo abierto, lo que no siempre encaja con productos comerciales cerrados.

Alternativas

Para decidir con informacion, conviene mirar el campo completo. Estas son las tres alternativas que mas aparecen cuando alguien evalua EverShop:

  • Medusa: tambien escrita en Node.js/TypeScript y headless por diseno. Separa completamente backend y frontend y deja al desarrollador elegir el framework del storefront (Next.js, Remix, Astro). Tiene una comunidad grande y arquitectura basada en modulos. Es mas pura «headless» que EverShop, lo cual es una ventaja si ya tenes un equipo frontend independiente, pero requiere armar mas piezas.
  • Saleor: construida en Python (Django) con una API GraphQL muy madura. Esta orientada a empresas grandes y marketplaces. Su calidad tecnica es altisima, pero su stack te aleja del mundo Node si tu equipo no maneja Python.
  • WooCommerce: el rey historico del e-commerce open source. Vive dentro de WordPress (PHP + MySQL). Tiene el catalogo de plugins mas grande del mercado y una comunidad enorme, pero sufre los problemas tipicos de WordPress: performance dependiente del hosting, seguridad basada en actualizaciones manuales y dificultad para construir frontends modernos sin headless.

No hay un ganador objetivo: EverShop tiene sentido si queres un monolito modular en TypeScript con admin incluido, Medusa tiene sentido si buscas headless puro, Saleor si tu stack es Python y WooCommerce si tu infraestructura vive en WordPress.

Conclusion

EverShop representa una de las apuestas mas serias del ecosistema Node para competir con las plataformas establecidas. Su arquitectura modular, el uso de TypeScript de punta a punta, la unica API GraphQL y la presencia de un admin completo de fabrica lo convierten en una opcion muy atractiva para equipos que quieren construir comercio digital sin atarse a un SaaS cerrado. Con mas de 10.000 estrellas y una version 2.1 estable, ya esta mas alla de la fase «proyecto experimental»: varios equipos LATAM lo estan usando en produccion, y la llegada de EverShop Cloud va a reducir aun mas la friccion de entrada.

Si queres revisar el codigo, contribuir o abrir un issue, el proyecto vive en evershopcommerce/evershop. Y si preferis ver una tienda en vivo antes de instalar nada, la demo oficial esta abierta en demo.evershop.io con el usuario de prueba demo@evershop.io.

Referencias

📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.

📚 Artículos relacionados

Top comments (0)