Գնահատել նախագիծը
← Բոլոր հրապարակումները

Ժամանակակից full stack հավելվածի ճարտարապետության կառուցում Next.js 15+-ով

Այս հոդվածը քայլ առ քայլ ներկայացնում է Next.js 15-ով կառուցված ժամանակակից full stack հավելվածի ճարտարապետությունը՝ TypeScript, Server Actions, Server և Client Components, Auth.js, Tailwind CSS, Drizzle ORM, PostgreSQL և Docker տեխնոլոգիաների հետ միասին։

21 րոպե
ՃարտարապետությունFull stackReactֆրեյմվորքներNext.Js

Արդեն շատ տարիներ React գրադարանը մեծ հանրաճանաչություն է վայելում frontend աշխարհում։ Այն թույլ է տալիս ծրագրավորողներին ստեղծել ինտերակտիվ օգտատիրոջ ինտերֆեյսներ վերօգտագործվող բաղադրիչներից, որոնք կարելի է իրար հետ համադրել։ Այս մոդուլային մոտեցման շնորհիվ հավելվածը մասշտաբավորվող է և հեշտ պահպանվող։

Լինելով գրադարան՝ React-ը ծրագրավորողներին է թողնում ընտրել լրացուցիչ գործիքներ այնպիսի բաների համար, ինչպիսիք են երթուղավորումը, վիճակի կառավարումը, տվյալների ստացումը, քեշավորումը կամ էջերի ռենդերինգի ռազմավարությունները։ Այս ճկունությունը շատ ազատություն է տալիս։ Գործնականում, սակայն, այն հանգում է ճարտարապետական որոշումներ կայացնելուն. ինչպես կազմակերպել պանակներն ու ֆայլերը, ինչ անվանման կանոններ պահպանել, ինչպես պաշտպանել հավելվածը SSR մակարդակում, ինչպես մոտենալ SEO-ին և, վերջապես, ինչպես հոգ տանել ծրագրավորողի փորձառության մասին։ Արդյունքում ծրագրավորողները ստիպված են ժամանակ ծախսել գործիքներ կարգավորելու և հավելվածների ընդհանուր պահանջների համար լուծումներ նորից հայտնագործելու վրա։

Ներածություն

Այն ֆրեյմվորքներից, որոնք նման կոնֆիգուրացիա և գործիքակազմ տալիս են «արկղից դուրս», Next.js-ը առաջատարն է։ Այն այժմ ամենահասուն ֆրեյմվորքն է, ինչը այն դարձնում է բավականին ակնհայտ ընտրություն, հատկապես React ծրագրավորողների կամ այն բոլորի համար, ովքեր ուզում են հավելվածներ կառուցել React էկոհամակարգում։

Next.js-ը սերվերային ռենդերինգը (SSR) դիտարկում է որպես իր հիմնական ռենդերինգի տեխնիկա։ Այն նաև աջակցում է ստատիկ կայքերի գեներացում (SSG), աստիճանական ստատիկ վերագեներացում (ISR) և կլիենտային ռենդերինգ (CSR)։ Դրանից բացի, այն առաջարկում է React Server Components (RSC) և React Server Functions (RSF) որպես հիմնարար ճարտարապետական շինանյութեր։ Next.js-ը թույլ է տալիս նաև ազատորեն համադրել այս ռենդերինգի տեխնիկաները. օրինակ՝ landing էջը կարող է հենվել SSG-ի վրա, իսկ նույնականացմամբ հավելվածը (dashboard)՝ SSR-ի։

React-ը ինքնին թույլ է տալիս կառուցել հավելվածներ, որոնք աշխատում են բացառապես կլիենտի կողմում։ Եթե նման հավելվածին backend է պետք (օրինակ՝ տվյալների բազայի հարցումները կամ նույնականացումը մշակելու համար), այդ backend-ը պետք է կառուցվի առանձին և ինտեգրվի React հավելվածին։ Next.js-ը, ընդհակառակը, հնարավորություն է տալիս կառուցել full-stack հավելվածներ՝ թույլ տալով ծրագրավորողին աշխատել և frontend-ի, և backend-ի վրա մեկ ֆրեյմվորքի շրջանակում։

Next.js-ի հիմնական հնարավորությունները

  1. SSR – էջերի սերվերային ռենդերինգի ներկառուցված աջակցություն, որը բարձրացնում է արտադրողականությունը և SEO-ն
  2. SSG – ստատիկ կայքերի գեներացման աջակցություն, որի ժամանակ էջերը ստեղծվում են կոմպիլյացիայի ժամանակ և մատուցվում որպես ստատիկ HTML ֆայլեր՝ արագացնելով բեռնումը և թեթևացնելով սերվերի բեռը
  3. Կոդի ավտոմատ բաժանում – Next.js-ը կոդը բաժանում է ավելի փոքր, ավելի կառավարելի մասերի՝ արտադրողականությունն ու բեռնման ժամանակը օպտիմալացնելու համար
  4. CSS աջակցություն – CSS լուծումների մի շարք աջակցություն, այդ թվում՝ CSS մոդուլներ, CSS-in-JS գրադարաններ և գլոբալ CSS ոճեր, ինչը ճկունություն է տալիս հավելվածի ոճավորման հարցում
  5. Տվյալների ստացում – տվյալների ստացման մի քանի եղանակների աջակցություն կոմպիլյացիայի կամ հարցման ժամանակ
  6. Երթուղավորում – զգալիորեն պարզեցված է ֆայլերի կառուցվածքի և էջերի պանակների հիման վրա երթուղիների ավտոմատ գեներացմամբ
  7. Պատկերների օպտիմալացում – պատկերների ավտոմատ չափափոխում և սեղմում՝ բեռնման օպտիմալ արտադրողականություն ապահովելու համար
  8. CSS-ի և JavaScript-ի ներկառուցված փաթեթավորում – CSS-ը և JS-ը ավտոմատ օպտիմալացվում և փաթեթավորվում են, որպեսզի ավելի արդյունավետ բեռնվեն
  9. API proxy – թույլ է տալիս ստեղծել API երթուղիներ, որոնք գործում են որպես երրորդ կողմի API-ների proxy՝ օգնելով տվյալների ստացմանը և անվտանգությանը
  10. Միջազգայնացման աջակցություն – Next.js-ը առաջարկում է գործիքներ և գրադարաններ մի քանի լեզուների աջակցության համար

Հաշվի առնելով այս հնարավորություններն ու առավելությունները՝ արժե հարցնել, թե երբ է իմաստ ունենում ընտրել այս ֆրեյմվորքը սովորական React-ի փոխարեն։ Next.js-ը օգտակար է բովանդակությամբ հարուստ կայքերի համար, ինչպիսիք են բլոգները կամ էլեկտրոնային առևտուրը, որտեղ SEO-ն նույնպես շատ կարևոր է։ Next.js-ը կարող է նկատելիորեն բարելավել հավելվածի արտադրողականությունը, քանի որ օգտատերը ստիպված չէ իր սարքում ներբեռնել և կատարել մեծ քանակությամբ JS, ինչը հատկապես կարևոր է ավելի դանդաղ սարքերի կամ ցանցերի դեպքում։

Ուրեմն սովորական React-ով մնալն ավելի լավ տարբերակ է, երբ գործ ունենք՝

  • Միկրոսերվիս ճարտարապետության կամ backend-ից մեծապես կախված տրամաբանության հետ
  • Իրական ժամանակի թարմացումներից մեծապես կախված հավելվածի հետ
  • Խիստ հարմարեցված օգտատիրոջ ինտերֆեյսի հետ՝ անիմացիաներով, փոխազդեցություններով և բարդ դասավորություններով

Ներածությունն ավարտվեց, ժամանակն է անցնել մանրամասներին։ Կանցնեմ այն մնացած հասկացությունների միջով, որոնք ծրագրավորողը պետք է նկատի ունենա Next.js հավելված կառուցելիս, ստեղծելով և կարգավորելով մի հավելված, որը կատարում է CRUD գործողություններ հոդվածների վրա՝ նույնականացումը ներառյալ։

Նախագծի սկիզբ

Տերմինալում.

npx create-next-app@latest

Հրամանը կատարվելուց հետո պատասխանում ենք մի քանի հարցի, և կարճ ժամանակ անց մեզ պետք եղած ամեն ինչ ավտոմատ կարգավորված է։

Նախագծի կառուցվածքը

Հարցերից մեկը հարցնում է, թե որ router-ն օգտագործել։ Next.js-ը երկու տեսակ է առաջարկում.

  1. App Router – ավելի նոր router, որն աջակցում է React-ի նոր հնարավորություններ, ինչպիսիք են Server Components-ը և Server Actions-ը,
  2. Pages Router – հենվում է ֆայլային համակարգի router-ի վրա, որը յուրաքանչյուր ֆայլը համապատասխանեցնում է երթուղու։ 13-րդ տարբերակը մինչև այն երթուղիներ ստեղծելու հիմնական եղանակն էր, և նոր տարբերակները դեռ աջակցում են այն։

Մինչև Next.js-ը App Router-ը ներմուծեց, հավելվածի ներսում երթուղավորումը կառուցված էր Pages Router-ի վրա։ Ըստ էության, այն հենվում էր Next.js-ում ներկառուցված React Router-ի վրա՝ էջերի միջև նավիգացիան ավտոմատ մշակելու համար։

Pages Router տեխնիկայով pages պանակում ստեղծում եք .js կամ .ts ֆայլեր, և Next.js-ը դրանք ավտոմատ վերածում է հավելվածի ենթաէջերի։ Օրինակ՝ pages/users.ts կառուցվածք ստեղծելը /users հասցեով էջ է ստեղծում։

Երբ Pages Router-ում հարցումը պետք է գնա սերվեր, pages ֆայլերի ներսում կարելի է օգտագործել getServerSideProps կամ getStaticProps մեթոդները։

App Router-ը՝ ավելի նոր մոտեցումը (13-րդ տարբերակից) և խորհուրդ տրվածը, ծրագրավորողներին ավելի շատ վերահսկողություն և ճկունություն է տալիս։ Այն երթուղիները սահմանում է պանակներով, ինչը հնարավորություն է տալիս առավել առաջադեմ հնարավորությունների, ինչպես ներդրված layout-ները։

app/users/page.ts կառուցվածքի դեպքում էջը լռելյայն server component է (աշխատում է սերվերում), և /users ուղին դառնում է երթուղին։ Կարող եք նաև ստեղծել layout-ներ, որոնք ընդհանուր են մի քանի երթուղու համար, ինչը օգնում է պահպանել դիզայնի և կառուցվածքի հետևողականությունը ողջ հավելվածում։

Next.js-ը հատուկ իմաստ է տալիս որոշ վերապահված պանակների և ֆայլերի անուններին։ Պանակների համար դրանք ներառում են src, public, app, [folder], […folder]։ Ֆայլերի համար օրինակներն են (համապատասխանաբար .ts, .js, .tsx, .jsx ընդլայնումներով)՝ middleware, layout, page, loading, error։ Դրանց տեղը նախագծի կառուցվածքում որոշում է, թե ինչպես են էջերն ու բաղադրիչները ռենդերվում և ինչպես է վարվում հավելվածն ամբողջությամբ։

Ավելի մանրամասն տեղեկություն կգտնեք այստեղ՝ նախագծի կառուցվածքը և կազմակերպումը

Server Actions

Նոր մոտեցմամբ սերվերային աշխատանքը, ինչպիսին է տվյալների ստացումը, ձևերի ուղարկումը և տվյալների բազայի հետ փոխազդեցությունը, մշակվում է Server Actions-ի միջոցով։ App Router-ում յուրաքանչյուր հարցում լռելյայն սերվերային է, ինչը պարզեցնում է սերվերի հետ հաղորդակցությունը՝ նախքան էջը ռենդերվելը։ Server Actions-ը կարելի է կանչել և Server, և Client Components-ից։

Server Actions-ը հայտարարվում են ‘use server’ դիրեկտիվով։ Next.js-ին պետք է ասել, որ ֆունկցիան, կամ ֆայլի յուրաքանչյուր export-ը, պետք է դիտարկվի որպես Server Action։ Առանց այս դիրեկտիվի Next.js-ը չի կարող որոշել՝ ֆունկցիան լոկալ է (օգտագործվում է միայն server component-ների կողմից), թե պետք է բացահայտվի որպես Server Action, որը կլիենտը կարող է կանչել։ Սա դիտավորյալ է, քանի որ Next.js-ը թույլ է տալիս Client և Server Components-ը խառնել հիբրիդային եղանակով, և միայն ‘use server’ դիրեկտիվով նշված ֆունկցիաները կարող են կանչվել կլիենտից։

Օրինակ.

'use server';

import { eq } from 'drizzle-orm';
import db from '@/db';
import { articles } from '@/db/schema';

export async function getArticleBySlug(slug: string) {
  return await db.query.articles.findFirst({
    where: eq(articles.slug, slug),
  });
}

‘use server’ դիրեկտիվի շնորհիվ getArticleBySlug ֆունկցիան կարելի է կանչել երկուսից էլ.

Server Component.

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const data = await getArticleBySlug(slug);
  // ...
}

և Client Component-ից (օրինակ՝ ֆունկցիան որպես callback փոխանցելով իրադարձության handler-ին կամ useEffect-ի ներսում).

կամ.

'use client';

import { createArticle } from '@/lib/actions/article.actions';
// ...

export const ArticleForm = () => {
  return (
    <form action={createArticle}>
    {/* ... */}
    <button type='submit'>Create</button>
    </form>
  );
};

կամ.

'use client';

import { createArticle } from '@/lib/actions/article.actions';
// ...

export const ArticleForm = () => {
  return (
    <>
    {/* ... */}
    <button
        onClick={async () => {
        const formData = new FormData();
        formData.append('title', 'Article title');
        await createArticle(formData);
        }}
    >
        Create
    </button>
    </>
  );
};

Առանց ‘use server’ դիրեկտիվի Next.js-ը կարող է նման ֆունկցիան դիտարկել որպես սովորական օժանդակ ֆունկցիա։ Արդյունքում այն չի գրանցվի որպես Server Action և չի կարող դինամիկ կերպով կանչվել Client Component-ից։

‘use server’ դիրեկտիվը կարելի է դնել կամ ասինխրոն ֆունկցիայի վերևում՝ նշելով այդ ֆունկցիան որպես Server Action, կամ առանձին ֆայլի վերևում՝ նշելով այդ ֆայլի յուրաքանչյուր export-ը որպես Server Action.

// Directive at the top of a separate file
'use server';

export async function createArticle(article: Article): Promise<ReturnType> {
  const parsedArticle = articleFormSchema.parse(article);

  if (!parsedArticle.success) return { message: 'Something went wrong' };

  return { message: 'Article created' };
}

// Directive at the top of an async function
export function Page() {
  const createArticle = async () => {
    'use server';
    // ...
  };

  return <form action={createArticle}>...</form>;
}

Server և Client Components

Եկեք հիմա անդրադառնանք այն հարցին, թե երբ դիմել Client, և երբ՝ Server Components-ին։

Layout-ներն ու էջերը լռելյայն Server Components են։ Սա թույլ է տալիս հարցումներ ուղարկել սերվերից և օգտատիրոջ ինտերֆեյսի մասերը ռենդերել այնտեղ՝ ըստ ցանկության քեշավորելով արդյունքները և փոխանցելով դրանք կլիենտին։ Client Components-ը, մյուս կողմից, ընտրություն են, երբ ինտերակտիվություն կամ բրաուզերի API-ին հասանելիություն է պետք։ Client Component ստեղծելու համար ֆայլի վերևում՝ import-ներից վերև, ավելացնում եք ‘use client’ դիրեկտիվ։ Երբ ֆայլն ունի ‘use client’ դիրեկտիվը, այն ամենը, ինչ ներմուծում է, և նրա բոլոր ենթաբաղադրիչները դառնում են կլիենտային bundle-ի մաս։ Սա նաև նշանակում է, որ պարտադիր չէ ‘use client’ դիրեկտիվ դնել կլիենտի համար նախատեսված յուրաքանչյուր բաղադրիչում։

