nextjs prisma boilerplate
1.0.0
這是圍繞最新Next.js堆棧建造的完整堆棧樣板。它是由官方文檔中描述的最佳實踐以及我從與其他人合作所獲得的經驗和知識中得出的決定所描述的。
不要花費接下來的3個月做出架構決策，選擇庫，設置開發和產品環境以及CI/CD管道，編寫樣板代碼，而要在15分鐘內安裝此樣板，然後立即開始處理您的功能。
如果應用程序破壞了，只需使用頁腳右側的
Reseed鏈接即可播放數據庫。
您需要GitPod帳戶，如果我的演示數據庫破壞了，則可能是Postgres數據庫URL。您可以在Elephantsql.com上創建一個，有關詳細信息，請參見GitPod環境部分。
next-auth電子郵件/密碼登錄等，可以重複使用vs vs代碼devcontainer等...） 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, React Hook Form 8-alpha , React Dropzone, Zod, msw, TailwindCSS 3 , Jest 28 , Testing Library React, Cypress 9.6.1 .
next-auth和Facebook，Google和憑據提供商進行身份驗證.env* files ...pages - > layouts - > views - > components!important陳述）next-connect API處理程序getServerSideProps全局錯誤處理testing-library/react用於單位和集成測試jest-preview視覺調試，用blob polyfill模擬的圖像，單獨的.env.test*文件沒有任何特殊調整，就有進一步改進的空間。
該項目有3個可用的開發環境：
您可以選擇任何喜歡的環境。
選擇哪一個？如果您喜歡傳統的方法選擇本地，那麼如果您在團隊中工作並希望與同事保持一致的環境，以輕鬆複製錯誤并快速在船上登上新成員，請選擇Docker，如果您想製作沙箱，請重現錯誤並尋求公開選擇GitPod。
克隆存儲庫和安裝依賴項。
# clone repository
git clone [email protected]:nemanjam/nextjs-prisma-boilerplate.git
cd nextjs-prisma-boilerplate
# install dependencies
yarn install當您首次打開項目文件夾VS代碼會要求您安裝推薦的擴展名時，您應該接受所有內容，它們需要強調，自動完成，棉布和格式代碼，運行測試，管理容器。
在.env.development中填寫所需的公共環境變量。最快的方法是使用http服務器運行該應用程序。
您僅在Facebook oauth登錄名中需要
https。為此，您需要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=設置所有變量後，您可以在Docker容器內運行Postgres數據庫，運行Prisma遷移，該遷移將從schema.prisma和帶有數據的種子數據庫中創建SQL表。
# 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克隆存儲庫構建應用程序容器後。
# 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運行應用程序，數據庫和管理容器。就是這樣。 Project文件夾已安裝到/app文件夾內部的容器中，您可以直接在主機上編輯源，也可以打開遠程容器擴展選項卡，然後右鍵單擊npb-app-dev ，然後在遠程VS代碼實例中選擇Attach to Container和“打開/app ”文件夾。打開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創建免費帳戶並創建免費的20MB 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在該本地文件中，從elephantsql.com設置了數據庫URL。其他變量是自動設置的。
# 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一切都設置了，您現在可以以開發模式運行該應用，然後在新的瀏覽器選項卡中打開它。
yarn gitpod:dev:env該項目具有4個單獨的測試配置以及代碼覆蓋範圍配置。所有測試都可以在Docker和GitHub動作中進行本地運行。
注意：您還可以使用
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在本地運行：
您需要運行和遷移測試數據庫（不需要種子），構建用於生產的應用程序，運行應用程序並運行柏樹。
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:env然後，您需要構建生產應用程序。
# build the app for prod
yarn build然後，您需要同時啟動應用程序和柏樹。這將打開柏樹GUI。
# starts the app and Cypress GUI
yarn test:e2e:env您也可以以無頭模式（無GUI）運行柏樹。
# starts the app and Cypress in headless mode
yarn test:e2e:headless:env在Docker中運行：
同時構建應用程序和柏樹圖像。
# build testing app image
yarn docker:npb-app-test:build
# build Cypress container
yarn docker:npb-e2e:build然後，您可以一次運行測試數據庫，測試應用程序容器和柏樹（以無頭模式）容器。
# run db, app and Cypress headless
yarn docker:npb-e2e:up我只用Traefik反向代理進行了一個單獨的存儲庫Nemanjam/traefik-proxy，它僅需要來自Dockerhub的環境變量和圖像。還可以在服務器上構建，推出和重新部署最新圖像的GitHub操作工作流程。您應該將其用於部署。
為了完整，我在這裡描述瞭如何在本地和Docker中構建和運行生產應用程序。這兩個可以用作測試的分期環境。我還描述瞭如何從當地開發機器中構建和將實時圖像構建到DockerHub。
在生產模式下構建和運行應用程序時，它將從.env.production和.env.production.local中讀取變量。在構建時間，唯一需要的變量是NEXTAUTH_URL （用於負責SEO的CustomHead組件中的基本URL）。如果使用getStaticProps （靜態站點生成），則需要使用正確的數據傳遞DATABASE_URL 。在運行時，您需要在這兩個文件中定義所有公共和私人變量。
構建和運行生產應用程序運行這兩個命令。
# build app
yarn build
# start app
yarn start再次在Docker映像中構建生產應用程序時，您需要通過類似於本地的變量（ NEXTAUTH_URL和DATABASE_URL for SSG），這次這些變量是通過ARG_NEXTAUTH_URL Dockerfile.prod中的arg_nextauth_url和arg_nextauth_url和arg_nextauth_url和ARG_DATABASE_URL轉發的。這次環境變量將從envs/production-docker/.env.production.docker and envs/production-docker/.env.production.docker.local讀取。在運行時，您需要在這兩個文件中定義所有公共和私人變量。
構建和運行Docker生產圖像運行此圖像。
# build production image
yarn docker:prod:build:env
# run production image
yarn docker:prod:up同樣，您需要在envs/production-live/.env.production.live.build.local中設置NEXTAUTH_URL和DATABASE_URL （對於SSG）。從示例文件中創建此文件。
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} .' " ,
現在，您可以構建，標記並推動將您的生產圖像停止。要推動圖像，您必須首先使用docker login登錄。
# build and tag production image
yarn docker:live:build
# push image to Dockerhub
yarn docker:live:push已經設置了工作流程，可以在.github/workflows/build-docker-image.yml中的github動作中構建和推動生產圖像。在您的存儲庫設置中，您只需要設置這些變量並運行工作流程即可。
# 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為此，我已經用Traefik反向代理製作了單獨的存儲庫Nemanjam/traefik-proxy，它允許您在Docker容器中託管多個應用程序，每個容器每個容器都會將不同的端口和Traefik Maps端口公開到子域中。有關如何配置此信息的詳細信息，請參見README.md文件和其中的鏈接教程。您只需要運行應用程序容器，而Traefik將自動拾取它，而無需手動重新啟動Traefik的容器。
除了Traefik之外，它還擁有用於管理容器的portainer容器，用於管理生產數據庫的adminer容器，用於跟踪網站正常運行時間的uptime-kuma以及其他配置的postgres容器，該容器配置為接受遠程主機的連接（用於在Github Action中構建應用程序）。
Bellow列出了您需要設置的所有環境變量。為了簡單起見，我在這裡向您展示瞭如何在local .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。您可以通過在服務器終端中運行id -u和id -g來查看它們的值。設置它們的最佳地點是在~/.bashrc中，因為多個容器可能需要它們。它們被傳遞到Postgres容器中，以便使用正確的權限和所有權（作為當前用戶而不是root用戶）創建卷數據文件。
# 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/workflows/deploy.yml中已經有GitHub操作工作流程，它將使用SSH Action從Dockerhub刪除舊圖像，並從Dockerhub撤下並運行最新圖像。您需要做的就是手動觸發它或在現有構建和推動工作流程上鍊接。
# .github/workflows/deploy.yml
# trigger redeploy with build workflow
on :
workflow_run :
workflows : ['docker build'] 該項目在Docs文件夾中有大量文檔。您可以找到所有經過精心記錄的技術方面，尤其是重要且困難的部分。在那裡，您可以找到問題描述，解決方案，代碼段和相關的鏈接引用。
目前的文檔是裸露的，從某種意義上說，它僅擁有裸露的技術信息如何解決某些問題，並且在具有其他背景下的人類友好文章中沒有圍繞。
這是您可以在其中找到的簡要概述：
next-connect重要點mkcert棘手部分v4遷移，測試組件和鉤子，水合，主要來自DOCS和TKDODO博客next-themes配置，主題作為Daisyui的自定義尾風插件實現v4遷移指南elephantsql.com設置用於演示目的getServerSideProps中的錯誤，使用錯誤孔處理錯誤並進行react Query，Typescript strict和strictNullChecks選項ts-jest setup, async tests with React Query, testing forms, mocking Blob class in jsdom for images, userEvent v14 migration, Suspense and ErrorBoundary in tests, msw, mocking Prisma in unit tests, using Supertest for testing controllers, backend integration tests with test database, multi projects Jest setup, running tests inside Docker and Github Actions, jest-preview設置，代碼覆蓋範圍配置docker-compose.ymlNODE_ENV和APP_ENV變量，使用SSH Action部署VPSnotes/envs codesandbox.io gitpod.io stackblitz.com repl.it此應用envs文檔歡迎捐款。您可以找到更多信息如何為貢獻做出貢獻。
Image組件用於本地託管的圖像output: 'standalone' next.config.js中的'獨立'構建選項prisma ，以進行遷移，而不會使工作流太複雜cypress: 10.x和next-connect: 1.x （它們具有破壞更改）JavaScript框架周圍有很多討論，理論，觀點和嗡嗡聲……但是讓我們停止說話，選擇最受歡迎的框架，閱讀他們在文檔中的建議，並在實踐中嘗試一下，檢查它的工作原理，並查看我們是否可以對其構建有用和有意義的東西。
Nemanjam，LinkedIn
文檔文件中附有完整的參考鏈接。最重要的參考是：
next-connect ，示例應用程序Hoangvvo/NextJS-MongoDB-App該項目使用MIT許可證：許可證
