nextjs prisma boilerplate
1.0.0
Il s'agit de la plaquette complète complète construite autour de la dernière pile Next.js. Il est composé des meilleures pratiques décrites dans les documents officiels combinés à mes décisions dérivées de ma propre expérience et de ma connaissance que j'ai recueillies en travaillant avec d'autres personnes.
Ne passez pas les 3 prochains mois à prendre des décisions architecturales, à choisir des bibliothèques, à configurer des environnements Dev et Prod et des pipelines CI / CD, en écrivant du code de passe-partout, installez plutôt cette passe-partout en 15 minutes et commencez à travailler sur vos fonctionnalités aujourd'hui .
Si l'application est vandalisée, utilisez simplement un lien
Reseedsur le côté droit du pied de page pour réenserver la base de données.
Vous avez besoin d'un compte Gitpod et peut-être de l'URL de la base de données Postgres si ma base de données de démonstration est vandalisée. Vous pouvez en créer un sur elephantsql.com, voir la section Gitpod Environment pour plus de détails.
next-auth , etc ...) REACT.JS 18.2.0 , Prisma 4 , 14.3 12.2.0 , TypeScript 16.13.1 , React Query 4- 4.7.4 , Axios, React Hook Form 4-beta 8-alpha , React Dropzone, Zod, MSW, Tailwindcss 3 , Jest 28 , Testing Library React, Cypress 9.6.1 .
next-auth et Facebook, Google et les informations d'identification.env* ...pages structure de composants évolutives et découplées -> layouts -> views -> components!important dans le code entier)next-connect avec des middleware pour la validation et les itinéraires protégésgetServerSideProps avec une classe d'erreur personnaliséetesting-library/react pour les tests d'unité et d'intégrationjest-preview , images moquées de polyfill blob, fichiers .env.test* séparésSans aucun ajustement spécial, il y a place à une amélioration supplémentaire.
Ce projet dispose de 3 environnements de développement disponibles:
Vous pouvez choisir l'environnement que vous préférez.
Lequel choisir? Si vous aimez l'approche conventionnelle, choisissez Local, si vous travaillez en équipe et que vous souhaitez avoir des environnements cohérents avec des collègues pour reproduire facilement des bogues et rapidement à bord de nouveaux membres, choisissez Docker, et si vous voulez faire du bac à sable, reproduisez un bug et demandez de l'aide envers Gitpod.
Référentiel de clones et dépenses d'installation.
# clone repository
git clone [email protected]:nemanjam/nextjs-prisma-boilerplate.git
cd nextjs-prisma-boilerplate
# install dependencies
yarn installLorsque vous ouvrez le dossier de projet pour la première fois VS Code vous demandera d'installer des extensions recommandées, vous devez les accepter tous, ils sont nécessaires pour mettre en surbrillance, la saisie automatique, le peluche et le code de format, exécuter des tests, gérer les conteneurs.
Remplissez les variables de l'environnement public requises en .env.development . Le moyen le plus rapide est d'exécuter l'application avec le serveur http .
Vous avez besoin
httpslocalement uniquement pour Facebook OAuth Connexion. Pour cela, vous avez besoinmkcertpour installer des certificats pourlocalhost, des instructions pour que vous puissiez trouver dans le dossierdocs.
Laissez PORT en 3001, il est codé en dur à plusieurs endroits, si vous voulez le changer, vous devez tous les modifier (c'est-à-dire tous Dockerfile.* Et 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} Créer un fichier .env.development.local .
# create local file form example file
cp .env.development.local.example .env.development.local
Dans tous les environnements, le conteneur Postgres est configuré pour s'exécuter en tant qu'utilisateur actuel non racine sur une machine hôte Linux. Ceci est important pour que les fichiers de base de données en volumes soient créés avec la propriété et les autorisations correctes. Pour cela, vous devez définir MY_UID et MY_GID . Le meilleur endroit pour les régler est dans ~/.bashrc .
# ~/.bashrc
export MY_UID= $( id -u )
export MY_GID= $( id -g )Remplissez les variables d'environnement privées requises. Les seules variables requises sont pour la connexion de la base de données Postgres et le secret JWT.
Facebook et Google les informations d'identification sont facultatifs et utilisés uniquement pour la connexion OAuth. La connexion Facebook nécessite
httpspour la redirection URL. Vous pouvez définir toutes les valeurs pourPOSTGRES_USER,POSTGRES_PASSWORDetPOSTGRES_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= Une fois que toutes les variables sont définies, vous pouvez exécuter la base de données Postgres à l'intérieur du conteneur Docker, exécuter des migrations Prisma qui créeront des tables SQL à partir de la base de données schema.prisma et des semences avec des données.
# 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 À ce stade, tout est prêt, vous pouvez maintenant démarrer l'application. Ouvrez http://localhost:3001 dans le navigateur pour voir l'application en cours d'exécution.
# start the app in dev mode
yarn devAprès avoir cloné le conteneur de l'application de construction du référentiel.
# terminal on host
yarn docker:dev:build L'environnement Docker lira les variables du dossier envs/development-docker . Créez un fichier Env local à partir d'un exemple de fichier. Il a déjà toutes les variables configurées.
# terminal on host
cp envs/development-docker/.env.development.docker.local.example envs/development-docker/.env.development.docker.local Exécutez les conteneurs de l'application, de la base de données et de l'administration. C'est ça. Le dossier du projet est monté sur le dossier /app dans le conteneur, vous pouvez soit modifier la source directement sur l'onglet Extension des conteneurs distants ou ouvrir le dossier npb-app-dev et sélectionner le dossier Attach to Container et ouvrir /app dans l'instance de télécommande vs de code. Ouvrez http://localhost:3001 dans le navigateur sur l'hôte pour voir l'application en cours d'exécution.
# terminal on host
yarn docker:dev:up Ouvrez un nouveau terminal à l'intérieur du conteneur et semencez la base de données, docker-compose.dev.yml transmet déjà des fichiers Env corrects.
# terminal inside the container
yarn prisma:seedRemarque: Git existera déjà dans le conteneur avec votre compte afin que vous puissiez engager et pousser les modifications directement à partir du conteneur.
# check that git config is already set inside the container
git config --list --show-originJe vous suggère d'installer localement Portainener Community Edition pour une gestion et un débogage plus faciles, c'est un outil gratuit et très utile.
Allez sur elephantsql.com Créez un compte gratuit et créez une base de données postgres gratuite de 20 Mo. Allez sur gitpod.io, connectez-vous avec github. Ouvrez votre référentiel fourchu dans Gitpod en ouvrant le lien suivant (remplacez your-username par un vrai):
https://gitpod.io/#https://github.com/your-username/nextjs-prisma-boilerplate
L'environnement Gitpod lira les variables du dossier envs/development-gitpod . Créez un fichier Env local à partir d'un exemple de fichier.
# terminal on Gitpod
cp envs/development-gitpod/.env.development.gitpod.local.example envs/development-gitpod/.env.development.gitpod.local Dans ce fichier local, définissez l'URL de la base de données de elephantsql.com . D'autres variables sont définies automatiquement.
# envs/development-gitpod/.env.development.gitpod.local
DATABASE_URL=postgres://something:[email protected]/somethingMigrez maintenant et semenez la base de données.
Remarque: la base de données
elephantsql.comn'a pas tous les privilèges, vous devez donc utiliser la commandeprisma pushau lieu deprisma migrate dev. Lisez plus de détails sur la base de données Shadow dans Docs / Demo-Environments.md.
# terminal on Gitpod
# migrate db
yarn gitpod:push:env
# seed db
yarn gitpod:seed:envTout est configuré, vous pouvez désormais exécuter l'application en mode Dev et l'ouvrir dans un nouvel onglet de navigateur.
yarn gitpod:dev:envCe projet a 4 configurations de test distinctes plus la configuration de la couverture de code. Tous les tests peuvent s'exécuter localement, dans Docker et dans les actions GitHub.
Remarque: Vous pouvez également exécuter et déboguer tous les tests de plaisanterie avec une extension
orta.vscode-jestqui est déjà incluse dans la liste recommandée.
Courir localement.
yarn test:clientCourir dans Docker.
yarn docker:test:clientCourir localement.
yarn test:server:unitCourir dans Docker.
yarn docker:test:server:unitAssurez-vous que la base de données de test est en hausse et migré. Vous n'avez pas besoin de le semer.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envCourir localement.
yarn test:server:integrationCourir dans Docker.
yarn docker:test:server:integrationVous avez besoin d'exécuter la base de données de test, comme à l'étape précédente.
Courir localement.
yarn test:coverageCourir dans Docker.
yarn docker:test:coverageCourir localement:
Vous devez exécuter et migrer la base de données de test (pas besoin de semences), créer l'application pour la production, exécuter l'application et exécuter Cypress.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envEnsuite, vous devez créer une application pour la production.
# build the app for prod
yarn buildEnsuite, vous devez démarrer à la fois l'application et le cyprès en même temps. Cela ouvrira Cypress GUI.
# starts the app and Cypress GUI
yarn test:e2e:envVous pouvez également exécuter Cypress en mode sans tête (sans GUI).
# starts the app and Cypress in headless mode
yarn test:e2e:headless:envCourir dans Docker:
Créez des images d'application et de cyprès.
# build testing app image
yarn docker:npb-app-test:build
# build Cypress container
yarn docker:npb-e2e:buildEnsuite, vous pouvez exécuter la base de données de test, le conteneur d'applications de test et le conteneur Cypress (en mode sans tête) à la fois.
# run db, app and Cypress headless
yarn docker:npb-e2e:upJ'ai fait un référentiel séparé Nemanjam / Trafik-Proxy uniquement pour le déploiement avec un proxy inversé Trafik qui n'a besoin que de variables d'environnement et d'image de DockerHub. Il existe également des workflows GitHub Actions pour construire, pousser et redéployer la dernière image la dernière image sur votre serveur. Vous devez l'utiliser pour le déploiement.
Par souci d'exhaustivité que j'ai décrit ici comment créer et exécuter l'application de production localement et dans Docker. Ces deux peuvent être utiles comme environnements de mise en scène pour les tests. J'ai également décrit comment construire et pousser l'image en direct vers Dockerhub à partir de votre machine de développement locale.
Lors de la création et de l'exécution de l'application en mode de production, il lira les variables de .env.production et .env.production.local . Au moment de la construction, la seule variable requise est NEXTAUTH_URL (il est utilisé pour l'URL de base dans le composant CustomHead responsable du référencement). Si vous utilisez getStaticProps (Génération de sites statiques), vous devrez également transmettre DATABASE_URL avec des données correctes. Au moment de l'exécution, vous devez définir toutes les variables publiques et privées dans ces deux fichiers.
Pour créer et exécuter l'application de production, exécutez ces deux commandes.
# build app
yarn build
# start app
yarn start Lors de la création de l'application de production à nouveau dans une image Docker, vous devez passer les mêmes variables comme localement ( NEXTAUTH_URL et DATABASE_URL pour SSG), cette fois, ceux-ci sont transmis avec ARG_NEXTAUTH_URL et ARG_DATABASE_URL dans Dockerfile.prod . Cette fois, les variables d'environnement sont lues à partir d' envs/production-docker/.env.production.docker et envs/production-docker/.env.production.docker.local . Au moment de l'exécution, vous devez définir toutes les variables publiques et privées dans ces deux fichiers.
Pour construire et exécuter l'image de production Docker, exécutez ceci.
# build production image
yarn docker:prod:build:env
# run production image
yarn docker:prod:up Encore une fois, vous devez définir NEXTAUTH_URL et DATABASE_URL (pour SSG) cette fois dans envs/production-live/.env.production.live.build.local . Créez ce fichier à partir d'un exemple de fichier.
cp envs/production-live/.env.production.live.build.local.example envs/production-live/.env.production.live.build.localVous devez modifier ce script de fil et définir votre vrai nom d'utilisateur Dockerhub et votre nom d'image.
# 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} .' " ,
Vous pouvez maintenant construire, étiqueter et pousser pour Dockerhub votre image de production. Pour pousser l'image, vous devez d'abord vous connecter dans le terminal avec docker login .
# build and tag production image
yarn docker:live:build
# push image to Dockerhub
yarn docker:live:push Il y a déjà une configuration de workflow pour construire et pousser l'image de production dans les actions GitHub dans .github/workflows/build-docker-image.yml . Dans vos paramètres de référentiel, vous avez juste besoin de définir ces variables et d'exécuter un flux de travail.
# 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 Il vous suffit de définir le nom de votre image dans docker-compose.live.yml , passez toutes les variables d'environnement et le déployez-le avec docker-compose up -d sur votre serveur.
# docker-compose.live.yml
services :
npb-app-live :
container_name : npb-app-live
image : your-dockerhub-username/your-image-name:latest À cette fin, j'ai déjà fait un référentiel séparé Nemanjam / Trafik-Proxy avec le proxy inversé Trafik qui vous permet d'accueillir plusieurs applications à l'intérieur de conteneurs Docker où chaque conteneur exposent différents ports de port et Trafik Maps vers des sous-domaines. Pour plus de détails, comment configurer ce fichier README.md et tutoriel lié. Vous avez juste besoin d'exécuter votre conteneur d'applications et Trafik le ramassera automatiquement sans que vous redémarrez manuellement le conteneur de Trafik.
En plus de Trafik, il dispose également portainer Container pour gérer les conteneurs, adminer Container pour administrer la base de données de production, uptime-kuma pour suivre la disponibilité du site Web et un autre conteneur postgres configuré pour accepter les connexions des hôtes distants (utile pour créer des applications dans les actions GitHub).
Les ci-dessous sont répertoriés toutes les variables d'environnements que vous devez définir. Par souci de simplicité, je vous ai montré ici comment les définir dans le fichier .env local, le fichier docker-compose.yml le lira et transmettra toutes les variables nécessaires dans les conteneurs. C'est OK pour les applications de démonstration, mais pour les applications de production réelles, une bonne façon de le faire est de les définir dans le tableau de bord de votre fournisseur de cloud ou d'utiliser un coffre-fort dédié.
# 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-boilerplateCe sont toutes les variables nécessaires.
MY_UIDetMY_GIDsont des ID de votre utilisateur et groupe actuels sur votre serveur Linux. Vous pouvez voir leurs valeurs en exécutantid -uetid -gdans le terminal de votre serveur. Le meilleur endroit pour les définir est mondialement dans~/.bashrccar ils peuvent être nécessaires pour plusieurs conteneurs. Ils sont transmis dans le conteneur Postgres afin que les fichiers de données de volume soient créés avec des autorisations et une propriété correctes (en tant qu'utilisateur actuel et non utilisateur racine).
# 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= Pour éviter le travail manuel, il existe déjà un flux de travail GitHub Actions dans .github/workflows/deploy.yml qui supprimera l'ancienne image et extrait et exécutera la dernière image à partir de Dockerhub à l'aide de l'action SSH. Tout ce que vous avez à faire est de le déclencher manuellement ou de le chaîner sur la construction existante et de pousser le flux de travail.
# .github/workflows/deploy.yml
# trigger redeploy with build workflow
on :
workflow_run :
workflows : ['docker build'] Il existe une documentation approfondie pour ce projet dans le dossier DOCS. Vous pouvez trouver tous les aspects techniques soigneusement documentés, particulièrement importants et difficiles. Vous pouvez y trouver des descriptions de problèmes, des solutions, des extraits de code et des références liées connexes.
Actuellement, la documentation est nue dans un sens qu'elle ne contient que des informations techniques nues comment résoudre quelque chose et qu'elle n'est pas complète dans des articles amicaux humains avec un contexte supplémentaire.
Voici le bref aperçu de ce que vous pouvez y trouver:
next-connect Docs et d'exemples officiels.mkcert et détails clés sur Google et Facebook Connectsv4 , composants et crochets de test, hydratation, principalement à partir du docs et du blog TKDODOnext-themes , thèmes comme implémentation de plugin de vent arrière personnalisé à partir de Daisyuiv4elephantsql.com Configuration à des fins de démonstrationgetServerSideProps , Gestion des erreurs avec des Boundaries Error et React Query, TypeScript strict et strictNullChecks OPTIONSts-jest , tests asynchrones avec requête React, formulaires de test, classe Blob moqueuse dans JSDom pour les images, utilisation de la migration v14 , suspense et erreurs dans les tests, MSW, Mocking PRISMA dans les tests unitaires, en utilisant des tests de test de test, des tests de docker à la datibase de test multiples, des tests de la datibase multi-projets, des tests multip projets, des tests jest-preview Configuration, configuration de la couverture du codedocker-compose.yml , configuration de conteneur de production en direct, image de cyprès personnaliséeNODE_ENV et APP_ENV , déploiement VPS à l'aide de l'action SSHgitpod.io , repl.it , codesandbox.io et stackblitz.com , dans le dossier envs et notes/envsLes contributions sont les bienvenues. Vous pouvez trouver plus d'informations sur la contribution à la contribution.
Image Next.js pour les images hébergées localementoutput: 'standalone' dans next.config.jsprisma des dépendances de la production avec un conteneur séparé pour les migrations sans rendre le flux de travail trop compliquécypress: 10.x et next-connect: 1.x (ils ont des changements de rupture)Il y a beaucoup de discussions, de théorie, d'opinions et de buzz autour des frameworks JavaScript ... Mais ce qui nousttons à parler, choisissons le cadre le plus populaire, lisez ce qu'ils suggèrent dans la documentation et essayons-le dans la pratique, vérifiez comment cela fonctionne et voyons si nous pouvons construire quelque chose d'utile et de significatif avec.
Nemanjam, Linkedin
Les liens de références complets sont joints dans les fichiers DOCS. Les références les plus importantes sont:
next-connect , exemple de l'application hoangvvo / nextjs-mongodb-appCe projet utilise la licence MIT: licence