Երբ օգտագործել Client Components.

  • Բաղադրիչի վիճակի կառավարում և իրադարձությունների մշակում (օր.՝ onClick, onChange)
  • Բաղադրիչի կյանքի ցիկլի օգտագործում (օր.՝ useEffect)
  • Բրաուզերի API-ին հասանելիություն (localStorage, window, geolocation)
  • Custom hook-եր

Երբ օգտագործել Server Components.

  • Տվյալների բազայի հետ աշխատանք
  • Աշխատանք API բանալիների, token-ների և այլ զգայուն տվյալների հետ, որոնց կլիենտը չպետք է հասանելիություն ունենա
  • Բրաուզերին ուղարկվող JavaScript-ի քանակի նվազեցում
  • First Contentful Paint-ի բարելավում և բովանդակության աստիճանական հոսքային փոխանցում կլիենտին

Փաթեթների կառավարիչ

Նախագիծը նախապատրաստելու համար օգտագործեցինք npx հրամանը, որը npm ռեեստրից Node.js փաթեթներ է գործարկում «թռչելիս»՝ առանց դրանք գլոբալ տեղադրելու։ Փաթեթների կառավարիչների մեջ npm-ն ամենալայն օգտագործվողն է, մեծ մասամբ այն պատճառով, որ գալիս է Node.js-ի յուրաքանչյուր տեղադրման հետ։ Այդուհանդերձ, yarn-ը, pnpm-ը և bun-ը լավ այլընտրանքներ են. հատկապես pnpm-ը՝ իր ավելի լավ արտադրողականության շնորհիվ։

Եթե երբևէ պետք լինի կառուցել մի քանի հավելված, որոնք կախված են իրարից կամ կիսում են բաղադրիչների ընդհանուր հավաքածու, monorepo-ն արժե դիտարկել։ Այս նպատակով լավ կարող են աշխատել այնպիսի գործիքներ, ինչպիսիք են Nx-ը կամ Turborepo-ն։

Linter և կոդի ֆորմատավորիչ

Նախագիծը նախապատրաստելուց հետո հաջորդ արժեքավոր քայլը կոդի միատեսակ ոճ ապահովելն է։ Այստեղ օգնում է ESLint linter-ը. այն պարտադրում է կոդի որոշակի ոճ և մեր IDE-ում սխալ է նշում, երբ սահմանված կանոնները խախտվում են։

Այն պետք է լրացվի կոդի ֆորմատավորիչով, ինչպիսին Prettier-ն է, որը կարելի է կարգավորել, որ կոդը ֆորմատավորի՝ հետևելով որոշակի կանոնների՝ ֆայլը պահպանելու ամեն անգամ։ Prettier-ը չի փոխարինում ESLint-ին, բայց երկուսը լավ ինտեգրվում են։

Փաթեթը տեղադրեք այսպես.

npm install --save-dev eslint-config-prettier

Հետո ավելացրեք փաթեթը ESLint-ի կոնֆիգուրացիայի ֆայլում (eslint.config.mjs)։

Այդ ընթացքում մի՛ մոռացեք տեղադրել փաթեթ, որը import հայտարարությունները դասավորում է սահմանված կարգով։ Օրինակ՝ երրորդ կողմի գրադարանները գնում են առաջինը, հետո alias import-ները և վերջում հարաբերական import-ները՝ խմբերը բաժանող դատարկ տողերով, ինչը ֆայլի այս մասը պահում է կարգավորված և ընթեռնելի.

npm install --save-dev @trivago/prettier-plugin-sort-imports

Հաջորդը՝ ավելացրեք փաթեթը .prettierrc.json ֆայլի plugins ցանկում և սահմանեք դասավորման կանոնները.

{
  "importOrder": [
    "^(react|next?/?([a-zA-Z/]*))$",
    "<THIRD_PARTY_MODULES>",
    "^@/(.*)$",
    "^[./]"
  ],
  "importOrderSeparation": true,
  "importOrderSortSpecifiers": true,
  "plugins": ["@trivago/prettier-plugin-sort-imports"]
}

Ոճավորում

Հավելվածը գալիս է պատրաստ Tailwind CSS-ի համար։ Բնականաբար, ինչպես ոճավորել հավելվածը, կախված է ձեր կարիքներից և ճաշակից։ Այդուհանդերձ, այս ֆրեյմվորքն արժե փորձել utility դասերի իր մոտեցման պատճառով, որոնք հեշտությամբ համադրվում են ցանկացած նախագիծ կառուցելու համար։ Tailwind CSS-ին առանձնացնում է այն, որ պատրաստի բաղադրիչներ տալու փոխարեն մեզ տալիս է սեփական բաղադրիչները կառուցելու գործիքներ։

Ավանդական մոտեցումը հենվում էր այնպիսի դասերի վրա, ինչպիսիք են container, section-wrapper, accordion, heading-1, notification և նմանները։ Tailwind CSS-ը այս տեսակի դասեր չունի. փոխարենը առաջարկում է պարզ գործիքների հավաքածու՝ flex (որը սահմանում է display: flex), w-screen (width: 100vw), text-lg (որը սահմանում է և որոշակի font-size, և որոշակի line-height) և այլն։ Խորհուրդ եմ տալիս կարդալ փաստաթղթերը։

