nextjs prisma boilerplate
1.0.0
Ini adalah boilerplate tumpukan penuh yang dibangun di sekitar tumpukan berikutnya.js terbaru. Ini terdiri dari praktik terbaik yang dijelaskan dalam dokumen resmi yang dikombinasikan dengan keputusan saya yang berasal dari pengalaman dan pengetahuan saya sendiri yang telah saya kumpulkan dari bekerja dengan orang lain.
Jangan menghabiskan 3 bulan ke depan membuat keputusan arsitektur, memilih perpustakaan, menyiapkan lingkungan dev dan prod dan pipa CI/CD, menulis kode boilerplate, alih -alih instal boilerplate ini dalam 15 menit dan mulailah mengerjakan fitur Anda hari ini .
Jika aplikasi dirusak cukup gunakan tautan
Reseeddi sisi kanan footer untuk membangkitkan kembali database.
Anda memerlukan akun gitpod, dan mungkin URL basis data Postgres jika database demo saya dirusak. Anda dapat membuatnya di gajah elephantql.com, lihat bagian Gitpod Environment untuk detailnya.
next-auth , dll ...) 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 dan Facebook, Google dan penyedia kredensial.env* ...pages struktur komponen yang dapat diskalakan dan dipisahkan -> layouts -> views -> components!important dalam seluruh kode)next-connect dengan middleware untuk validasi dan rute yang dilindungigetServerSideProps dengan kelas kesalahan khusustesting-library/react for Unit and Integration Testsjest-preview Visual Debugging, Gambar Diejek dengan Blob Polyfill, Pisahkan .env.test* FileTanpa penyesuaian khusus, ada ruang untuk perbaikan lebih lanjut.
Proyek ini memiliki 3 lingkungan pengembangan yang tersedia:
Anda dapat memilih lingkungan apa pun yang Anda sukai.
Mana yang harus dipilih? Jika Anda suka pendekatan konvensional, pilih lokal, jika Anda bekerja di tim dan ingin memiliki lingkungan yang konsisten dengan kolega untuk dengan mudah mereproduksi bug dan dengan cepat naik anggota baru memilih Docker, dan jika Anda ingin membuat Sandbox mereproduksi bug dan meminta bantuan untuk memilih GitPod secara publik.
Klon Repositori dan instal dependensi.
# clone repository
git clone [email protected]:nemanjam/nextjs-prisma-boilerplate.git
cd nextjs-prisma-boilerplate
# install dependencies
yarn installKetika Anda membuka folder proyek untuk pertama kalinya VS Code akan meminta Anda untuk menginstal ekstensi yang disarankan, Anda harus menerima semuanya, mereka diperlukan untuk menyorot, melengkapi secara otomatis, kode serat dan format, menjalankan tes, mengelola kontainer.
Isi variabel lingkungan publik yang diperlukan di .env.development . Cara tercepat adalah menjalankan aplikasi dengan server http .
Anda memerlukan
httpssecara lokal hanya untuk login facebook oauth. Untuk itu Anda memerlukanmkcertuntuk menginstal sertifikat untuklocalhost, instruksi untuk itu yang dapat Anda temukan di folderdocs.
Tinggalkan PORT sebagai 3001, hardcoded di banyak tempat, jika Anda ingin mengubahnya, Anda harus mengedit semuanya (yaitu semua Dockerfile.* Dan 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} Buat file .env.development.local .
# create local file form example file
cp .env.development.local.example .env.development.local
Di semua lingkungan Postgres Container dikonfigurasi untuk dijalankan sebagai pengguna non-root saat ini pada mesin host Linux. Ini penting agar file database dalam volume dibuat dengan kepemilikan dan izin yang benar. Untuk ini Anda perlu mendefinisikan MY_UID dan MY_GID . Tempat terbaik untuk mengaturnya adalah di ~/.bashrc .
# ~/.bashrc
export MY_UID= $( id -u )
export MY_GID= $( id -g )Isi variabel lingkungan pribadi yang diperlukan. Satu -satunya variabel yang diperlukan adalah untuk koneksi basis data postgres dan rahasia JWT.
Kredensial Facebook dan Google adalah opsional dan hanya digunakan untuk login OAuth. Login Facebook membutuhkan
httpsuntuk pengalihan URL. Anda dapat menetapkan nilai apa pun untukPOSTGRES_USER,POSTGRES_PASSWORDdanPOSTGRES_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= Setelah semua variabel diatur, Anda dapat menjalankan basis data Postgres di dalam wadah Docker, jalankan migrasi prisma yang akan membuat tabel SQL dari schema.prisma dan database benih dengan data.
# 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 Pada titik ini semuanya sudah siap, Anda sekarang dapat memulai aplikasi. Buka http://localhost:3001 di browser untuk melihat aplikasi yang sedang berjalan.
# start the app in dev mode
yarn devSetelah Anda mengkloning wadah aplikasi Repository Build.
# terminal on host
yarn docker:dev:build Lingkungan Docker akan membaca variabel dari folder envs/development-docker . Buat file Env lokal dari file contoh. Ini sudah memiliki semua variabel yang dikonfigurasi.
# terminal on host
cp envs/development-docker/.env.development.docker.local.example envs/development-docker/.env.development.docker.local Jalankan wadah aplikasi, database, dan admin. Itu saja. Folder Proyek Dipasang ke /app Folder Di Dalam Kontainer, Anda dapat mengedit sumber secara langsung di host atau membuka tab Ekstensi Wadah Jarak Jauh dan klik kanan npb-app-dev dan pilih Attach to Container dan Buka /app di instance Remote vs Code. Buka http://localhost:3001 di browser di host untuk melihat aplikasi yang sedang berjalan.
# terminal on host
yarn docker:dev:up Buka terminal baru di dalam wadah dan benih database, docker-compose.dev.yml sudah melewati file env yang benar.
# terminal inside the container
yarn prisma:seedCatatan: Git sudah ada dalam wadah dengan akun Anda sehingga Anda dapat melakukan dan mendorong perubahan langsung dari kontainer.
# check that git config is already set inside the container
git config --list --show-originSaya sarankan Anda menginstal wadah Edisi Komunitas Portainer secara lokal untuk lebih mudah mengelola dan men -debug wadah, alat ini gratis dan sangat berguna.
Pergi ke elephantql.com Buat akun gratis dan buat database 20MB Postgres gratis. Pergi ke gitpod.io, login dengan github. Buka repositori bercabang Anda di gitpod dengan membuka tautan berikut (ganti your-username dengan yang asli):
https://gitpod.io/#https://github.com/your-username/nextjs-prisma-boilerplate
Lingkungan GitPod akan membaca variabel dari folder envs/development-gitpod . Buat file Env lokal dari file contoh.
# terminal on Gitpod
cp envs/development-gitpod/.env.development.gitpod.local.example envs/development-gitpod/.env.development.gitpod.local Dalam file lokal itu, atur URL basis data dari elephantsql.com . Variabel lain diatur secara otomatis.
# envs/development-gitpod/.env.development.gitpod.local
DATABASE_URL=postgres://something:[email protected]/somethingSekarang bermigrasi dan benih database.
Catatan: Database
elephantsql.comtidak memiliki semua hak istimewa sehingga Anda harus menggunakan perintahprisma pushalih -alihprisma migrate devbiasa. Baca detail lebih lanjut tentang database bayangan di dokumen/demo-environments.md.
# terminal on Gitpod
# migrate db
yarn gitpod:push:env
# seed db
yarn gitpod:seed:envSemuanya diatur, Anda sekarang dapat menjalankan aplikasi dalam mode dev dan membukanya di tab Browser Baru.
yarn gitpod:dev:envProyek ini memiliki 4 konfigurasi pengujian terpisah plus konfigurasi cakupan kode. Semua tes dapat berjalan secara lokal, di Docker dan dalam tindakan GitHub.
Catatan: Anda juga dapat menjalankan dan men-debug semua tes Jest dengan ekstensi
orta.vscode-jestyang sudah termasuk dalam daftar yang disarankan.
Berjalan secara lokal.
yarn test:clientBerlari di Docker.
yarn docker:test:clientBerjalan secara lokal.
yarn test:server:unitBerlari di Docker.
yarn docker:test:server:unitPastikan bahwa database pengujian naik dan bermigrasi. Anda tidak perlu menyemai itu.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envBerjalan secara lokal.
yarn test:server:integrationBerlari di Docker.
yarn docker:test:server:integrationAnda perlu menjalankan database tes, sama seperti pada langkah sebelumnya.
Berjalan secara lokal.
yarn test:coverageBerlari di Docker.
yarn docker:test:coverageBerlari secara lokal:
Anda perlu menjalankan dan memigrasi basis data uji (tidak perlu benih), membangun aplikasi untuk produksi, menjalankan aplikasi dan menjalankan cypress.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envMaka Anda perlu membangun aplikasi untuk produksi.
# build the app for prod
yarn buildMaka Anda perlu memulai aplikasi dan Cypress pada saat yang sama. Ini akan membuka Cypress GUI.
# starts the app and Cypress GUI
yarn test:e2e:envAnda juga dapat menjalankan Cypress dalam mode tanpa kepala (tanpa GUI).
# starts the app and Cypress in headless mode
yarn test:e2e:headless:envBerlari di Docker:
Bangun Aplikasi dan Gambar Cypress.
# build testing app image
yarn docker:npb-app-test:build
# build Cypress container
yarn docker:npb-e2e:buildKemudian Anda dapat menjalankan database uji, wadah uji aplikasi dan wadah Cypress (dalam mode headless) sekaligus.
# run db, app and Cypress headless
yarn docker:npb-e2e:upSaya membuat repositori terpisah nemanjam/traefik-proxy hanya untuk penyebaran dengan proxy terbalik traefik yang hanya membutuhkan variabel lingkungan dan gambar dari Dockerhub. Ada juga alur kerja tindakan GitHub untuk membangun, mendorong, dan memulihkan gambar terbaru di server Anda. Anda harus menggunakannya untuk penempatan.
Demi kelengkapan yang saya jelaskan di sini cara membangun dan menjalankan aplikasi produksi secara lokal dan di Docker. Keduanya dapat berguna sebagai lingkungan pementasan untuk pengujian. Saya juga menggambarkan cara membangun dan mendorong gambar langsung ke Dockerhub dari mesin pengembangan lokal Anda.
Saat membangun dan menjalankan aplikasi dalam mode produksi, ia akan membaca variabel dari .env.production dan .env.production.local . Pada waktu pembangunan satu -satunya variabel yang diperlukan adalah NEXTAUTH_URL (digunakan untuk url dasar dalam komponen CustomHead yang bertanggung jawab untuk SEO). Jika Anda menggunakan getStaticProps (pembuatan situs statis), Anda juga perlu meneruskan DATABASE_URL dengan data yang benar. Saat runtime Anda perlu mendefinisikan semua variabel publik dan pribadi dalam dua file ini.
Untuk membangun dan menjalankan aplikasi produksi jalankan dua perintah ini.
# build app
yarn build
# start app
yarn start Saat membangun aplikasi produksi di dalam gambar Docker lagi, Anda perlu melewati variabel yang sama seperti secara lokal ( NEXTAUTH_URL dan DATABASE_URL untuk SSG), kali ini diteruskan dengan ARG_NEXTAUTH_URL dan ARG_DATABASE_URL di Dockerfile.prod . Variabel lingkungan waktu ini dibaca dari envs/production-docker/.env.production.docker dan envs/production-docker/.env.production.docker.local . Saat runtime Anda perlu mendefinisikan semua variabel publik dan pribadi dalam dua file ini.
Untuk membangun dan menjalankan gambar produksi Docker, jalankan ini.
# build production image
yarn docker:prod:build:env
# run production image
yarn docker:prod:up Sekali lagi Anda perlu mengatur NEXTAUTH_URL dan DATABASE_URL (untuk ssg) kali ini di envs/production-live/.env.production.live.build.local . Buat file ini dari file contoh.
cp envs/production-live/.env.production.live.build.local.example envs/production-live/.env.production.live.build.localAnda perlu mengedit skrip benang ini dan mengatur nama pengguna Dockerhub dan nama gambar Anda yang sebenarnya.
# 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} .' " ,
Anda sekarang dapat membangun, menandai, dan mendorong ke Dockerhub gambar produksi Anda. Untuk mendorong gambar, Anda harus terlebih dahulu login di terminal dengan docker login .
# build and tag production image
yarn docker:live:build
# push image to Dockerhub
yarn docker:live:push Sudah ada alur kerja yang diatur untuk membangun dan mendorong citra produksi dalam tindakan GitHub di .github/workflows/build-docker-image.yml . Di pengaturan repositori Anda, Anda hanya perlu mengatur variabel -variabel ini dan menjalankan alur kerja.
# 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 Anda hanya perlu mengatur nama gambar Anda di dalam docker-compose.live.yml , berikan semua variabel lingkungan ke sana dan sebarkan dengan docker-compose up -d di server Anda.
# docker-compose.live.yml
services :
npb-app-live :
container_name : npb-app-live
image : your-dockerhub-username/your-image-name:latest Untuk tujuan ini saya sudah membuat repositori terpisah Nemanjam/Traefik-Proxy dengan Traefik Reverse Proxy yang memungkinkan Anda untuk meng-host beberapa aplikasi di dalam wadah Docker di mana setiap wadah mengekspos port port dan port traefik yang berbeda ke subdomain. Untuk detail cara mengkonfigurasi ini lihat file README.md dan tutorial tertaut di dalamnya. Anda hanya perlu menjalankan wadah aplikasi Anda dan Traefik akan secara otomatis mengambilnya tanpa Anda perlu memulai kembali wadah Traefik secara manual.
Selain traefik, ia juga sudah memiliki wadah portainer untuk mengelola wadah, adminer wadah untuk mengelola basis data produksi, uptime-kuma untuk melacak uptime situs web, dan wadah postgres lain yang dikonfigurasi untuk menerima koneksi dari host jarak jauh (berguna untuk aplikasi membangun dalam tindakan github).
Bellow terdaftar semua variabel lingkungan yang perlu Anda tetapkan. Demi kesederhanaan, saya menunjukkan kepada Anda di sini cara mengaturnya dalam file .env lokal, file docker-compose.yml akan membacanya dan meneruskan semua variabel yang diperlukan ke dalam wadah. Ini tidak masalah untuk aplikasi demo tetapi untuk aplikasi produksi nyata cara yang tepat untuk melakukan ini adalah dengan mengaturnya di dasbor penyedia cloud Anda atau menggunakan beberapa lemari besi khusus.
# 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-boilerplateIni semua adalah variabel yang diperlukan.
MY_UIDdanMY_GIDadalah id dari pengguna dan grup Anda saat ini di server Linux Anda. Anda dapat melihat nilainya dengan menjalankanid -udanid -gdi terminal server Anda. Tempat terbaik untuk mengaturnya adalah secara global di~/.bashrckarena mereka dapat dibutuhkan untuk beberapa wadah. Mereka diteruskan ke wadah Postgres sehingga file data volume dibuat dengan izin dan kepemilikan yang benar (sebagai pengguna saat ini dan bukan pengguna 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= Untuk menghindari pekerjaan manual, sudah ada alur kerja tindakan gitub di .github/workflows/deploy.yml yang akan menghapus gambar lama dan menarik dan menjalankan gambar terbaru dari Dockerhub menggunakan aksi ssh. Yang perlu Anda lakukan adalah memicu baik secara manual atau rantai pada build yang ada dan mendorong alur kerja.
# .github/workflows/deploy.yml
# trigger redeploy with build workflow
on :
workflow_run :
workflows : ['docker build'] Ada dokumentasi yang luas untuk proyek ini di folder Docs. Anda dapat menemukan semua aspek teknis yang didokumentasikan dengan cermat, terutama bagian -bagian penting dan sulit. Di sana Anda dapat menemukan deskripsi masalah, solusi, cuplikan kode dan referensi tertaut terkait.
Saat ini dokumentasi telanjang dalam arti bahwa ia hanya memiliki informasi teknis yang telanjang bagaimana menyelesaikan sesuatu dan tidak bulat dalam artikel ramah manusia dengan konteks tambahan.
Berikut adalah gambaran singkat tentang apa yang dapat Anda temukan di dalamnya:
next-connect , dan beberapa hal reaksi umum yang umummkcert dan detail utama tentang Google dan Login Facebookv4 , komponen dan kait pengujian, hidrasi, terutama dari dokumen dan blog tkdodonext-themes , Tema sebagai Implementasi Plugin Tailwind Kustom dari Daisyuiv4 Migration Guideelephantsql.com gratis untuk tujuan demo untuk tujuan demostrict Kesalahan - Penanganan Kesalahan dalam API dan getServerSideProps , Menangani Kesalahan Dengan strictNullChecksts-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, Pengaturan jest-preview , Konfigurasi Cakupan Kodedocker-compose.yml , pengaturan kontainer produksi langsung, gambar cypress khusus kustom cypress custom customNODE_ENV dan Variabel APP_ENV , Penyebaran VPS Menggunakan Aksi SSHgitpod.io , repl.it , codesandbox.io dan stackblitz.com , di folder envs and notes/envs Anda memiliki konfigurasi untuk semua lingkungan ini tetapi hanya gitpod yang memiliki daya komputasi yang cukup untuk benar -benar menjalankannyaKontribusi dipersilakan. Anda dapat menemukan info lebih lanjut cara berkontribusi dalam berkontribusi.
Image berikutnya.js untuk gambar yang di -host secara lokaloutput: 'standalone' di next.config.jsprisma dari dependensi prod dengan wadah terpisah untuk migrasi tanpa membuat alur kerja terlalu rumitcypress: 10.x dan next-connect: 1.x (mereka mengalami perubahan perubahan)Ada banyak pembicaraan, teori, pendapat, dan desas -desus di sekitar kerangka kerja JavaScript ... tetapi mari berhenti berbicara, memilih kerangka kerja paling populer, membaca apa yang mereka sarankan dalam dokumentasi dan mencobanya dalam praktiknya, periksa cara kerjanya dan lihat apakah kita dapat membangun sesuatu yang bermanfaat dan bermakna dengannya.
Nemanjam, LinkedIn
Tautan referensi lengkap dilampirkan dalam file dokumen. Referensi terpenting adalah:
next-connect , contoh aplikasi hoangvvo/nextjs-mongodb-appProyek ini menggunakan lisensi MIT: lisensi
