nextjs prisma boilerplate
1.0.0
هذا هو مكدس كامل boilerplate مبني حول أحدث مكدس. js. وهي تتألف من أفضل الممارسات الموضحة في المستندات الرسمية إلى جانب قراراتي المستمدة من تجربتي ومعرفتي التي جمعتها من العمل مع أشخاص آخرين.
لا تقضي الأشهر الثلاثة القادمة في اتخاذ القرارات المعمارية واختيار المكتبات وإنشاء بيئات Dev و Prod وخطوط أنابيب CI/CD ، وكتابة رمز Boilerplate ، بدلاً من ذلك ، قم بتثبيت هذا Boilerplate في 15 دقيقة وابدأ العمل على ميزاتك اليوم .
إذا تم تخريب التطبيق ، فما عليك سوى استخدام رابط
Reseedعلى الجانب الأيمن من تذييل تذييل لإعادة صياغة قاعدة البيانات.
أنت بحاجة إلى حساب GITPOD ، وربما URL POSTGRES لقاعدة البيانات إذا تم تخريب قاعدة بيانات العرض التجريبي الخاص بي. يمكنك إنشاء واحدة على موقع Elephantsql.com ، راجع قسم بيئة GITPOD للحصول على التفاصيل.
next-auth ، إلخ ...) React 18.2.0 ، Next.js 12.2.0 ، Node.JS 16.13.1 ، Prisma 4 ، Postgres 14.3 ، TypeScript 4.7.4 ، React Query 4-beta ، Axios ، Form Hook Form 8-alpha ، React Dropzone ، Zod ، MSW ، Tailwindcs 3 ، Jest 28 ، Testing Mibrary React ، Cypress 9.6.1 .
next-auth والفيسبوك وجوجل وبيانات الاعتماد.env* ملفات ...pages بنية المكون القابلة للتطوير والفكين -> layouts -> views -> components!importantnext-connect مع البرامج الوسيطة للتحقق من الصحة والطرق المحميةgetServerSideProps مع فئة خطأ مخصصةtesting-library/react لاختبارات الوحدة والتكاملjest-preview Visual Debugging ، الصور التي تسخر منها Plob polyfill ، ملفات منفصلة .env.test*بدون أي تعديلات خاصة ، هناك مجال لمزيد من التحسن.
يحتوي هذا المشروع على 3 بيئات تطوير متاحة:
يمكنك اختيار أي بيئة تفضلها.
أي واحد يختار؟ إذا كنت تحب النهج التقليدي ، فاختر محليًا ، إذا كنت تعمل في فريق ما وترغب في الحصول على بيئات متسقة مع الزملاء لإعادة إنتاج الأخطاء بسهولة وسرعان ما على متن الأعضاء الجدد في اختيار Docker ، وإذا كنت ترغب في جعل Sandbox يقوم بإعادة إنتاج خطأ وطلب المساعدة في اختيار gitpod علنًا.
استنساخ مستودع وتثبيت التبعيات.
# clone repository
git clone [email protected]:nemanjam/nextjs-prisma-boilerplate.git
cd nextjs-prisma-boilerplate
# install dependencies
yarn installعندما تفتح مجلد المشروع لأول مرة VS ، ستطلب منك رمز تثبيت الامتدادات الموصى بها ، يجب أن تقبلها جميعًا ، فهي ضرورية لتسليط الضوء على رمز الإكمال التلقائي ، والبث والتنسيق ، وتشغيل الاختبارات ، وإدارة الحاويات.
ملء متغيرات البيئة العامة المطلوبة في .env.development . أسرع طريقة هي تشغيل التطبيق باستخدام خادم http .
أنت بحاجة إلى
httpsمحليًا فقط لتسجيل الدخول إلى Oauth Facebook. لذلك ، تحتاج إلىmkcertلتثبيت شهادات لـlocalhost، وهي تعليمات يمكن العثور عليها في مجلدdocs.
اترك PORT كـ 3001 ، يتم ترميزه في أماكن متعددة ، إذا كنت ترغب في تغييره ، فيجب عليك تحريرها جميعًا (أي كل Dockerfile.* و docker-compose.*.yml )
# .env.development
SITE_PROTOCOL=http
SITE_HOSTNAME=localhost
PORT=3001
# don't touch these two variables
APP_ENV=local
NEXTAUTH_URL= ${SITE_PROTOCOL} :// ${SITE_HOSTNAME} : ${PORT} إنشاء .env.development.local ملف.
# create local file form example file
cp .env.development.local.example .env.development.local
في جميع البيئات ، تم تكوين حاوية Postgres لتشغيلها كمستخدم حالي غير الجذر على جهاز مضيف Linux. هذا أمر مهم بحيث يتم إنشاء ملفات قاعدة البيانات في مجلدات مع الملكية والأذونات الصحيحة. لهذا ، تحتاج إلى تحديد MY_UID و MY_GID . أفضل مكان لوضعها في ~/.bashrc .
# ~/.bashrc
export MY_UID= $( id -u )
export MY_GID= $( id -g )ملء متغيرات البيئة الخاصة المطلوبة. المتغيرات المطلوبة الوحيدة هي لاتصال قاعدة بيانات Postgres و JWT Secret.
بيانات اعتماد Facebook و Google اختيارية وتستخدم فقط لتسجيل الدخول إلى OAuth. يتطلب تسجيل الدخول على Facebook
httpsلإعادة توجيه عنوان URL. يمكنك تعيين أي قيم لـPOSTGRES_USERوPOSTGRES_PASSWORDوPOSTGRES_DB.
# .env.development.local
# set database connection
POSTGRES_HOSTNAME=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres_user
POSTGRES_PASSWORD=password
POSTGRES_DB=npb-db-dev
# don't edit this expanded variable
DATABASE_URL=postgresql:// ${POSTGRES_USER} : ${POSTGRES_PASSWORD} @ ${POSTGRES_HOSTNAME} : ${POSTGRES_PORT} / ${POSTGRES_DB} ? schema=public
# jwt secret
SECRET=some-long-random-string
# OAuth logins (optional)
# Facebook (you need https for this)
FACEBOOK_CLIENT_ID=
FACEBOOK_CLIENT_SECRET=
# Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET= بعد تعيين جميع المتغيرات ، يمكنك تشغيل قاعدة بيانات Postgres داخل حاوية Docker ، وتشغيل عمليات ترحيل Prisma التي ستنشئ جداول SQL من schema.prisma وقاعدة بيانات البذور مع البيانات.
# run database container
yarn docker:db:dev:up
# run Prisma migrations (this will create sql tables, database must be running)
yarn prisma:migrate:dev:env
# seed database with data
yarn prisma:seed:dev:env في هذه المرحلة ، كل شيء جاهز ، يمكنك الآن بدء التطبيق. افتح http://localhost:3001 في المتصفح لرؤية تطبيق التشغيل.
# start the app in dev mode
yarn devبعد أن تم استنساخ حاوية تطبيق ROTOSTORY BUILD.
# terminal on host
yarn docker:dev:build سوف تقرأ بيئة Docker المتغيرات من مجلد envs/development-docker . قم بإنشاء ملف ENV المحلي من ملف مثال. لديها جميع المتغيرات التي تم تكوينها بالفعل.
# terminal on host
cp envs/development-docker/.env.development.docker.local.example envs/development-docker/.env.development.docker.local قم بتشغيل التطبيق وقاعدة البيانات وحاويات الإدارة. هذا كل شيء. يتم تثبيت مجلد المشروع على مجلد /app داخل الحاوية ، يمكنك إما تحرير المصدر مباشرة على علامة التبويب تمديد المضيف أو فتح حاويات عن بُعد ونقر بزر الماوس الأيمن على npb-app-dev وحدد Attach to Container وفتح /app Folder في مثيل رمز VS REMOTE. افتح http://localhost:3001 في المتصفح على المضيف لمشاهدة تطبيق التشغيل.
# terminal on host
yarn docker:dev:up افتح محطة جديدة داخل الحاوية وبذرة قاعدة البيانات ، docker-compose.dev.yml تمرر بالفعل ملفات ENV الصحيحة.
# terminal inside the container
yarn prisma:seedملاحظة: ستكون GIT موجودة بالفعل في الحاوية مع حسابك حتى تتمكن من التزام التغييرات مباشرة من الحاوية.
# check that git config is already set inside the container
git config --list --show-originأقترح عليك تثبيت حاوية Portainer Community Edition محليًا لتسهيل إدارة الحاويات وتصحيح الأخطاء ، إنها أداة مجانية ومفيدة للغاية.
انتقل إلى Elephantsql.com قم بإنشاء حساب مجاني وإنشاء قاعدة بيانات مجانية 20 ميجابايت بعد Postgres. انتقل إلى gitpod.io ، تسجيل الدخول مع github. افتح مستودعك المتشعب في gitpod عن طريق فتح الرابط التالي (استبدل your-username بحق حقيقي):
https://gitpod.io/#https://github.com/your-username/nextjs-prisma-boilerplate
ستقرأ بيئة Gitpod المتغيرات من مجلد envs/development-gitpod . قم بإنشاء ملف ENV المحلي من ملف مثال.
# terminal on Gitpod
cp envs/development-gitpod/.env.development.gitpod.local.example envs/development-gitpod/.env.development.gitpod.local في هذا الملف المحلي قم بتعيين عنوان URL لقاعدة البيانات من elephantsql.com . يتم تعيين متغيرات أخرى تلقائيا.
# envs/development-gitpod/.env.development.gitpod.local
DATABASE_URL=postgres://something:[email protected]/somethingالآن ترحيل وبذرة قاعدة البيانات.
ملاحظة: لا تحتوي قاعدة بيانات
elephantsql.comعلى جميع الامتيازات ، لذا يجب عليك استخدام أمرprisma pushبدلاً منprisma migrate dev. اقرأ المزيد من التفاصيل حول قاعدة بيانات الظل في المستندات/البيئات التجريبية.
# terminal on Gitpod
# migrate db
yarn gitpod:push:env
# seed db
yarn gitpod:seed:envتم إعداد كل شيء ، يمكنك الآن تشغيل التطبيق في وضع DEV وفتحه في علامة التبويب Browser New Browser.
yarn gitpod:dev:envيحتوي هذا المشروع على 4 تكوينات اختبار منفصلة بالإضافة إلى تكوين تغطية الرمز. يمكن أن تعمل جميع الاختبارات محليًا ، في Docker و Github الإجراءات.
ملاحظة: يمكنك أيضًا تشغيل وتصحيح جميع اختبارات Jest مع امتداد
orta.vscode-jestالذي تم تضمينه بالفعل في القائمة الموصى بها.
الجري محليا.
yarn test:clientالجري في Docker.
yarn docker:test:clientالجري محليا.
yarn test:server:unitالجري في Docker.
yarn docker:test:server:unitتأكد من أن قاعدة بيانات الاختبار قد تم ترحيلها. لا تحتاج إلى البذور.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envالجري محليا.
yarn test:server:integrationالجري في Docker.
yarn docker:test:server:integrationتحتاج إلى تشغيل قاعدة بيانات اختبار ، كما في الخطوة السابقة.
الجري محليا.
yarn test:coverageالجري في Docker.
yarn docker:test:coverageالجري محليا:
تحتاج إلى تشغيل قاعدة بيانات الاختبار وترحيلها (لا حاجة للبذور) ، وإنشاء تطبيق للإنتاج ، وتشغيل التطبيق وتشغيل Cypress.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envثم تحتاج إلى إنشاء تطبيق للإنتاج.
# build the app for prod
yarn buildثم تحتاج إلى بدء كل من التطبيق والسرو في نفس الوقت. هذا سوف يفتح السرو واجهة المستخدم الرسومية.
# starts the app and Cypress GUI
yarn test:e2e:envيمكنك أيضًا تشغيل Cypress في وضع Headless (بدون واجهة المستخدم الرسومية).
# starts the app and Cypress in headless mode
yarn test:e2e:headless:envالجري في Docker:
بناء كل من الصور و cypress.
# build testing app image
yarn docker:npb-app-test:build
# build Cypress container
yarn docker:npb-e2e:buildبعد ذلك ، يمكنك تشغيل قاعدة بيانات الاختبار وحاوية تطبيق التطبيق وحاوية Cypress (في الوضع غير المقطع) مرة واحدة.
# run db, app and Cypress headless
yarn docker:npb-e2e:upلقد صنعت مستودعًا منفصلًا Nemanjam/Traefik-proxy فقط للنشر مع الوكيل العكسي Traefik الذي يحتاج فقط إلى متغيرات البيئة والصورة من DockerHub. هناك أيضًا سير عمل إجراءات GitHub لإنشاء أحدث صورة على الخادم الخاص بك ودفعه وإعادة صياغته على الخادم الخاص بك. يجب عليك استخدام ذلك للنشر.
من أجل الاكتمال الذي وصفته هنا كيفية إنشاء تطبيق الإنتاج وتشغيله محليًا وفي Docker. يمكن أن يكون هذان الاثنان مفيدين كبيئات التدريج للاختبار. كما وصفت كيفية بناء ودفع الصورة المباشرة إلى Dockerhub من آلة التطوير المحلية.
عند إنشاء التطبيق وتشغيله في وضع الإنتاج ، ستقرأ المتغيرات من .env.production و .env.production.local . في وقت البناء ، يكون المتغير الوحيد المطلوب هو NEXTAUTH_URL (يتم استخدامه لعنوان URL الأساسي في مكون رأس CustomHead مسؤول عن كبار المسئولين الاقتصاديين). إذا كنت تستخدم getStaticProps (توليد الموقع الثابت) ، فستحتاج إلى تمرير DATABASE_URL أيضًا مع البيانات الصحيحة. في وقت التشغيل ، تحتاج إلى تحديد جميع المتغيرات العامة والخاصة في هذين الملفين.
لبناء وتشغيل تطبيق الإنتاج تشغيل هذين الأمرين.
# build app
yarn build
# start app
yarn start عند إنشاء تطبيق الإنتاج داخل صورة Docker مرة أخرى ، تحتاج إلى تمرير نفس المتغيرات محليًا ( NEXTAUTH_URL و DATABASE_URL لـ SSG) ، هذه المرة يتم إعادة توجيهها باستخدام ARG_NEXTAUTH_URL و ARG_DATABASE_URL في Dockerfile.prod . تتم قراءة متغيرات البيئة هذه من envs/production-docker/.env.production.docker و envs/production-docker/.env.production.docker.local . في وقت التشغيل ، تحتاج إلى تحديد جميع المتغيرات العامة والخاصة في هذين الملفين.
لبناء وتشغيل صورة إنتاج Docker تشغيل هذا.
# build production image
yarn docker:prod:build:env
# run production image
yarn docker:prod:up مرة أخرى ، تحتاج إلى تعيين NEXTAUTH_URL و DATABASE_URL (لـ SSG) هذه المرة في envs/production-live/.env.production.live.build.local . إنشاء هذا الملف من ملف مثال.
cp envs/production-live/.env.production.live.build.local.example envs/production-live/.env.production.live.build.localتحتاج إلى تحرير هذا البرنامج النصي الغزل وتعيين اسم مستخدم DockerHub الحقيقي واسم الصورة.
# replace your-dockerhub-username and your-image-name with yours
" docker:live:build " : " dotenv -e ./envs/production-live/.env.production.live.build.local -- bash -c 'docker build -f Dockerfile.prod -t your-dockerhub-username/your-image-name:latest --build-arg ARG_DATABASE_URL= ${DATABASE_URL} --build-arg ARG_NEXTAUTH_URL= ${NEXTAUTH_URL} .' " ,
يمكنك الآن بناء ووضع علامة ودفع إلى DockerHub صورة الإنتاج الخاصة بك. لدفع الصورة ، يجب عليك أولاً تسجيل الدخول في Terminal مع docker login .
# build and tag production image
yarn docker:live:build
# push image to Dockerhub
yarn docker:live:push يوجد بالفعل سير عمل إعداد لإنشاء ودفع صورة الإنتاج في إجراءات GitHub في .github/workflows/build-docker-image.yml . في إعدادات المستودع الخاص بك ، تحتاج فقط إلى تعيين هذه المتغيرات وتشغيل سير العمل.
# your dockerhub username
DOCKERHUB_USERNAME
# your dockerhub password
DOCKERHUB_TOKEN
# database url (only for SSG)
NPB_DATABASE_URL
# your live production app url (without trailing '/')
# i.e. https://subdomain.my-domain.com
NPB_NEXTAUTH_URL تحتاج فقط إلى تعيين اسم صورتك داخل docker-compose.live.yml ، وتمرير جميع متغيرات البيئة إليها ونشرها باستخدام docker-compose up -d على الخادم الخاص بك.
# docker-compose.live.yml
services :
npb-app-live :
container_name : npb-app-live
image : your-dockerhub-username/your-image-name:latest لهذا الغرض ، قمت بالفعل بإنشاء مستودع منفصل Nemanjam/Traefik-proxy مع الوكيل العكسي Traefik الذي يسمح لك باستضافة تطبيقات متعددة داخل حاويات Docker حيث تعرض كل حاوية منافذ منافذ وريفيك مختلفة إلى النطاقات الفرعية. للحصول على تفاصيل كيفية تكوين هذا ، راجع ملف README.md والتعليمي المرتبط به. تحتاج فقط إلى تشغيل حاوية التطبيق الخاصة بك وسيقوم Traefik تلقائيًا بتقاطها تلقائيًا دون الحاجة إلى إعادة تشغيل حاوية Traefik يدويًا.
إلى جانب Traefik ، يوجد بالفعل حاوية portainer لإدارة الحاويات ، وحاوية adminer لإدارة قاعدة بيانات الإنتاج ، uptime-kuma لتتبع وقت تشغيل موقع الويب ، وحاوية postgres أخرى تم تكوينها لقبول الاتصالات من المضيفين عن بُعد (مفيد لبناء التطبيق في إجراءات github).
تم إدراج Bellow جميع متغيرات البيئات التي تحتاج إلى تعيينها. من أجل البساطة ، لقد عرضت عليك هنا كيفية تعيينها في ملف .env المحلي ، وسيقوم ملف docker-compose.yml بقراءته وإعادة توجيه جميع المتغيرات المطلوبة إلى حاويات. هذا جيد للتطبيقات التجريبية ولكن لتطبيقات الإنتاج الحقيقية طريقة مناسبة للقيام بذلك هي تعيينها في لوحة القيادة الخاصة بمزود السحابة الخاص بك أو استخدام بعض قبو مخصص.
# create .env file locally and set vars
cp apps/nextjs-prisma-boilerplate/.env.example apps/nextjs-prisma-boilerplate/.env
# copy populated local .env file to server securely with ssh
scp ./apps/nextjs-prisma-boilerplate/.env ubuntu@your-server: ~ /traefik-proxy/apps/nextjs-prisma-boilerplateهذه كلها متغيرات مطلوبة.
MY_UIDوMY_GIDهما معرف للمستخدم الحالي ومجموعتك على خادم Linux الخاص بك. يمكنك رؤية قيمها عن طريق تشغيلid -uوid -gفي محطة الخادم الخاصة بك. أفضل مكان لضبطها على مستوى العالم في~/.bashrcلأنه يمكن أن تكون هناك حاجة إليها لحاويات متعددة. يتم تمريرها إلى حاوية postgres بحيث يتم إنشاء ملفات بيانات الصوت مع الأذونات والملكية الصحيحة (كمستخدم حالي وليس مستخدم الجذر).
# apps/nextjs-prisma-boilerplate/.env
# public vars bellow
APP_ENV=live
# http node server in live, Traefik handles https
SITE_PROTOCOL=http
# real full production public domain (with subdomain), used in app and Traefik
SITE_HOSTNAME=nextjs-prisma-boilerplate.nemanjamitic.com
PORT=3001
# real url is https and doesn't have port, Traefik handles https and port
NEXTAUTH_URL=https:// ${SITE_HOSTNAME}
# private vars bellow
# db container
POSTGRES_HOSTNAME=npb-db-live
POSTGRES_PORT=5432
POSTGRES_USER=postgres_user
POSTGRES_PASSWORD=
POSTGRES_DB=npb-db-live
# don't edit this
DATABASE_URL=postgresql:// ${POSTGRES_USER} : ${POSTGRES_PASSWORD} @ ${POSTGRES_HOSTNAME} : ${POSTGRES_PORT} / ${POSTGRES_DB} ? schema=public
# current host user as non-root user in Postgres container, set it here
MY_UID=1001
MY_GID=1001
# or better globally in ~/.bashrc
# export MY_UID=$(id -u)
# export MY_GID=$(id -g)
# jwt secret
SECRET=some-long-random-string
# Facebook
FACEBOOK_CLIENT_ID=
FACEBOOK_CLIENT_SECRET=
# Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET= لتجنب العمل اليدوي ، يوجد بالفعل سير العمل في إجراءات GitHub في .github/workflows/deploy.yml التي ستقوم بإزالة الصورة القديمة وسحب وتشغيل أحدث صورة من DockerHub باستخدام SSH Action. كل ما عليك فعله هو تشغيله إما يدويًا أو سلسلة من سير العمل والضغط على سير العمل الحالي.
# .github/workflows/deploy.yml
# trigger redeploy with build workflow
on :
workflow_run :
workflows : ['docker build'] هناك وثائق واسعة لهذا المشروع في مجلد المستندات. يمكنك العثور على جميع الجوانب التقنية الموثقة بعناية ، خاصة الأجزاء المهمة والصعبة. هناك يمكنك العثور على أوصاف المشكلة ، والحلول ، ومقتطفات التعليمات البرمجية والمراجع المرتبطة ذات الصلة.
تكون الوثائق حاليًا عارية بمعنى أنها تحمل معلومات تقنية عارية فقط كيفية حل شيء ما ولم يتم تقريبها في مقالات صديقة للإنسان مع سياق إضافي.
فيما يلي نظرة عامة موجزة على ما يمكنك العثور عليه فيه:
next-connect يحتوي على نقاط مهمة بشكل أساسي من مستندات وأمثلة JS الرسميةmkcert وتفاصيل رئيسية حول تسجيلات تسجيلات Google و Facebookv4 ، مكونات الاختبار والخطافات ، الترطيب ، بشكل رئيسي من المستندات ومدونة TKDODOnext-themes ، والموضوعات كتطبيق مخصص للمكون الإضافي من Daisyui من Daisyuiv4elephantsql.com لغرض العرض التجريبيgetServerSideProps ، والتعامل مع الأخطاء مع errorboundaries وتفاعل الاستعلام ، والخيارات strict strictNullChecksts-jest ، اختبارات Async مع استعلام React ، نماذج الاختبار ، فئة blob السخرية في jest-preview ، userevent v14 الترحيل ، التشويق والخطأ في الاختبارات ، MSW ، prisma السخرية في اختبارات الوحدة ، باستخدام Sucgenting Controllers مع اختبارات تكامل الخلفية مع بيانات الاختبار متعددة المشاريع. الإعداد ، تكوين تغطية الكودdocker-compose.ymlNODE_ENV و APP_ENV ، نشر VPS باستخدام SSH Actiongitpod.io و repl.it و codesandbox.io و stackblitz.com ، في مجلد envs و notes/envs لديك تكوين لجميع هذه البيئات ولكن فقط gitpod لديه ما يكفي من قوة الحوسبة لتشغيله فعليًاالمساهمات موضع ترحيب. يمكنك العثور على مزيد من المعلومات حول كيفية المساهمة في المساهمة.
Image next.js للصور المستضافة محليًاoutput: 'standalone' في next.config.jsprisma من تبعيات Prod مع حاوية منفصلة للهجرة دون جعل سير العمل معقدًا للغايةcypress: 10.x و next-connect: 1.x (لديهم تغييرات كسر)هناك الكثير من الكلام والنظرية والآراء والطنين حول أطر JavaScript ... ولكن دعنا نتوقف عن الحديث ، واختيار الإطار الأكثر شعبية ، وقراءة ما يقترحونه في الوثائق وتجربته في الممارسة العملية ، والتحقق من كيفية عمله ومعرفة ما إذا كان بإمكاننا بناء شيء مفيد وذات معنى معه.
نيمانجام ، لينكدين
يتم إرفاق روابط المراجع الكاملة في ملفات المستندات. أهم المراجع هي:
next-connect ، مثال على التطبيق Hoangvvo/NextJS-Mongodb-Appيستخدم هذا المشروع ترخيص MIT: ترخيص