Տարբեր նախագծեր ունեն օգտատիրոջ ինտերֆեյսի ոճավորման տարբեր պահանջներ՝ սկսած սահմանված դիզայն համակարգից, որը պահանջում է հատուկ բաղադրիչներ, մինչև ավելի ճկուն մոտեցում, որտեղ պատրաստի լուծումները բավարար կլինեն։ Այսօրվա հանրաճանաչ բաղադրիչների գրադարաններից մեկը shadcn/ui-ն է, որը պատրաստի բաղադրիչներ է կառուցում Tailwind-ի պարզ դասերից։ Ավելին, այն չի տեղադրվում որպես նախագծի կախվածություն. փոխարենը կոդը դրվում է components պանակում՝ մեզ տալով հասանելիություն սկզբնական կոդին։ shadcn/ui բաղադրիչները գալիս են հիմնական ոճավորմամբ, ուստի հեշտ է դրանք հարմարեցնել հավելվածի դիզայնին։

Այլ ուշագրավ գրադարաններ են.

Միջավայրի փոփոխականների հետ աշխատանք

Հաջորդը՝ դիտարկենք միջավայրի փոփոխականների հետ աշխատանքի կարգավորումը։ Լռելյայն Next.js-ը վերցնում է նախագծի .env ֆայլը և բեռնում դրանում սահմանված միջավայրի փոփոխականները՝ դարձնելով դրանք հասանելի process.env-ի միջոցով։ Սակայն կարող է պատահել, որ փոփոխականը բացակայի կամ սխալ տիպի լինի. օրինակ՝ պորտի համարը պետք է թիվ լինի, ոչ թե տող։ Միջավայրի փոփոխականները տիպերով անվտանգ կերպով և ավտոմատ վալիդացիայով մշակելու համար արժե դիմել Zod գրադարանին, որը թույլ է տալիս սահմանել անհրաժեշտ փոփոխականների սխեմա և վալիդացնել դրանք հավելվածի գործարկման ժամանակ։

Կարող ենք սա մեկ քայլ առաջ տանել T3 Env գրադարանով, որը կառուցված է Zod-ի վրա և նախագծված է հատուկ TypeScript/Next.js նախագծերում միջավայրի փոփոխականների կառավարման համար։ Այն նաև թույլ է տալիս առանձին պահել կլիենտային և սերվերային փոփոխականները։

Տեղադրում.

npm install @t3-oss/env-nextjs zod

src/env/server.ts ֆայլում սահմանում ենք սերվերին հատուկ միջավայրի փոփոխականների սխեմա.

import { createEnv } from "@t3-oss/env-nextjs";
import "dotenv/config";
import { z } from "zod";

export const env = createEnv({
  server: {
    NODE_ENV: z.enum(["development", "production"]),
    AUTH_GOOGLE_ID: z.string(),
    AUTH_GOOGLE_SECRET: z.string(),
    SESSION_SECRET: z.string(),
    DATABASE_URL: z.string().url(),
    CLOUDINARY_NAME: z.string(),
    CLOUDINARY_KEY: z.string(),
    CLOUDINARY_SECRET: z.string(),
  },
  onValidationError: (issues) => {
    console.error("❌ Invalid environment variables:", issues);
    process.exit(1);
  },
  emptyStringAsUndefined: true,
  experimental__runtimeEnv: process.env,
});

Անհրաժեշտության դեպքում կլիենտի համար կպահեմ առանձին src/env/client.ts ֆայլ, քանի որ միջավայրի փոփոխականը բրաուզերում բացահայտվելու համար պետք է ունենա NEXTPUBLIC նախածանցը։

Լավ գաղափար է այս ֆայլը ներմուծել next.config.ts ֆայլում, որպեսզի միջավայրի փոփոխականները ստուգվեն կոմպիլյացիայի ժամանակ։ Եթե որևէ փոփոխական բացակայի, հավելվածն ընդհանրապես չի գործարկվի։

Որպեսզի մեր հավելվածը ոչ մի տեղ ուղղակիորեն process.env-ին չդիմի և պարտադրվի մեր ստեղծած սխեմայի օգտագործումը, կարող ենք տեղադրել eslint-plugin-n plugin-ը.

npm install –save-dev eslint-plugin-n

և միացնել այն eslint.config.mjs ֆայլում.

const eslintConfig = [
  ...compat.config({
    plugins: ['n'],
    rules: {
    "n/no-process-env": ["error"]
    }
  })
];

Այս պահից միջավայրի փոփոխականին դիմելու համար պետք է ներմուծել մեր նախկինում սահմանած env հաստատունը.

import { env } from “@/env/server”;

և հետո օգտագործել այն.

env.DATABASE_URL

Ձևերի և վալիդացիաների մշակում

Ձևերը ցանկացած հավելվածի էական մասն են, և դրանց հետ աշխատանքը մի շարք մարտահրավերներ է առաջացնում։ Մեզ պետք է կլիենտային վալիդացիա՝ օգտատերերին ակնթարթային հետադարձ կապ տալու համար, և սերվերային վալիդացիա՝ տվյալների ամբողջականությունն ապահովելու և ձևի վիճակը կառավարելու համար։ Սա կարող է արագ բարդանալ, հատկապես բազմաքայլ ձևերի կամ դինամիկ դաշտերով ձևերի դեպքում։ Մասնագիտացված գրադարանները, որոնք վալիդացիային կառուցվածքային մոտեցում են առաջարկում, կրճատում են boilerplate-ը և օգնում օգտատիրոջ ինտերֆեյսը հետևողական պահել սխալների վիճակների և հետադարձ կապի համար, կարող են մեծապես բարելավել և ծրագրավորողի, և օգտատիրոջ փորձառությունը։

