\section{لماذا Vercel مع FormaTeX}
إنشاء PDF دون مغادرة مجموعة Next.js التقنية
لا تستطيع دوال Vercel تشغيل TeX Live، لكنها تستطيع إرسال طلبات HTTP. يحوّل FormaTeX API استدعاء fetch واحدًا إلى ملف PDF مجمّع بالكامل.
نشر دون أي إعداد
أضف ملف مسار API واحدًا ومتغير بيئة واحدًا. ادفع إلى Vercel، وتصبح نقطة نهاية PDF الخاصة بك متاحة عالميًا خلال ثوانٍ.
يعمل مع App Router
يتبع معالج المسار اصطلاح App Router في Next.js. صدّر runtime وmaxDuration ومعالج POST، وهذا كل شيء.
استجابة مبثوثة
مرّر بايتات PDF الواردة من الخادم مباشرة إلى المتصفح دون تخزين الملف بأكمله مؤقتًا في الذاكرة، فيبقى استدعاء الدالة سريعًا وموفرًا للتكلفة.
\section{مسار API في Next.js}
مسار API الكامل
أنشئ app/api/pdf/route.ts في مشروع Next.js. يقبل المسار طلب POST بجسم JSON يحتوي على source وحقل engine اختياري، ثم يبثّ ملف PDF المجمّع إلى المستدعي.
// app/api/pdf/route.ts
import type { NextRequest } from "next/server"
// Use the Node.js runtime — the Edge runtime does not support
// the full fetch API response streaming needed for binary files.
export const runtime = "nodejs"
// Vercel Hobby: 10 s max. Pro / Enterprise: up to 300 s.
// Set this to at least 30 s to handle complex documents.
export const maxDuration = 30
export async function POST(request: NextRequest) {
const body = await request.json()
const source: string = body.source ?? ""
const engine: string = body.engine ?? "pdflatex"
if (!source) {
return Response.json({ error: "source is required" }, { status: 400 })
}
const apiKey = process.env.FORMATEX_API_KEY
if (!apiKey) {
return Response.json({ error: "FORMATEX_API_KEY is not configured" }, { status: 500 })
}
const upstream = await fetch("https://api.formatex.io/api/v1/compile", {
method: "POST",
headers: {
"X-API-Key": apiKey,
"Content-Type": "application/json",
},
body: JSON.stringify({ latex: source, engine }),
})
if (!upstream.ok) {
const err = await upstream.json().catch(() => ({ error: "compilation failed" }))
return Response.json(err, { status: upstream.status })
}
// Stream the PDF bytes directly to the client — no buffering in memory.
return new Response(upstream.body, {
headers: {
"Content-Type": "application/pdf",
"Content-Disposition": 'attachment; filename="document.pdf"',
},
})
}\subsection{استدعاء المسار}
استدعِ /api/pdf من أي مكوّن عميل أو إجراء خادم. تُطلق الدالة المساعدة أدناه تنزيلًا في المتصفح مباشرة من الـ blob.
// Calling the route from a React component or server action
async function generatePdf(latexSource: string): Promise<void> {
const res = await fetch("/api/pdf", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ source: latexSource, engine: "pdflatex" }),
})
if (!res.ok) {
const { error } = await res.json()
throw new Error(error ?? "PDF generation failed")
}
// Trigger a browser download
const blob = await res.blob()
const url = URL.createObjectURL(blob)
const a = document.createElement("a")
a.href = url
a.download = "document.pdf"
a.click()
URL.revokeObjectURL(url)
}\section{متغيرات البيئة}
إضافة مفتاح API إلى Vercel
افتح إعدادات مشروعك
انتقل إلى vercel.com ← مشروعك ← Settings ← Environment Variables.
أضف FORMATEX_API_KEY
اضبط الاسم على FORMATEX_API_KEY والصق مفتاحك من لوحة تحكم FormaTeX. اختر بيئتي Production (واختياريًا Preview).
أعد النشر
تسري تغييرات متغيرات البيئة عند عملية النشر التالية. أطلق إعادة نشر من لوحة تحكم Vercel أو بدفع commit جديد.
لا تكشف FORMATEX_API_KEY للمتصفح أبدًا. المتغير متاح من جهة الخادم فقط داخل Route Handler أو Server Action، ولن يُضمَّن في حزمة العميل.
\section{اختيار بيئة التشغيل}
بيئة Edge مقابل Node.js
بيئة Edge
غير موصى بها- حد 50 ميلي ثانية من المعالج، وهو غير كافٍ للمستندات المعقدة
- حد 4 ميغابايت لجسم الاستجابة، وقد يقتطع ملفات PDF الكبيرة
- لا تتوفر مكونات Node.js المدمجة مثل Buffer
بيئة Node.js
موصى بها- تنفيذ حتى 300 ثانية (خطة Pro/Enterprise)
- دعم كامل لبثّ جسم الاستجابة
- تتوفر Buffer وcrypto القياسيتان في Node.js
اضبط export const runtime = "nodejs" في أعلى ملف المسار. بدونه قد يختار Next.js بيئة Edge افتراضيًا على Vercel، وسيفشل بثّ PDF للمستندات الكبيرة.
\section{أدلة ذات صلة}
مزيد من الأدلة لمجموعتك التقنية
FormaTeX API نقطة نهاية HTTP عادية. يمكنك الوصول إليها من أي لغة أو منصة.

