BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/netlify.mdx
View on GitHub---
title: "Netlify"
description: "انشر تطبيق Agent-Native مستقلًا على Netlify باستخدام Netlify CLI، واضبط الإبقاء دافئًا (keep-warm) لقواعد البيانات ذات التوسع إلى صفر."
---
# Netlify
يستضيف Netlify تطبيقك نيابةً عنك، لذلك لا يوجد خادم تحتاج إلى إعداده أو إبقائه
قيد التشغيل. يحوّل البناء التطبيق إلى ملفات ثابتة يقدّمها Netlify مباشرةً ودوال
يشغّلها Netlify عند الطلب، ويمنح Netlify التطبيق عنوانًا عامًا مع HTTPS.
يشرح هذا الدليل نشر تطبيق مستقل واحد من البداية. ستنشئ التطبيق، وتمنحه قاعدة
بيانات إنتاجية وسر مصادقة، وتنشئ موقع Netlify له، وتجهّز قاعدة البيانات، ثم تبني
التطبيق وتنشره.
<Callout tone="info">
يلزم Node.js `22.22+`.
</Callout>
تحتاج أيضًا إلى حساب Netlify. شغّل الأوامر في هذا الدليل على حاسوبك الخاص. يرفع
Netlify CLI البناء النهائي إلى Netlify نيابةً عنك.
## الخطوة 1: إنشاء التطبيق {#step-1-create-the-app}
أنشئ تطبيقك المستقل الجديد. ينشئ المثال أدناه تطبيقًا من قالب Chat، لكن يمكنك
البدء من أي قالب. انتقل إلى مجلد التطبيق وثبّت تبعياته. يفعّل الأمر
`corepack enable` إصدار `pnpm` الذي يتوقعه التطبيق، لذلك لا تحتاج إلى تثبيت
`pnpm` بنفسك.
```bash
npx --yes @agent-native/core@latest create my-app --standalone --template chat
cd my-app
corepack enable
pnpm install
```
استبدل `my-app` باسم تطبيقك إذا أردت. يفترض باقي هذا الدليل أنك داخل مجلد
التطبيق.
<Callout tone="info">
إذا فشلت هذه الأوامر بأخطاء في التبعيات النظيرة، فقد يكون السبب نسخة قديمة من حزمة في ذاكرة npx المؤقتة. شغّل `npx clear-npx-cache` لمسح الذاكرة المؤقتة، ثم شغّل الأوامر مرة أخرى.
</Callout>
## الخطوة 2: ضبط أسرار البيئة {#step-2-configure-environment-secrets}
يقرأ التطبيق إعدادات الإنتاج من متغيرات البيئة:
| المتغير | مطلوب | الغرض |
| -------------------- | ----- | ------------------------------------------------------- |
| `DATABASE_URL` | نعم | يربط التطبيق بقاعدة بيانات PostgreSQL الخاصة به |
| `BETTER_AUTH_SECRET` | نعم | يوقّع جلسات المستخدمين |
| `BETTER_AUTH_URL` | لا | يحدد العنوان العام الذي يستخدمه الناس للوصول إلى تطبيقك |
تجعل أوامر التصدير أدناه الأوامر التالية تعمل في هذه الصدفة. قبل النشر، احفظ
المتغيرات نفسها في إعدادات بيئة المشروع أو الخدمة لدى موفر الاستضافة. توضح الخطوة
التالية كيفية حفظها في Netlify.
### عنوان URL لقاعدة البيانات {#database-url}
أثناء التطوير المحلي، يخزّن التطبيق البيانات في قاعدة بيانات محلية عندما يكون
`DATABASE_URL` غير مضبوط. يحتاج التطبيق المنشور إلى قاعدة بيانات PostgreSQL
حقيقية تحتفظ ببياناتها بين عمليات النشر. لا يحتفظ Netlify بالملفات بين الطلبات،
لذلك يجب أن توجد قاعدة البيانات خارج دوال Netlify. انسخ سلسلة الاتصال من موفر
قاعدة البيانات وصدّرها:
```bash
export DATABASE_URL='your-postgres-url-string'
```
توضح [أدلة موفري قواعد البيانات](/docs/neon) مكان العثور على سلسلة الاتصال لدى
كل موفر.
<Callout tone="warning">
اختر موفر PostgreSQL دائمًا: Neon أو Supabase أو Amazon RDS أو غيرها.
</Callout>
### سر المصادقة {#auth-secret}
أنشئ هذه القيمة مرة واحدة وأبقها ثابتة عبر عمليات النشر.
يستخدم التطبيق `BETTER_AUTH_SECRET` لتوقيع جلسات المستخدمين. إذا تغيّرت القيمة،
يُسجَّل خروج كل مستخدم مسجّل الدخول. ينشئ الأمر أدناه قيمة عشوائية:
```bash
export BETTER_AUTH_SECRET="$(openssl rand -hex 32)"
```
احفظ القيمة المُنشأة في مكان آمن، مثل مدير كلمات المرور. استخدم القيمة نفسها في
كل مرة تنشر فيها.
### عنوان URL العام {#public-url}
اختياري. اضبطه عند استخدام نطاق مخصص، أو وكيل عكسي، أو تدفق مصادقة أو OAuth يحتاج
إلى أصل عام ثابت.
`BETTER_AUTH_URL` هو العنوان العام الذي يستخدمه الناس للوصول إلى تطبيقك. بدونه،
يستنتج التطبيق عنوانه من كل طلب وارد. يكون ذلك مناسبًا عادةً على العنوان الذي
يمنحك إياه Netlify، لكن اضبطه عندما تربط نطاقًا مخصصًا حتى تستخدم روابط تسجيل
الدخول وعمليات إعادة توجيه OAuth ذلك النطاق.
```bash
export BETTER_AUTH_URL='https://your-domain.example'
```
## الخطوة 3: ربط الموقع وحفظ الأسرار {#step-3-link-the-site-and-save-the-secrets}
سجّل الدخول إلى Netlify من سطر الأوامر، ثم أنشئ موقعًا جديدًا للتطبيق. يمكنك ترك
اسم المشروع على قيمته الافتراضية وترك مستودع GitHub فارغًا في الوقت الحالي.
```bash
npx netlify login
npx netlify sites:create --name my-app
```
ينشئ `sites:create` الموقع ويربطه بمجلد التطبيق، حتى تعرف الأوامر اللاحقة أي موقع
تستخدم. يصبح الاسم أيضًا عنوان الموقع، مثل `my-app.netlify.app`. أسماء المواقع
مشتركة عبر Netlify بالكامل، لذلك اختر اسمًا مختلفًا إذا كان `my-app` مستخدمًا
بالفعل. لا تحتاج إلى مستودع GitHub، لأنك تنشر التطبيق من حاسوبك في الخطوة 5.
احفظ المتغيرين المطلوبين في بيئة الموقع:
```bash
npx netlify env:set DATABASE_URL "$DATABASE_URL"
npx netlify env:set BETTER_AUTH_SECRET "$BETTER_AUTH_SECRET"
```
يقرأ كل أمر القيمة التي صدّرتها في الخطوة 2 ويحفظها في Netlify، لذلك لا تحتاج إلى
لصق الأسرار يدويًا. إذا ضبطت `BETTER_AUTH_URL`، فاحفظه بالطريقة نفسها. يمكنك
أيضًا عرض هذه القيم وتغييرها لاحقًا في إعدادات الموقع على لوحة تحكم Netlify.
## الخطوة 4: الترحيل {#step-4-migrate}
تنشئ عمليات الترحيل الجداول التي يحتاجها التطبيق في قاعدة البيانات وتحدّثها.
شغّل هذا الأمر قبل أول عملية نشر:
```bash
pnpm migrate:production
```
يعمل الأمر على حاسوبك ويتصل بقاعدة بيانات الإنتاج باستخدام `DATABASE_URL` الذي
صدّرته في الخطوة 2. شغّله مرة أخرى بعد ترقية التطبيق، وقبل نشر الإصدار الجديد.
## الخطوة 5: النشر {#step-5-deploy}
ابنِ التطبيق لـ Netlify:
```bash
NITRO_PRESET=netlify pnpm build
```
يبني `NITRO_PRESET=netlify` التطبيق بالتنسيق الذي يتوقعه Netlify. يكتب البناء
الملفات الثابتة للتطبيق في المجلد `dist` ودوال الخادم الخاصة به في المجلد
`.netlify/functions-internal`.
ارفع البناء وانشره:
```bash
npx netlify deploy --prod --dir=dist --functions=.netlify/functions-internal
```
يخبر `--dir` و`--functions` CLI بمكان الملفات الثابتة والدوال التي بنيتها للتو.
وينشرها `--prod` على عنوان الإنتاج الخاص بك بدلًا من معاينة مسودة.
عندما ينتهي الأمر، يطبع عنوان الإنتاج الخاص بالتطبيق. افتحه وأنشئ الحساب الأول.
## نشر التحديثات {#deploy-updates}
لإصدار نسخة جديدة، شغّل أوامر الترحيل والبناء والنشر مرة أخرى من مجلد التطبيق:
```bash
pnpm migrate:production
NITRO_PRESET=netlify pnpm build
npx netlify deploy --prod --dir=dist --functions=.netlify/functions-internal
```
يبقى ربط الموقع والمتغيرات المحفوظة كما هي، لذلك لا تحتاج إلى تكرار الخطوة 3.
## الإبقاء دافئًا وقواعد البيانات ذات التوسع إلى صفر {#netlify-keep-warm}
بعد فترة هادئة، قد يكون الطلب الأول بطيئًا بينما يبدأ Netlify تشغيل الدالة وتستيقظ
قاعدة بيانات ذات توسع إلى صفر، مثل المستوى المجاني من Neon. يمكن لـ Agent-Native
تقليل هذا الانتظار عبر الإبقاء دافئًا. عند تشغيله، يضيف البناء دالة Netlify
مجدولة تستدعي نقطة النهاية `/_agent-native/health` الخاصة بالتطبيق **كل دقيقة**،
مما يُبقي دالة الخادم وقاعدة بياناتها مستيقظتين.
الإبقاء دافئًا **مُعطَّل افتراضيًا**. إبقاء قاعدة البيانات مستيقظة يمنعها من
التوقف المؤقت، وهذا يستهلك حصة الحوسبة في الخطط المجانية أو المقاسة. إذا نفدت
الحصة، ترفض قاعدة البيانات **جميع** القراءات ويتوقف التطبيق عن العمل. اضبط
`AGENT_NATIVE_ENABLE_KEEP_WARM=1` عندما تستحق الزيارة الأولى الأسرع وقت قاعدة
البيانات الإضافي.
تتحكم هذه المتغيرات في الإبقاء دافئًا. لا تُطبَّق إعدادات الجدول والخلفية إلا بعد
تشغيل `AGENT_NATIVE_ENABLE_KEEP_WARM`:
| المتغير | التأثير |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENT_NATIVE_ENABLE_KEEP_WARM` | يشغّل التدفئة المجدولة لدالة الخادم وقاعدة البيانات. غير مضبوط افتراضيًا. |
| `AGENT_NATIVE_DISABLE_KEEP_WARM` | يوقف الإبقاء دافئًا حتى عند ضبط `AGENT_NATIVE_ENABLE_KEEP_WARM`. مُبقى عليه للتوافق مع الإعدادات الأقدم. |
| `AGENT_NATIVE_KEEP_WARM_SCHEDULE` | يغيّر عدد مرات تشغيل التدفئة، بتعبير cron مكون من 5 حقول مثل `*/5 * * * *`. القيمة الافتراضية هي `* * * * *`، أي كل دقيقة. القيمة التي ليست تعبير cron صالحًا **تُفشل البناء**. |
| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | يتخطى تدفئة دالة الخلفية ويواصل تدفئة دالة الخادم. تدفئة الخادم طلب واحد. تدفئة دالة الخلفية تبدأ حاوية جديدة تفحص مخطط قاعدة البيانات مرة أخرى. |
| `AGENT_NATIVE_KEEP_WARM_CONCURRENCY` | مساحات العمل متعددة التطبيقات فقط: عدد مثيلات الخادم التي يبقيها كل تطبيق دافئة، من 1 إلى 50. القيمة الافتراضية `1`. القيمة خارج هذا النطاق **تُفشل البناء**. |
### مساحات العمل متعددة التطبيقات {#netlify-workspace-keep-warm}
يقرأ نشر مساحة العمل المتغيرات نفسها. عند تشغيل keep-warm، يُصدر دالة مجدولة واحدة، `agent-native-workspace-keep-warm`، تستدعي نقطة النهاية `/<app>/_agent-native/health` لكل تطبيق وفق الجدول.
يخدم مثيل دالة Netlify طلبًا واحدًا في كل مرة، وفتح تطبيق يرسل دفعة من طلبات إطار العمل المتوازية. كل طلب لا يجد مثيلًا خاملًا يبدأ مثيلًا باردًا، لذا لا يفيد مثيل دافئ واحد كثيرًا في تحميل الصفحة. اضبط `AGENT_NATIVE_KEEP_WARM_CONCURRENCY` لإرسال هذا العدد من طلبات الفحص المتداخلة لكل تطبيق، فيبقى هذا العدد من المثيلات دافئًا. كل تشغيل يرسل `التطبيقات x التزامن` طلبًا، لذا اجمع القيمة الأعلى مع جدول أبطأ مثل `*/3 * * * *`.
إذا كانت قاعدة بياناتك على خطة مجانية أو محدودة بطريقة أخرى، اترك
`AGENT_NATIVE_ENABLE_KEEP_WARM` غير مضبوط. إذا شغّلته، اختر جدولًا أبطأ أو اضبط
`AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND=1` لتخطي تدفئة الخلفية الأكثر تكلفة.
يقرأ البناء هذه المتغيرات، وليس التطبيق قيد التشغيل. لأنك تبني على حاسوبك الخاص في
الخطوة 5، اضبطها في الصدفة نفسها قبل البناء. حفظها في إعدادات موقع Netlify ليس له
أي تأثير على بناء يعمل محليًا. على سبيل المثال، لتشغيل الإبقاء دافئًا بجدول كل خمس
دقائق:
```bash
export AGENT_NATIVE_ENABLE_KEEP_WARM=1
export AGENT_NATIVE_KEEP_WARM_SCHEDULE='*/5 * * * *'
NITRO_PRESET=netlify pnpm build
```
ثم انشر كالمعتاد.
## ما هي الخطوة التالية {#whats-next}
- [**متغيرات بيئة النشر**](/docs/deployment-environment-variables) - القائمة الكاملة لإعدادات الإنتاج
- [**التخزين المؤقت SSR**](/docs/ssr-caching) - سياسة التخزين المؤقت الافتراضية وسلوك `netlify-cdn-cache-control` المنفصل الخاص بـ Netlify
- [**النشر**](/docs/deployment) - قارن بين أهداف الاستضافة ومتطلباتها الأساسية
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |