Уроки, отримані під час розробки SaaS на Next.js та створення CLI для шаблонів проектів.

Розробка справжнього SaaS-продукту з використанням React та Next.js — це не стільки вибір модного фреймворку, скільки правильне прийняття десятків непомітних рішень ще до того, як ви почнете працювати з панеллю керування. Та сама дисципліна, яка забезпечує стабільність архітектури продукту серед реальних клієнтів, проявляється навіть у таких буденних завданнях, як створення нового проекту на Next.js — саме тому власний інструмент CLI для генерації шаблонів допомагає засвоїти ту саму лекцію, що й розробка самого SaaS: саме нудна налаштовувальна робота визначає, чи досягне проект успіху, чи зазнає невдачі.

Вибір технологій, які не уповільнять вас

Після розробки кількох SaaS-продуктів технологічна стеку зазвичай набуває передбачуваної форми:

1. Next.js як єдиний фреймворк для маршрутизації, серверної обробки та API-шляхів, що дозволяє уникнути використання окремих інструментів для кожної функції.

TypeScript — це обов’язкова умова, особливо там, де знаходиться логіка оплати; саме такі помилки ви не хочете, щоб з’являлися під час роботи програми.

Tailwind CSS для стилізації, головним чином тому, що він усуває постійну боротьбу з проблемою специфічності CSS.

Redux Toolkit або Zustand — використовуються лише для стану, який справді потребує глобального обміну між компонентами.

Жоден з цих виборів не робиться заради новизни. Разом вони дозволяють невеликій команді працювати швидко, не накопичуючи при цьому технічний борг, який вони ніколи не зможуть погасити.

Спочатку створіть прості основи

Засновникам легко хочеться одразу приступити до створення панелей керування. Протистояйте цьому бажанню. Перш ніж створювати щось для користувача, необхідно налаштувати ці три елементи:

1. Аутентифікація — реалізована за допомогою справжніх сесій, а не просто токенів, які зберігаються у localStorage.
2. Багатоклієнтська архітектура — навіть якщо зараз у вас є лише один клієнт, проектуйте систему з урахуванням кількох клієнтів з самого початку.
3. Хуків для билінгу — рання налаштування webhook-ів від Stripe допомагає уникнути складної переробки після справжнього запуску продукту.

Ось шаблон, який варто використовувати для здійснення API-запитів у межах окремих клієнтів, щоб не повторювати код:

// hooks/useTenantFetch.ts
import { useCallback } from "react";
import { useSession } from "next-auth/react";

export function useTenantFetch() {
  const { data: session } = useSession();

  const fetchScoped = useCallback(
    async (endpoint: string, options: RequestInit = {}) => {
      if (!session?.tenantId) throw new Error("No active tenant");

      const res = await fetch(`/api/${session.tenantId}${endpoint}`, {
        ...options,
        headers: {
          ...options.headers,
          "Content-Type": "application/json",
        },
      });

      if (!res.ok) throw new Error(`Request failed: ${res.status}`);
      return res.json();
    },
    [session]
  );

  return { fetchScoped };
}

Це невелика утиліта, але вона допомагає уникнути розкидання перевірок ідентифікаторів клієнтів у десятках компонентів пізніше.

Визначення того, що належить до глобального стану

Не кожен фрагмент даних заслуговує на місце в Redux. Один інженер, який працює у стартапі, підтримуваному Y Combinator, добре це сформулював: глобальний стан — це борг, який з часом нарощує відсотки. Використовуйте Redux (або інший ваш вибраний глобальний сховище) лише для того, що справді стосується всього інтерфейсу — модалів, флагів функцій, переваг користувача — а все інше, що насправді є просто даними з сервера під маскуванням, нехай обробляє React Query або SWR.

Кілька ключових порад підсумовують аспекти створення SaaS-продуктів:

• Спочатку налаштуйте автентифікацію та систему оплати, перш ніж інвестувати у вдосконалений інтерфейс.
• Типовий JavaScript перестає бути необов’язковим у момент, коли залучаються гроші.
• Утримуйтеся від надмірної централізації стану; більшість функцій належать до інструментів для керування даними на сервері, а не до глобального сховища.

Усе це не є наслідком погоні за найновішою бібліотекою. Це походить з основ: якщо з самого початку належним чином реалізувати автентифікацію, систему оренди та облік оплат, усе інше — зростання, нові функції, масштабування — стає набагато простішим для розробки.