React Hook Form-ը արտադրողականության վրա կենտրոնացած ուշագրավ ձևերի գրադարան է։ Այն նախագծված է նվազագույնի հասցնել re-rendering-ը՝ մնալով ճկուն։ Դրա hooks-first մոտեցումը պարզեցնում է բաղադրիչների ծառը և խուսափում ավելորդ re-rendering-ից։

Տեղադրում.

npm install react-hook-form

Եվ ահա օրինակ.

import { zodResolver } from "@hookform/resolvers/zod";
import { SubmitHandler, useForm } from "react-hook-form";
import { z } from "zod";

// ...

const {
  register,
  handleSubmit,
  formState: { errors },
} = useForm({
  resolver: zodResolver(articleFormSchema),
  defaultValues: { ... },
});

  const onSubmit: SubmitHandler<z.infer<typeof articleFormSchema>> = async (
    values
  ) => { ... };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
        <div>
        <Input {...register("title", { required: true })} />
        <p>{errors.title?.message}</p>
        </div>
        {/* ... */}
    </form>
  );
};

React Hook Form-ը լավ է համագործակցում սխեմայի վալիդացիայի գրադարանների հետ (վերևի օրինակը օգտագործում է zodResolver)։ Zod գրադարանը հիշատակեցի միջավայրի փոփոխականների մասին խոսելիս, և այն կատարյալ կերպով հարմար է նաև այս դեպքի համար։ Սա TypeScript-first գրադարան է, որը թույլ է տալիս սահմանել վալիդացիայի սխեմաներ շղթայվող API-ով, որը կառուցված է TypeScript-ի տիպերի ինֆերենցի համակարգի վրա։ Zod-ի մեծ ուժը նրանում է, որ այն կարող է հանդես գալ որպես վալիդացիայի տրամաբանության միակ աղբյուր և կլիենտում, և սերվերում, ուստի կարող ենք վալիդացիայի սխեման սահմանել մեկ անգամ և վերօգտագործել ամբողջ հավելվածում։

Օրինակ.

import { z } from "zod";

export const signUpFormSchema = z
  .object({
    name: z.string().min(3, "Name must be at least 3 characters"),
    email: z.string().email("Invalid email address"),
    password: z.string().min(6, "Password must be at least 6 characters"),
    confirmPassword: z
    .string()
    .min(6, "Confirm password must be at least 6 characters"),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "Passwords don't match",
    path: ["confirmPassword"],
  });

Սերվերային վալիդացիայի համար, իր հերթին, Zod-ը առաջարկում է հարցման բեռը վալիդացնելու մաքուր և պարզ եղանակ.

import { signUpFormSchema } from "@/validations/sign-up.validator";

export async function signup(_state: FormState, formData: FormData) {
  try {
    const user = signUpFormSchema.parse({
    name: formData.get("name"),
    email: formData.get("email"),
    password: formData.get("password"),
    confirmPassword: formData.get("confirmPassword"),
    });
    // ...
  } catch (error) {
    // ...
  }
}

Թեստավորում

Թեստավորումը կառուցված է այնպիսի ֆրեյմվորքի վրա, ինչպիսին Vitest-ն է կամ Jest-ը, որը տալիս է թեստեր գործարկելու գործիքներ, assertion գրադարան և ֆունկցիաների spy-ինգ ու mock անելու հնարավորություններ։ React Testing Library-ը օգտակար լրացում է՝ թույլ տալով ռենդերել React բաղադրիչներ և HTML տարրերի վրա իրադարձություններ սիմուլացնել։

E2E թեստավորման համար Playwright-ը խորհուրդ տրվող գործիքն է, Cypress-ը՝ որպես այլընտրանք։ Երկուսն էլ թույլ են տալիս ավտոմատացնել և սիմուլացնել օգտատիրոջ փոխազդեցությունները բրաուզերում՝ համոզվելու համար, որ հավելվածը վարվում է ըստ նախատեսվածի։

Նույնականացում

Հաջորդը՝ նույնականացման կարգավորումը։ Ընդհանուր առմամբ, նույնականացումը ներառում է հետևյալ հասկացությունները.

  • Նույնականացում (Authentication). օգտատիրոջ ինքնությունը հաստատելու գործընթաց, այսինքն՝ ստուգում, որ հավելվածին մուտք փորձողը իսկապես այն է, ով ասում է
  • Սեսիաների կառավարում (Session management). օգտատիրոջ նույնականացման կարգավիճակին հետևելը, երբ նա ռեսուրսներ է հարցնում
  • Թույլտվություն (Authorization). որոշում, թե որ ռեսուրսներին և գործողություններին օգտատերը կարող է հասանելիություն ունենալ՝ հավելվածում նույնականացվելուց հետո

Նախագծի նույնականացումը կարելի է կարգավորել շատ եղանակներով։ Next.js-ի փաստաթղթերի էջը ունի մի ամբողջ հոդված այն զրոյից կառուցելու մասին՝ սեսիաների կառավարումը ներառյալ։ Սակայն զրոյից սկսելը միշտ չէ, որ անհրաժեշտ կլինի, ուստի խորհուրդ են տրվում պատրաստի լուծումներ, ի թիվս այլոց՝ ավելի լավ անվտանգության և պարզության համար։ Նման գրադարանները տալիս են ներկառուցված նույնականացում, սեսիաների կառավարում և թույլտվություն, գումարած լրացումներ, ինչպիսիք են սոցիալական մուտքը, բազմագործոն նույնականացումը կամ դերերի վրա հիմնված մուտքի վերահսկողությունը (RBAC)։ Next.js-ը պահպանում է համատեղելի նույնականացման և սեսիաների կառավարման գրադարանների ցանկ։

