nextjs prisma boilerplate
1.0.0
Dies ist eine vollständige Stack -Boilerplate, die sich um den neuesten. Js -Stack in der neuesten.js -Stack befindet. Es besteht aus den Best Practices, die in offiziellen Dokumenten in Kombination mit meinen Entscheidungen aus meiner eigenen Erfahrung und meinem eigenen Wissen, die ich aus der Arbeit mit anderen Menschen gesammelt habe, beschrieben.
Verbringen Sie die nächsten 3 Monate nicht damit, architektonische Entscheidungen zu treffen, Bibliotheken auszuwählen, Entwicklungs- und Produktumgebungen und CI/CD -Pipelines einzurichten, das Boilerplate -Code zu schreiben, stattdessen diese Boilerplate in 15 Minuten zu installieren und noch heute an Ihren Funktionen zu arbeiten.
Wenn die App zerstört wird, verwenden Sie einfach
ReseedLink auf der rechten Seite der Fußzeile, um die Datenbank neu zu erstellen.
Sie benötigen ein Gitpod -Konto und posten Sie möglicherweise die Datenbank -URL, wenn meine Demo -Datenbank zerstört wird. Weitere Informationen finden Sie unter Elephantsql.com. Weitere Informationen finden Sie in GitPod Umgebung.
next-auth usw. wiederverwendet werden.) 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, Tailwindcs 3 , Jest 28 , Testing Bibliothek, Cypypypress 9.6.1 .
next-auth und Facebook, Google und Anmeldeinformationen.env* -Dateien ...pages -> layouts -> views -> components!important Anweisung im gesamten Code)next-connect API-HandlergetServerSideProps mit benutzerdefinierter Fehlerklassetesting-library/react für Einheiten- und Integrationstestsjest-preview , Bilder mit Blob Polyfill verspottet, separat .env.test* DateienOhne besondere Anpassungen gibt es Raum für weitere Verbesserungen.
Dieses Projekt verfügt über 3 verfügbare Entwicklungsumgebungen:
Sie können jede Umgebung auswählen, die Sie bevorzugen.
Welches zu wählen? Wenn Sie einen konventionellen Ansatz mögen, wählen Sie lokal aus, wenn Sie in einem Team arbeiten und konsistente Umgebungen mit Kollegen haben möchten, um Fehlern problemlos zu reproduzieren und neue Mitglieder schnell an Bord von Docker zu wählen.
Klon -Repository und Installation von Abhängigkeiten.
# clone repository
git clone [email protected]:nemanjam/nextjs-prisma-boilerplate.git
cd nextjs-prisma-boilerplate
# install dependencies
yarn installWenn Sie zum ersten Mal den Projektordner öffnen, werden Sie aufgefordert, empfohlene Erweiterungen zu installieren. Sie sollten sie alle akzeptieren. Sie werden benötigt, um die automatischen Vervollständigung, den FINT- und Formatcode zu markieren, Tests auszuführen, Container zu verwalten.
Füllen Sie die erforderlichen Variablen der öffentlichen Umgebung in .env.development ein. Der schnellste Weg besteht darin, die App mit http -Server auszuführen.
Sie benötigen
httpslokal nur für Facebook OAuth Login. Dafür benötigen Siemkcert, um Zertifikate fürlocalhostzu installieren. Anweisungen dafür finden Sie im Ordnerdocs.
Lassen Sie PORT als 3001, er ist an mehreren Stellen festcodiert. Wenn Sie ihn ändern möchten, müssen Sie alle bearbeiten (dh alle Dockerfile.* Und 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} Create .env.development.local Datei.
# create local file form example file
cp .env.development.local.example .env.development.local
In allen Umgebungen ist Postgres-Container so konfiguriert, dass er als aktueller Nicht-Root-Benutzer auf einem Linux-Host-Computer ausgeführt wird. Dies ist wichtig, damit Datenbankdateien in Mengen mit korrektem Eigentum und Berechtigungen erstellt werden. Dafür müssen Sie MY_UID und MY_GID definieren. Der beste Ort, um sie einzustellen, ist in ~/.bashrc .
# ~/.bashrc
export MY_UID= $( id -u )
export MY_GID= $( id -g )Füllen Sie die erforderlichen Variablen für private Umgebung aus. Die einzigen erforderlichen Variablen sind für die Postgres -Datenbankverbindung und das JWT -Geheimnis.
Facebook- und Google -Anmeldeinformationen sind optional und nur für OAuth -Login verwendet. Das Facebook -Login erfordert
httpsfür die Umleitungs -URL. Sie können alle Werte fürPOSTGRES_USER,POSTGRES_PASSWORDundPOSTGRES_DBfestlegen.
# .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= Nachdem alle Variablen festgelegt sind, können Sie die Postgres -Datenbank im Docker -Container ausführen, Prisma -Migrationen ausführen, die SQL -Tabellen aus schema.prisma und Seed -Datenbank mit Daten erstellen.
# 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 Zu diesem Zeitpunkt ist alles fertig, Sie können jetzt die App starten. Öffnen Sie http://localhost:3001 im Browser, um die laufende App anzuzeigen.
# start the app in dev mode
yarn devNachdem Sie das Repository -Build -App -Container geklont haben.
# terminal on host
yarn docker:dev:build Die Docker-Umgebung lesen Variablen aus dem Ordner envs/development-docker . Erstellen Sie eine lokale Env -Datei aus der Beispieldatei. Es verfügt über alle Variablen bereits konfiguriert.
# terminal on host
cp envs/development-docker/.env.development.docker.local.example envs/development-docker/.env.development.docker.local Führen Sie die App-, Datenbank- und Adminer -Container aus. Das war's. Der Projektordner ist in den Ordner /app im Container montiert. Sie können die Quelle entweder direkt auf dem Host bearbeiten oder die Registerkarte "Remote Container" und mit der rechten Maustaste auf npb-app-dev klicken und Attach to Container und den Ordner "Remote-VS-Code öffnen /app auswählen. Öffnen Sie http://localhost:3001 im Browser auf Host, um die laufende App zu sehen.
# terminal on host
yarn docker:dev:up Öffnen Sie das neue Terminal im Container und säen Sie die Datenbank, docker-compose.dev.yml überträgt bereits die richtigen Env-Dateien.
# terminal inside the container
yarn prisma:seedHinweis: Git existiert bereits in Container mit Ihrem Konto, sodass Sie Änderungen direkt aus dem Container festlegen und drücken können.
# check that git config is already set inside the container
git config --list --show-originIch schlage vor, Sie installieren den Container der Portainer Community Edition lokal, um Container zu leichtern und zu debuggen, und es ist ein kostenloses und sehr nützliches Tool.
Gehen Sie zu Elephantsql.com KOSTENLOSES Konto und erstellen Sie kostenlose 20 -MB -Postgres -Datenbank. Gehen Sie zu Gitpod.io, melden Sie sich mit GitHub an. Öffnen Sie Ihr Forked Repository in Gitpod, indem Sie den folgenden Link öffnen (Ersetzen Sie your-username durch echte):
https://gitpod.io/#https://github.com/your-username/nextjs-prisma-boilerplate
Die GITPOD-Umgebung liest Variablen aus envs/development-gitpod . Erstellen Sie eine lokale Env -Datei aus der Beispieldatei.
# terminal on Gitpod
cp envs/development-gitpod/.env.development.gitpod.local.example envs/development-gitpod/.env.development.gitpod.local Setzen Sie in dieser lokalen Datei die Datenbank -URL von elephantsql.com . Andere Variablen werden automatisch eingestellt.
# envs/development-gitpod/.env.development.gitpod.local
DATABASE_URL=postgres://something:[email protected]/somethingMigrieren Sie nun die Datenbank.
Hinweis:
elephantsql.com-Datenbank hat nicht alle Berechtigungen, daher müssen Sieprisma push-Befehl anstelle von üblichenprisma migrate devverwenden. Weitere Informationen zu Shadow-Datenbank finden Sie in DOCS/Demo-Environments.md.
# terminal on Gitpod
# migrate db
yarn gitpod:push:env
# seed db
yarn gitpod:seed:envAlles ist eingerichtet, Sie können die App jetzt im Dev -Modus ausführen und auf der Registerkarte "New Browser" öffnen.
yarn gitpod:dev:envDieses Projekt verfügt über 4 separate Testkonfigurationen sowie Code -Abdeckungskonfiguration. Alle Tests können lokal, in Docker und in GitHub -Aktionen ausgeführt werden.
Hinweis: Sie können auch alle Scherztests mit
orta.vscode-jestErweiterung ausführen und debuggen, die bereits in der empfohlenen Liste enthalten sind.
Vor Ort laufen.
yarn test:clientLaufen in Docker.
yarn docker:test:clientVor Ort laufen.
yarn test:server:unitLaufen in Docker.
yarn docker:test:server:unitStellen Sie sicher, dass diese Testdatenbank abgelaufen und migriert ist. Sie müssen es nicht säen.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envVor Ort laufen.
yarn test:server:integrationLaufen in Docker.
yarn docker:test:server:integrationSie benötigen eine ausgeführte Testdatenbank, wie im vorherigen Schritt.
Vor Ort laufen.
yarn test:coverageLaufen in Docker.
yarn docker:test:coverageVor Ort laufen:
Sie müssen die Testdatenbank ausführen und migrieren (keine Saatgut erforderlich), die App für die Produktion erstellen, die App ausführen und Zypressen ausführen.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envDann müssen Sie App für die Produktion erstellen.
# build the app for prod
yarn buildDann müssen Sie gleichzeitig App und Cypress starten. Dies wird Cypress GUI eröffnen.
# starts the app and Cypress GUI
yarn test:e2e:envSie können auch Cypress im Kopflosenmodus (ohne GUI) ausführen.
# starts the app and Cypress in headless mode
yarn test:e2e:headless:envLaufen in Docker:
Erstellen Sie sowohl App- als auch Zypressenbilder.
# build testing app image
yarn docker:npb-app-test:build
# build Cypress container
yarn docker:npb-e2e:buildAnschließend können Sie die Testdatenbank, den Test -App -Container und den Cypress (im Kopflosenmodus) gleichzeitig ausführen.
# run db, app and Cypress headless
yarn docker:npb-e2e:upIch habe ein separates Repository Nemanjam/Traefik-Proxy nur für die Bereitstellung mit Traefik Reverse Proxy erstellt, die nur Umgebungsvariablen und Bild von DockerHub benötigt. Es gibt auch Workflows mit GitHub -Aktionen, um das neueste Bild auf Ihrem Server zu erstellen, zu pushen und neu einzuschalten. Sie sollten das zur Bereitstellung verwenden.
Aus Vollständigkeit habe ich hier beschrieben, wie man die Produktions -App lokal und in Docker erstellt und ausführt. Diese beiden können als Staging -Umgebungen zum Testen nützlich sein. Ich habe auch beschrieben, wie man Live -Image von Ihrer lokalen Entwicklungsmaschine auf DockerHub aufbaut und weitergibt.
Beim Erstellen und Ausführen von App im Produktionsmodus werden Variablen von .env.production und .env.production.local gelesen. Zum Bauzeit ist die einzige erforderliche Variable NEXTAUTH_URL (sie wird für die Basis -URL in CustomHead -Komponente verwendet, die für SEO verantwortlich ist). Wenn Sie getStaticProps (statische Site -Generierung) verwenden, müssen Sie auch DATABASE_URL mit korrekten Daten übergeben. Zur Laufzeit müssen Sie alle öffentlichen und privaten Variablen in diesen beiden Dateien definieren.
Um die Produktions -App zu erstellen und auszuführen, führen Sie diese beiden Befehle aus.
# build app
yarn build
# start app
yarn start Wenn Sie erneut die Produktions -App in einem Docker -Bild erstellen, müssen Sie die gleichen Variablen wie lokal ( NEXTAUTH_URL und DATABASE_URL für SSG) übergeben, diesmal werden diese mit ARG_NEXTAUTH_URL und ARG_DATABASE_URL in Dockerfile.prod weitergeleitet. Diese Zeiten werden Umgebungsvariablen aus envs/production-docker/.env.production.docker und envs/production-docker/.env.production.docker.local gelesen. Zur Laufzeit müssen Sie alle öffentlichen und privaten Variablen in diesen beiden Dateien definieren.
Um das Docker -Produktionsbild zu erstellen und auszuführen, leiten Sie dies aus.
# build production image
yarn docker:prod:build:env
# run production image
yarn docker:prod:up Auch hier müssen Sie diesmal NEXTAUTH_URL und DATABASE_URL (für SSG) in envs/production-live/.env.production.live.build.local festlegen. Erstellen Sie diese Datei aus der Beispieldatei.
cp envs/production-live/.env.production.live.build.local.example envs/production-live/.env.production.live.build.localSie müssen dieses Garnskript bearbeiten und Ihren echten DockerHub -Benutzernamen und Ihren Bildnamen festlegen.
# 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} .' " ,
Sie können jetzt Ihr Produktionsbild erstellen, markieren und drängen, um DockerHub zu erstellen. Um das Bild zu drücken, müssen Sie sich zunächst mit docker login im Terminal anmelden.
# build and tag production image
yarn docker:live:build
# push image to Dockerhub
yarn docker:live:push Es gibt bereits Workflows, um das Produktionsbild in GitHub-Aktionen in .github/workflows/build-docker-image.yml zu erstellen und zu schieben. In Ihren Repository -Einstellungen müssen Sie diese Variablen nur festlegen und Workflow ausführen.
# 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 Sie müssen nur Ihren Bildnamen in docker-compose.live.yml festlegen, alle Umgebungsvariablen an ihn übergeben und mit docker-compose up -d auf Ihrem Server bereitstellen.
# docker-compose.live.yml
services :
npb-app-live :
container_name : npb-app-live
image : your-dockerhub-username/your-image-name:latest Zu diesem Zweck habe ich bereits separate Repository Nemanjam/Traefik-Proxy mit Traefik Reverse Proxy erstellt, mit dem Sie mehrere Apps in Docker-Containern hosten können, bei denen jeder Container unterschiedliche Port- und Traefik-Kartenports in Subdomains aussetzt. Weitere Informationen, wie Sie diese konfigurieren, siehe README.md -Datei und verknüpftes Tutorial darin. Sie müssen nur Ihren App -Container ausführen, und Traefik wird sie automatisch abholen, ohne dass Sie den Container von Traefik manuell neu starten müssen.
Neben Traefik verfügt es auch über portainer Container zum Verwalten von Containern, adminer Container für die Verwaltung der Produktionsdatenbank, zur Verfügung uptime-kuma für die Verfolgung der Website der Website und ein weiterer postgres Container, der zum Akzeptieren von Verbindungen von Remote-Hosts konfiguriert ist (nützlich für das Erstellen von Apps in GitHub-Aktionen).
Unten sind alle Umgebungen aufgelistet, die Sie festlegen müssen. Aussofern habe ich Ihnen hier gezeigt, wie Sie sie in der lokalen .env Datei festlegen, docker-compose.yml -Datei wird sie lesen und alle benötigten Variablen in Container weiterleiten. Dies ist für Demo -Apps in Ordnung, aber für echte Produktions -Apps, um dies zu tun, können Sie sie in das Dashboard Ihres Cloud -Anbieters einstellen oder ein dediziertes Tresor verwenden.
# 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-boilerplateDies sind alles benötigte Variablen.
MY_UIDundMY_GIDsind IDs Ihres aktuellen Benutzer und Gruppen auf Ihrem Linux -Server. Sie können ihre Werte sehen, indem Sieid -uundid -gim Terminal Ihres Servers ausführen. Der beste Ort, um sie einzustellen, ist weltweit in~/.bashrcda sie für mehrere Behälter benötigt werden können. Sie werden in den Postgres -Container übergeben, damit Volumendatendateien mit korrekten Berechtigungen und Eigentum erstellt werden (als aktueller Benutzer und nicht als Root -Benutzer).
# 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= Um manuelle Arbeiten zu vermeiden, gibt es bereits GitHub -Aktionen Workflows in .github/workflows/deploy.yml das das alte Bild entfernen und das neueste Bild von DockerHub mithilfe von SSH -Aktion abzieht und ausführt. Alles, was Sie tun müssen, ist, es entweder manuell auszulösen oder auf vorhandenen Build und Push -Workflow zu ketten.
# .github/workflows/deploy.yml
# trigger redeploy with build workflow
on :
workflow_run :
workflows : ['docker build'] Es gibt eine umfangreiche Dokumentation für dieses Projekt im DOCS -Ordner. Sie können alle technischen Aspekte sorgfältig dokumentiert finden, insbesondere wichtige und schwierige Teile. Dort finden Sie Problembeschreibungen, Lösungen, Codeausschnitte und zugehörige verknüpfte Referenzen.
Derzeit ist die Dokumentation in gewissem Sinne klopft, dass es nur bares technische Informationen enthält, wie man etwas löst, und es ist nicht in menschlichen freundlichen Artikeln mit zusätzlichem Kontext abgerundet.
Hier ist der kurze Überblick darüber, was Sie darin finden können:
next-connectmkcert und Schlüsseldetails zu Google und Facebook Loginsv4 -Migration, Testkomponenten und Haken, Hydratation, hauptsächlich aus DOCS und TKDODO -Blognext-themes , Themen als benutzerdefinierte Rückenwind -Plugin -Implementierung von Daisyuiv4 -Migrationshandbuchelephantsql.comgetServerSideProps , Handhabung von Fehler mit FehlerBoundaries und React Query, Typscript strict und strictNullChecks -Optionents-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 Setup, Codeabdeckungskonfigurationdocker-compose.yml , Live -Produktionscontainer -Setup, benutzerdefiniertes ZypressenbildNODE_ENV und APP_ENV -Variablen, VPS -Bereitstellung mithilfe der SSH -Aktiongitpod.io , repl.it , codesandbox.io und stackblitz.com , im Ordner envs und notes/envs haben Sie Konfiguration für all diese Umgebungen, aber nur Gitpod verfügtBeiträge sind willkommen. Weitere Informationen finden Sie zum Beitrag zum Beitrag.
Image für lokal gehostete Bilder hinzuoutput: 'standalone' -Aption in next.config.jsprisma aus Prod -Abhängigkeiten mit separatem Behälter für Migrationen zu entfernen, ohne den Workflow zu kompliziert zu machencypress: 10.x und next-connect: 1.x (sie haben Bruchänderungen)Es gibt viel Gespräch, Theorie, Meinungen und Summen in den JavaScript -Frameworks ... aber lassen Sie uns aufhören zu reden, das beliebteste Framework auszuwählen, zu lesen, was sie in der Dokumentation vorschlagen, und probieren Sie es in der Praxis aus, überprüfen Sie, wie es funktioniert, und sehen Sie, ob wir etwas Nützliches und Sinnvolles damit aufbauen können.
Nemanjam, LinkedIn
Komplette Referenzen Links werden in DOCS -Dateien beigefügt. Die wichtigsten Referenzen sind:
next-connect , Beispiel App Hoangvvo/Nextjs-mongoDB-AppDieses Projekt verwendet die MIT -Lizenz: Lizenz
