NextNodeTemplate/docs/KNOWLEDGE_BASE.md

База знаний проекта

Назначение шаблона

Это шаблон проекта для быстрого старта новых проектов с:

• Next.js фронтендом (App Router)
• Express.js бэкендом
• TypeScript
• Tailwind CSS
• Модульной архитектурой

Архитектура системы

Frontend (Next.js)

Структура:

frontend/
  app/               # Next.js App Router страницы
    page.tsx         # Главная страница
    layout.tsx       # Общий layout
  components/        # React компоненты
  lib/               # Утилиты и типы
  docs/              # Документация фронтенда

Технологии:

• Next.js 15.3.3 с App Router
• React 19
• TypeScript 5
• Tailwind CSS 4
• Статический экспорт (output: 'export')

Backend (Express)

Структура:

backend/
  server.js          # Основной файл сервера
  routes/            # API маршруты (создавать по мере необходимости)

Технологии:

• Express.js 5
• body-parser для обработки запросов

Типы данных

Все типы должны быть определены явно. Используй интерфейсы для сложных структур:

// Пример: frontend/lib/types.ts
export interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

export interface User {
  id: string;
  name: string;
  email: string;
}

API интеграция

Определение URL

Фронтенд автоматически определяет URL API:

const isLocalhost = typeof window !== 'undefined' && window.location.hostname === 'localhost';
const apiUrl = isLocalhost
  ? 'http://localhost:3001/api'
  : 'https://your-api-domain.com/api';

Пример запроса

async function fetchData() {
  try {
    const response = await fetch(`${apiUrl}/endpoint`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ data: 'value' }),
    });
    
    if (!response.ok) {
      throw new Error('Server error');
    }
    
    const result = await response.json();
    return result;
  } catch (err) {
    console.error('API Error:', err);
    throw err;
  }
}

Добавление новых функций

Frontend компонент

1. Создать компонент в frontend/components/:

// components/MyComponent.tsx
export default function MyComponent() {
  return <div>Content</div>;
}

2. Использовать в странице:

// app/page.tsx
import MyComponent from '@/components/MyComponent';

Backend endpoint

1. Добавить маршрут в backend/server.js или создать отдельный файл в backend/routes/:

// backend/server.js
app.post('/api/my-endpoint', (req, res) => {
  try {
    const { data } = req.body;
    // Обработка данных
    res.json({ success: true, result: data });
  } catch (err) {
    res.status(500).json({ success: false, error: err.message });
  }
});

Окружение разработки

Платформы

• Разработка: Windows с PowerShell
• Хостинг: Ubuntu Linux

Особенности разработки на Windows

• PowerShell не поддерживает оператор && для цепочки команд
• Используйте ; или выполняйте команды отдельно
• Пути в Git и конфигах всегда используют /, даже на Windows
• При работе через SSH используйте Linux команды

Локальная разработка (Windows + PowerShell)

# Frontend - один терминал
cd frontend
npm install
npm run dev

# Backend - отдельный терминал
cd backend
npm install
node server.js

Деплой

Сервер

• ОС: Ubuntu Linux
• IP: (настройте под себя)
• Пользователь: (настройте под себя)
• Путь: ~/projects/
• Управление процессами: PM2

Процессы PM2

• <app-name>-frontend - Next.js приложение (статические файлы через serve или nginx)
• <app-name>-backend - Express сервер

Команды деплоя

С локального Windows (PowerShell):

# Отправить изменения
git push origin dev

# Подключиться и обновить сервер (Ubuntu команды через SSH)
ssh user@server-ip "cd ~/projects/<project-name> && git pull origin dev && cd frontend && npm run build && pm2 restart <app-name>-frontend <app-name>-backend"

Или на сервере напрямую (Ubuntu):

cd ~/projects/<project-name>
git pull origin dev
cd frontend && npm run build
pm2 restart <app-name>-frontend <app-name>-backend

Настройка PM2

Создайте ecosystem.config.js в корне проекта:

module.exports = {
  apps: [
    {
      name: 'my-app-frontend',
      script: 'serve',
      args: '-s frontend/out -p 3000',
      cwd: './',
      env: {
        NODE_ENV: 'production'
      }
    },
    {
      name: 'my-app-backend',
      script: 'server.js',
      cwd: './backend',
      env: {
        NODE_ENV: 'production',
        PORT: 3001
      }
    }
  ]
};

Запуск: pm2 start ecosystem.config.js

Обработка ошибок

API запросы

try {
  const response = await fetch(apiUrl, { method: 'POST', body: formData });
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data = await response.json();
  return data;
} catch (err) {
  console.error('API Error:', err);
  // Показать сообщение пользователю
  throw err;
}

Backend

app.post('/api/endpoint', (req, res) => {
  try {
    // Обработка
    res.json({ success: true, data: result });
  } catch (err) {
    console.error('Error:', err);
    res.status(500).json({ success: false, error: err.message });
  }
});

Известные особенности

1. Статический экспорт: Next.js собирается в статические файлы, нет серверного рендеринга
2. CORS: Настроен для разработки, адаптируйте под продакшн
3. Порты: Frontend 3000, Backend 3001 по умолчанию