Մեր օրինակելի հավելվածի համար կկենտրոնանամ Auth.js-ի վրա։ Սա ամբողջական նույնականացման լուծում է, որը կառուցված է Next.js-ի համար, բայց աշխատում է նաև այլ backend ֆրեյմվորքների հետ (5-րդ տարբերակից առաջ այն կոչվում էր NextAuth և աջակցում էր միայն Next.js-ը)։ Այն մեծապես կրճատում է նախագծում անվտանգ նույնականացում իրականացնելու համար պահանջվող ժամանակը։

Auth.js-ի հիմնական հնարավորությունները.

  • Նույնականացման հանրահայտ մատակարարների (օր.՝ Google, GitHub, FaceBook) աջակցություն «արկղից դուրս»
  • Էլ. փոստ/գաղտնաբառ նույնականացման տարբերակ
  • Սեսիաների մանրակրկիտ կառավարում
  • Դերերի վրա հիմնված մուտքի վերահսկողություն
  • Անվտանգության հնարավորություններ, ինչպիսիք են CSRF պաշտպանությունը և http-only cookie-ները

Կօգտագործեմ նույնականացման երկու մեթոդ.

  1. Credentials provider – թույլ է տալիս օգտատերերին մուտք գործել ցանկացած հավատարմագրերով, օրինակ՝ էլ. փոստով և գաղտնաբառով
  2. Google provider – թույլ է տալիս օգտատերերին մուտք գործել Google հաշվով