Коли сама налаштування стає вузьким місцем

Саме цей інстинкт усувати повторювану та схильну до помилок роботу з налаштуванням зрештою призводить до автоматизації цих базових кроків. Кожен фронтенд-розробник знає цю рутину: спочатку створюється скелет нового проекту за допомогою create-next-app, а потім починається справжня нудна робота. Потрібно створити папку components, розділити ui від features, налаштувати hooks, під’єднати спільні types, написати допоміжні функції, налаштувати псевдоніми шляхів та організувати ієрархію папок — і може минути година, перш ніж буде написана хоча б одна рядок справжньої бізнес-логіки.

Після того, як цей ритуал було виконано занадто багато разів, наступним логічним кроком стало автоматизування цього процесу, що призвело до появи першого опублікованого пакета з відкритим кодом для npm: nexarch-cli.

Основна проблема

Стандартні шаблони стартування Next.js надають порожню основу, а не архітектуру, готову до використання у продакшені. Сучасні додатки зазвичай потребують:

• Чіткого розділення логіки відображення та бізнес-логіки
• Модульного групування за функціями
• Масштабованих визначень типів та функціональних обгорток
• Єдиних правил, яких може дотримуватися вся команда

Створення всього цього вручну для кожного прототипу чи проекту клієнта є повільним, непослідовним та схильним до помилок.

Що насправді робить nexarch-cli

nexarch-cli — це інтерактивний інструмент командного рядка, створений для швидкого побудови чистої, модульної архітектури Next.js протягом кількох секунд. Замість того, щоб вручну створювати вкладені папки та файли-замінники, ви відповідаєте на кілька запитань у терміналі, і інструмент створює для вас базову структуру.

Його основні функції включають:

• Інтерактивне створення структури за допомогою простих запитань у терміналі, адаптованих під ваші потреби.
• Модульна архітектура із заздалегідь налаштованими конвенціями для розширення у міру зростання додатку.
• Не потрібна глобальна установка — він запускається за потреби через npx.
• Відповідність сучасним конвенціям Next.js та React, що забезпечує послідовність структури каталогів згідно з сучасними практиками.

Запуск інструменту

Немає потреби встановлювати щось глобально. Ви можете запустити його безпосередньо:

npx nexarch-cli

Як тільки ви відповісте на запитання, структура вашого проекту буде створена та готова до фактичної розробки.

Уроки створення першого CLI

Створення та публікація цього інструменту як першого інструменту для розробників супроводжувалося складним процесом навчання. Ось кілька важливих уроків:

• Інтерфейс користувача терміналу настільки ж важливий, як і сам код. Чисте завершення процесів, зрозумілі запитання та чіткі повідомлення про помилки мають таке ж значення, як і логіка створення файлів.
• Операції з файловою системою приховують багато непередбачуваних ситуацій. Написання рекурсивних функцій для створення каталогів та шаблонів файлів, які будуть коректно працювати на різних операційних системах, вимагає ретельних та повторюваних тестів.

Пакування для npm має свою власну навчальну криву. Правильна налаштування бінарних файлів package.json (bin), робота з дозволами файлів за допомогою chmod та підтримання мінімального обсягу залежностей демонструють, як насправді працюють інструменти CLI, засновані на Node.

Яким є статус проекту зараз

Цей інструмент все ще знаходиться на початковій стадії розвитку як проект з відкритим кодом, тож йому корисні зовнішні пропозиції під час формування. Код знаходиться за адресою github.com/CaffeineLogs/nexarch-cli, а опублікований пакет можна знайти в реєстрі npm під назвою nexarch-cli.

Будь-хто, у кого інший варіант структури проекту, або хто стикається з ситуаціями, які ще не ефективно вирішуються інструментами, може задати про це питання у репозиторії. Пропозиції щодо подальших кроків — наприклад, стандартизовані налаштування стилів чи готові параметри керування станом — також будуть корисними як теми для обговорення чи коментарі.

Чи ви вирішуєте, що має бути частиною Redux, чи плануєте структуру нового проекту на базі Next.js, усе зводиться до одного: ті частини проекту, які здаються найскладнішими — автентифікація, управління користувачами, билінг, структура папок — саме ті, які варто правильно налаштувати, а часто й автоматизувати, перш ніж приступати до чогось іншого.