Встановлення і налаштування Vendure (NestJS/TypeScript)

Встановлення та налаштування Vendure (NestJS/TypeScript)

Vendure встановлюється через @vendure/create або вручну. Ручне встановлення переважне для нестандартних проектів: потрібна конкретна версія, монорепозиторій або інтеграція в існуючий NestJS-проект.

Системні вимоги

• Node.js 18+ (рекомендується 20 LTS)
• PostgreSQL 12+ або MySQL 8+ (SQLite лише для розробки)
• Redis 6+ (для воркерів та сесій в production)

Встановлення через CLI

npx @vendure/create my-shop

Інтерактивний майстер пропонує:

• Вибір БД (PostgreSQL / MySQL / SQLite)
• Заповнення зразковими даними
• TypeScript або JavaScript

Результат — робочий проект із dev-скриптами.

Ручне встановлення (production-ready)

mkdir vendure-shop && cd vendure-shop
npm init -y
npm install @vendure/core @vendure/email-plugin @vendure/asset-server-plugin \
  @vendure/admin-ui-plugin @nestjs/core @nestjs/common \
  typeorm pg reflect-metadata ts-node typescript
npm install -D @types/node ts-node-dev

// tsconfig.json
{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2020",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "outDir": "dist",
    "sourceMap": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Змінні оточення

# .env
APP_ENV=development
SUPERADMIN_USERNAME=admin
SUPERADMIN_PASSWORD=changeme_in_production

DB_HOST=localhost
DB_PORT=5432
DB_NAME=vendure
DB_USER=vendure
DB_PASSWORD=vendure_secret

COOKIE_SECRET=your-32-char-secret-here

SMTP_HOST=smtp.mailgun.org
[email protected]
SMTP_PASS=smtp-password

ASSET_UPLOAD_DIR=/var/www/vendure/assets
SHOP_URL=https://shop.yourdomain.com
ADMIN_UI_URL=https://admin.yourdomain.com

Ініціалізація БД та міграції

# Згенерувати першу міграцію
npm run build
npx ts-node src/migration.ts generate src/migrations/InitialSchema

# Застосувати міграції
npx ts-node src/migration.ts run

Заповнення початковими даними

npx ts-node src/populate.ts

Запуск у розробці

// package.json scripts
{
  "scripts": {
    "dev:server": "ts-node-dev --respawn --transpile-only src/index.ts",
    "dev:worker": "ts-node-dev --respawn --transpile-only src/worker.ts",
    "dev": "concurrently \"npm run dev:server\" \"npm run dev:worker\"",
    "build": "tsc",
    "start": "node dist/index.js",
    "start:worker": "node dist/worker.js",
    "migration:generate": "ts-node src/migration.ts generate",
    "migration:run": "ts-node src/migration.ts run"
  }
}

Production розгортання (Docker Compose)

# docker-compose.yml
version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: vendure
      POSTGRES_USER: vendure
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data

  vendure-server:
    build: .
    command: node dist/index.js
    env_file: .env.production
    ports:
      - "3000:3000"
    depends_on:
      - postgres
      - redis
    volumes:
      - assets:/app/static/assets

  vendure-worker:
    build: .
    command: node dist/worker.js
    env_file: .env.production
    depends_on:
      - postgres
      - redis
    volumes:
      - assets:/app/static/assets

volumes:
  pgdata:
  redisdata:
  assets:

# Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY --from=builder /app/dist ./dist
EXPOSE 3000

Nginx reverse proxy

server {
    listen 443 ssl;
    server_name shop.yourdomain.com;

    location /shop-api/ {
        proxy_pass http://vendure-server:3000/shop-api/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location /assets/ {
        proxy_pass http://vendure-server:3000/assets/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    location /admin/ {
        proxy_pass http://vendure-server:3000/admin/;
    }
}

Контрольний список після встановлення

• БД створена, міграції застосовані
• Суперадмін створений (SUPERADMIN_USERNAME/PASSWORD в env)
• Admin UI доступний за адресою /admin
• Shop API відповідає на /shop-api?
• Директорія Assets має права запису
• SMTP налаштований (тест: створити замовлення, перевірити лист)
• Worker запущений як окремий процес
• Redis підключений (перевірити логи воркера)

Встановлення займає 4–8 годин при наявності готової інфраструктури (БД, Redis, CI/CD).