Սեսիաների կառավարման համար հասանելի են սեսիաների երկու տեսակ.

  1. Stateless – սեսիայի տվյալները գտնվում են բրաուզերի cookie-ներում։ Cookie-ն ուղեկցում է յուրաքանչյուր հարցմանը, ուստի սերվերը կարող է այն ստուգել։ Սա ավելի պարզ մոտեցում է, բայց պոտենցիալ ավելի քիչ անվտանգ (սա եմ օգտագործելու – JWT token
  2. Database – սեսիայի տվյալները գտնվում են տվյալների բազայում, և օգտատիրոջ բրաուզերը ստանում է միայն գաղտնագրված սեսիայի ID։ Սա ավելի անվտանգ է, բայց կարող է ավելի բարդ լինել և սպառել սերվերի ավելի շատ ռեսուրսներ

Տեղադրում.

npm install next-auth@beta

Կոնֆիգուրացիա @/auth.ts ֆայլում.

import NextAuth, { type User } from "next-auth";
import Credentials from "next-auth/providers/credentials";
import GoogleProvider from "next-auth/providers/google";

export const { handlers, signIn, signOut, auth } = NextAuth({
  session: {
    strategy: "jwt",
  },
  providers: [
    GoogleProvider,
    Credentials({
    credentials: {
        email: {},
        password: {},
    },
    authorize: async (credentials) => {
        // ...
    },
    }),
  ],
});

Հաջորդը՝ երթուղին կարող ենք պաշտպանել այսպես.

import { auth } from '@/auth';

// ...

const session = await auth();

if (!session?.user) {
  return redirect('/sign-in');
}

Auth.js-ի տեղադրման մասին ավելի մանրամասն տեղեկություն հասանելի է այստեղ։

Տվյալների բազայի ինտեգրում

Next.js հավելված կառուցելը սովորաբար նշանակում է աշխատել տվյալների բազայի ORM-ի հետ։ Հասանելի մի քանիսից երկուսը հատկապես հանրաճանաչ են՝ Prisma և Drizzle ORM։

Իմ ընտրությունը Drizzle ORM-ն է։ Drizzle-ին առանձնացնում է այն, որ, ի տարբերություն Prisma-ի, այն կոդի գեներացիա չի պահանջում։ Prisma-ով նախ սահմանում եք սխեման, ապա կատարում npx prisma generate հրամանը (սխեմայի ֆայլի յուրաքանչյուր փոփոխությունից հետո)։ Այդ քայլը ստեղծում է Prisma կլիենտը (@prisma/client) և մոդելի տիպերի սահմանումները։

Drizzle-ում TypeScript-ով աղյուսակ սահմանելը միաժամանակ սահմանում է օգտագործման համար պատրաստ տիպեր՝ առանց կոդի գեներացիայի առանձին հրամաններ կատարելու։ Հետևաբար Drizzle-ում սխեման փոխելը լրացուցիչ քայլ չի պահանջում տիպերը և ORM կլիենտը թարմացնելու համար։

Drizzle-ը գալիս է նաև ներկառուցված օժանդակ ֆունկցիաներով, որոնք այդ նույն աղյուսակի սահմանումները վերածում են Zod վալիդատորների (կրկին առանց կոդի լրացուցիչ գեներացիայի)։

Ավելին, Drizzle-ը առաջարկում է տարբեր ադապտերներ՝ կախված նախագծի օգտագործած տվյալների բազայի տեսակից։ Աջակցվող տարբերակները ներառում են, ի թիվս այլոց, PostgreSQL, MySQL, SQLite, Neon և Supabase (ավելին այս մասին այստեղ)։ Դրանցից յուրաքանչյուրը կարելի է միացնել շատ տարբեր եղանակներով։

Ուզում եմ միանալ Docker կոնտեյներում աշխատող PostgreSQL-ին։

Տեղադրում.

npm i drizzle-orm postgres
npm i -D drizzle-kit

Դրայվերի սկզբնավորում.

import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import { env } from "@/env/server";
import * as schema from "./schema/index";

const queryClient = postgres(env.DATABASE_URL);
const db = drizzle({ client: queryClient, schema });

export default db;

Drizzle-ի կոնֆիգուրացիա (drizzle.config.ts).

import { defineConfig } from "drizzle-kit";
import { env } from "@/env/server";

export default defineConfig({
  out: "./src/db/migrations",
  schema: "./src/db/schema/index.ts",
  dialect: "postgresql",
  dbCredentials: {
    url: env.DATABASE_URL!,
  },
});

Օրինակելի սխեմա (src/db/articles.ts).

import { relations } from "drizzle-orm";
import {
  boolean,
  index,
  pgTable,
  text,
  timestamp,
  uniqueIndex,
  uuid,
  varchar,
} from "drizzle-orm/pg-core";
import users from "./users";

const articles = pgTable(
  "article",
  {
    id: uuid().primaryKey().defaultRandom(),
    title: varchar("title", { length: 255 }),
    slug: varchar("slug", { length: 255 }).notNull(),
    content: text("content").notNull(),
    image: varchar("image", { length: 2048 }),
    isPublic: boolean("is_public").default(false),
    authorId: uuid("author_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
    createdAt: timestamp("created_at", { mode: "string" })
    .notNull()
    .defaultNow(),
    updatedAt: timestamp("updated_at", { mode: "string" })
    .notNull()
    .defaultNow(),
  },
  (table) => [
    uniqueIndex("slug_idx").on(table.slug),
    index("title_idx").on(table.title),
  ]
);

export const articlesRelations = relations(articles, ({ one }) => ({
  author: one(users, {
    fields: [articles.authorId],
    references: [users.id],
  }),
}));

Սխեման ներմուծվում է src/db/schema/index.ts ֆայլում և միացվում drizzle.config.ts կոնֆիգուրացիային։ Տվյալների բազային հարցում անելու համար կավելացնենք օժանդակ ֆունկցիա src/lib/actions/article.actions.ts ֆայլում.

"use server";

import db from "@/db";

// ...

export async function getArticleBySlug(slug: string) {
  const article = await db.query.articles.findFirst({
    where: eq(articles.slug, slug),
  });

  return article;
}

Այս մեթոդը հիմա կարելի է կանչել page ֆայլում.

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const article = await getArticleBySlug(slug);
  // ...
}

Docker կոնտեյներացում

Տվյալների բազան Docker կոնտեյներում գործարկելու համար համոզվեք, որ տեղադրված է Docker Desktop, քանի որ այն հեշտացնում է կոնտեյներների կառավարումը։ Docker կոնտեյները կարելի է գործարկել շատ եղանակներով՝ օրինակ՝ ուղղակի հրամանի տողից կամ պատրաստի image-ներից, բայց գնանք ավելի կառուցվածքային ճանապարհով։ Ստեղծեք docker-compose.yml ֆայլ, որը պարունակում է ամբողջ անհրաժեշտ տեղեկությունը (օրինակ՝ PostgreSQL image-ը, պորտերը և միջավայրի փոփոխականները).

services:
  database:
    image: postgres
    container_name: readium_postgres
    environment:
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: postgres
    POSTGRES_DB: readium
    ports:
    - 5432:5432
    volumes:
    - dockerreadiumdata:/var/lib/postgresql/data
    healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres -d readium"]
    interval: 10s
    timeout: 5s
    retries: 5
    restart: unless-stopped

volumes:
  dockerreadiumdata:

Տվյալների բազան գործարկելը հետո հանգում է տերմինալում մեկ հրամանի կատարմանը.

docker compose up

Տեղակայում (Deployment)

Next.js հավելվածի տեղակայումը և հոստինգը շատ նման են ցանկացած այլ հավելվածի տեղակայմանը, և շատ բան կախված է ծրագրավորողների կարիքներից ու ընտրությունից, ինչպես նաև բիզնես որոշումներից։

Այսպիսով, Next.js-ը կարելի է տեղակայել.

  • Որպես Node.js սերվեր ցանկացած մատակարարի մոտ, որն աջակցում է այս միջավայրը
  • Ցանկացած մատակարարի մոտ, որն աջակցում է Docker կոնտեյներները, ներառյալ կոնտեյներների օրկեստրացիան, ինչպիսին Kubernetes-ն է, կամ ամպային մատակարարը
  • Որպես ստատիկ export (ստատիկ էջերի կամ SPA-ների համար)
  • Կամ, վերջապես, հարմարեցված տարբեր պլատֆորմների վրա աշխատելու համար, որոնք աջակցում են ենթակառուցվածքը

Լրացուցիչ տեղեկություն հասանելի է այստեղ։

Ամփոփում

Այս հոդվածում քայլ առ քայլ ներկայացրի Next.js 15-ով և այնպիսի տեխնոլոգիաներով, ինչպիսիք են TypeScript-ը, Server Actions-ը, Server և Client Components-ը, Auth.js-ը, Tailwind CSS-ը, Drizzle ORM-ը, PostgreSQL-ը և Docker-ը, կառուցված ժամանակակից full stack հավելվածի ճարտարապետությունը։ Բացի այն ցույց տալուց, թե ինչպես են այս գործիքները համադրվում, ցուցադրեցի, թե ինչպես կարգավորել նախագծի հստակ կառուցվածք, մշակել վիճակն ու տիպերը և տրամաբանությունը մաքուր բաժանել frontend-ի և backend-ի միջև։

Հուսով եմ՝ այս գիտելիքը կօգնի ձեզ կառուցել ամուր, մասշտաբավորվող հավելվածներ։