Ժամանակակից full stack հավելվածի ճարտարապետության կառուցում Next.js 15+-ով
Այս հոդվածը քայլ առ քայլ ներկայացնում է Next.js 15-ով կառուցված ժամանակակից full stack հավելվածի ճարտարապետությունը՝ TypeScript, Server Actions, Server և Client Components, Auth.js, Tailwind CSS, Drizzle ORM, PostgreSQL և Docker տեխնոլոգիաների հետ միասին։
Արդեն շատ տարիներ 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-ի հիմնական հնարավորությունները
- SSR – էջերի սերվերային ռենդերինգի ներկառուցված աջակցություն, որը բարձրացնում է արտադրողականությունը և SEO-ն
- SSG – ստատիկ կայքերի գեներացման աջակցություն, որի ժամանակ էջերը ստեղծվում են կոմպիլյացիայի ժամանակ և մատուցվում որպես ստատիկ HTML ֆայլեր՝ արագացնելով բեռնումը և թեթևացնելով սերվերի բեռը
- Կոդի ավտոմատ բաժանում – Next.js-ը կոդը բաժանում է ավելի փոքր, ավելի կառավարելի մասերի՝ արտադրողականությունն ու բեռնման ժամանակը օպտիմալացնելու համար
- CSS աջակցություն – CSS լուծումների մի շարք աջակցություն, այդ թվում՝ CSS մոդուլներ, CSS-in-JS գրադարաններ և գլոբալ CSS ոճեր, ինչը ճկունություն է տալիս հավելվածի ոճավորման հարցում
- Տվյալների ստացում – տվյալների ստացման մի քանի եղանակների աջակցություն կոմպիլյացիայի կամ հարցման ժամանակ
- Երթուղավորում – զգալիորեն պարզեցված է ֆայլերի կառուցվածքի և էջերի պանակների հիման վրա երթուղիների ավտոմատ գեներացմամբ
- Պատկերների օպտիմալացում – պատկերների ավտոմատ չափափոխում և սեղմում՝ բեռնման օպտիմալ արտադրողականություն ապահովելու համար
- CSS-ի և JavaScript-ի ներկառուցված փաթեթավորում – CSS-ը և JS-ը ավտոմատ օպտիմալացվում և փաթեթավորվում են, որպեսզի ավելի արդյունավետ բեռնվեն
- API proxy – թույլ է տալիս ստեղծել API երթուղիներ, որոնք գործում են որպես երրորդ կողմի API-ների proxy՝ օգնելով տվյալների ստացմանը և անվտանգությանը
- Միջազգայնացման աջակցություն – Next.js-ը առաջարկում է գործիքներ և գրադարաններ մի քանի լեզուների աջակցության համար
Հաշվի առնելով այս հնարավորություններն ու առավելությունները՝ արժե հարցնել, թե երբ է իմաստ ունենում ընտրել այս ֆրեյմվորքը սովորական React-ի փոխարեն։ Next.js-ը օգտակար է բովանդակությամբ հարուստ կայքերի համար, ինչպիսիք են բլոգները կամ էլեկտրոնային առևտուրը, որտեղ SEO-ն նույնպես շատ կարևոր է։ Next.js-ը կարող է նկատելիորեն բարելավել հավելվածի արտադրողականությունը, քանի որ օգտատերը ստիպված չէ իր սարքում ներբեռնել և կատարել մեծ քանակությամբ JS, ինչը հատկապես կարևոր է ավելի դանդաղ սարքերի կամ ցանցերի դեպքում։
Ուրեմն սովորական React-ով մնալն ավելի լավ տարբերակ է, երբ գործ ունենք՝
- Միկրոսերվիս ճարտարապետության կամ backend-ից մեծապես կախված տրամաբանության հետ
- Իրական ժամանակի թարմացումներից մեծապես կախված հավելվածի հետ
- Խիստ հարմարեցված օգտատիրոջ ինտերֆեյսի հետ՝ անիմացիաներով, փոխազդեցություններով և բարդ դասավորություններով
Ներածությունն ավարտվեց, ժամանակն է անցնել մանրամասներին։ Կանցնեմ այն մնացած հասկացությունների միջով, որոնք ծրագրավորողը պետք է նկատի ունենա Next.js հավելված կառուցելիս, ստեղծելով և կարգավորելով մի հավելված, որը կատարում է CRUD գործողություններ հոդվածների վրա՝ նույնականացումը ներառյալ։
Նախագծի սկիզբ
Տերմինալում.
npx create-next-app@latest
Հրամանը կատարվելուց հետո պատասխանում ենք մի քանի հարցի, և կարճ ժամանակ անց մեզ պետք եղած ամեն ինչ ավտոմատ կարգավորված է։
Նախագծի կառուցվածքը
Հարցերից մեկը հարցնում է, թե որ router-ն օգտագործել։ Next.js-ը երկու տեսակ է առաջարկում.
- App Router – ավելի նոր router, որն աջակցում է React-ի նոր հնարավորություններ, ինչպիսիք են Server Components-ը և Server Actions-ը,
- 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-ները
Կօգտագործեմ նույնականացման երկու մեթոդ.
- Credentials provider – թույլ է տալիս օգտատերերին մուտք գործել ցանկացած հավատարմագրերով, օրինակ՝ էլ. փոստով և գաղտնաբառով
- Google provider – թույլ է տալիս օգտատերերին մուտք գործել Google հաշվով
Սեսիաների կառավարման համար հասանելի են սեսիաների երկու տեսակ.
- Stateless – սեսիայի տվյալները գտնվում են բրաուզերի cookie-ներում։ Cookie-ն ուղեկցում է յուրաքանչյուր հարցմանը, ուստի սերվերը կարող է այն ստուգել։ Սա ավելի պարզ մոտեցում է, բայց պոտենցիալ ավելի քիչ անվտանգ (սա եմ օգտագործելու – JWT token
- 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-ի միջև։
Հուսով եմ՝ այս գիտելիքը կօգնի ձեզ կառուցել ամուր, մասշտաբավորվող հավելվածներ։