Урокі з адміністрування 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. Хукі для выклікання платежаў — раннее налаштаванне webhooks ад 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-раслужб:

• Забезпечыце працэ автанаціі і розрахункоў перад тым, як інвеставаць у выгляднае панель керування.
• TypeScript перестае быць необавязковым як толькі з’яўляюцца фінансавыя аспекты.
• Утримвацеся ад чрэзмернай централізацыі стану; большасць функцый належыць інструментам серверскага стану, а не глобальнаму хранару.

Нічыя з гэтых рашынакоў не выходзіць з прагону за найновейшай бібліятэкай. Яны выходзяць з фундаментальных прынцыпаў: спачатку неабходна чыткая рэалізацыя апраўлення дакументаў, кантрактаў на аренду і системы выклікання платы, і тады все, што следуе — рост, новыя функцыі, масштабаванне — стае набліжна простым для дадатковага розвіцця.

Калі сама наладка становіцца вузкам местам

Той самы інстынкт падбірваць павторныя, схильныя да адмылакоў наладчыкія задачы ў канечнай лініі ведае да автаматызацыі самых базавых крокаў. Кожны разработчык фронтэнду знае гэты рутын: вы ствараеце новы проект за дапамогою 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, урок застаецца тым самым: тыя часткі проекта, якія здаюцца найбольш труднымі — аутэнтыкацыя, аренда, білінг, структура папак — якраз тыя часткі, якія варта правільна налаштаваць, а часта і автоматызаваць, перш чым прыступаць да чаго-небудзь іншага.