nextjs prisma boilerplate
1.0.0
Это полный стек, построенный вокруг последнего стека Next.js. Он состоит из лучших практик, описанных в официальных документах, в сочетании с моими решениями, полученными из моего собственного опыта и знаний, которые я собрал из работы с другими людьми.
Не тратьте в следующие 3 месяца на принятие архитектурных решений, выбирая библиотеки, настройку среда Dev и Prod и CI/CD трубопроводы, написание кода в шаблоне, вместо этого установите этот шаблон за 15 минут и начинайте работать над своими функциями сегодня .
Если приложение вандализировано, просто используйте
ReseedLink в правой стороне нижнего колонтитула для повторной базы данных.
Вам нужна учетная запись 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, React Hook Form 8-alpha , React Dropzone, Zod, MSW, Tailwindcs 3 , Jest 28 , Testing Bibrail React, Cypress 9.6.1 .
next-auth и Facebook, Google и поставщиками учетных данных.env* файлы ...pages структуры компонентов -> layouts -> views -> components!importantnext-connect с промежуточным программным обеспечением для проверки и защищенных маршрутовgetServerSideProps с пользовательским классом ошибокtesting-library/react для единичных и интеграционных тестовjest-preview .env.test*Без каких -либо специальных корректировок есть место для дальнейшего улучшения.
Этот проект имеет 3 доступных среде разработки:
Вы можете выбрать любую среду, которую вы предпочитаете.
Какой выбрать? Если вам нравится обычный подход, выбирайте Local, если вы работаете в команде и хотите иметь постоянные среды с коллегами, чтобы легко воспроизводить ошибки и быстро на борту новых участников выбирают Docker, и если вы хотите заставить песочницу воспроизвести ошибку и попросить помощи публично выбрать Gitpod.
Репозиторий клона и установить зависимости.
# clone repository
git clone [email protected]:nemanjam/nextjs-prisma-boilerplate.git
cd nextjs-prisma-boilerplate
# install dependencies
yarn installКогда вы открываете папку проекта в первый раз против кода, попросят вас установить рекомендуемые расширения, вы должны принять их все, они необходимы для выделения, автозаполнения, кода Lint и формата, запуска тестов, управления контейнерами.
Заполните необходимые переменные общественной среды в .env.development . Самый быстрый способ запустить приложение с http -сервером.
Вам нужны
httpsлокально только для Facebook OAuth Login. Для этого вам нужен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} Create .env.development.local файл.
# create local file form example file
cp .env.development.local.example .env.development.local
Во всех средах Postgres Container настраивается для запуска в качестве текущего пользователя, не являющегося корректом, на хост-машине Linux. Это важно, чтобы файлы базы данных в объемах создавались с правильным владением и разрешениями. Для этого вам нужно определить MY_UID и MY_GID . Лучшее место для их установки - в ~/.bashrc .
# ~/.bashrc
export MY_UID= $( id -u )
export MY_GID= $( id -g )Заполните необходимые переменные частной среды. Единственные требуемые переменные для подключения базы данных Postgres и секрета JWT.
Учетные данные 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 и базы данных SED с данными.
# 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 Environment будет считывать переменные из envs/development-docker Polder. Создайте локальный файл 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 и папку Open /app в экземпляре кода удаленного VS. Откройте 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 Создайте бесплатную учетную запись и создайте бесплатную базу данных Postgres 20 МБ. Перейдите на 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 pushCommand, а не обычнуюprisma migrate dev. Прочитайте больше информации о базе данных Shadow в Docs/Demo-Environments.md.
# terminal on Gitpod
# migrate db
yarn gitpod:push:env
# seed db
yarn gitpod:seed:envВсе настроено, теперь вы можете запустить приложение в режиме Dev и открыть его на вкладке «Новый браузер».
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Тогда вам нужно запустить как приложение, так и Cypress одновременно. Это откроет кипарисовый графический интерфейс.
# starts the app and Cypress GUI
yarn test:e2e:envВы также можете запустить Cypress в режиме без головы (без графического интерфейса).
# 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Затем вы можете запустить тестовую базу данных, тестировать контейнер приложений и контейнер Cypress (в режиме без головы) одновременно.
# run db, app and Cypress headless
yarn docker:npb-e2e:upЯ сделал отдельный репозиторий Nemanjam/Traefik-Proxy только для развертывания с помощью Traefik Reverse Proxy, который требует только переменных среды и изображения от Dockerhub. Существуют также рабочие процессы GitHub для создания, толчка и повторного развертывания последнего изображения на вашем сервере. Вы должны использовать это для развертывания.
Для полноты я описал здесь, как создавать и запустить производственное приложение на локальном и в Docker. Эти два могут быть полезны в качестве стационарных сред для тестирования. Я также описал, как построить и подтолкнуть живое изображение в Dockerhub из вашей местной машины разработки.
При создании и запуске приложения в режиме производства он будет считывать переменные из .env.production и .env.production.local . Во время сборки единственной требуемой переменной является NEXTAUTH_URL (она используется для базового URL в CustomHead Component, ответственный за SEO). Если вы используете 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 свое производственное изображение. Чтобы нажать изображение, вы должны сначала войти в терминал с 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, где каждый контейнер подвергает различные порты порта и карты Traefik для субдоменов. Подробнее о том, как настроить этот файл 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, так что файлы данных тома создаются с правильными разрешениями и владением (как текущий пользователь, а не root user).
# 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'] Существует обширная документация для этого проекта в папке Docs. Вы можете найти все технические аспекты, тщательно документированные, особенно важные и сложные детали. Там вы можете найти описания проблем, решения, фрагменты кода и связанные связанные ссылки.
В настоящее время документация обнажена в том смысле, что в ней содержится только техническая информация о том, как что -то решить, и она не окружена в дружественных к человеческим статьям с дополнительным контекстом.
Вот краткий обзор того, что вы можете найти в нем:
next-connect и некоторые общие материалы Reactmkcert и ключевыми подробностями о входах в Google и Facebookv4 , компоненты тестирования и крючки, гидратация, в основном из документов и блога Tkdodonext-themes , темы как пользовательская реализация плагина Taillide от Daisyuiv4elephantsql.com для демонстрацииgetServerSideProps , обработка ошибок с помощью ошибок и реагировать на запросы, TypeScript strict и 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, Настройка jest-preview , конфигурация покрытия кодаdocker-compose.yml , настройка контейнера в прямом эфире, настраиваемое изображение CypressNODE_ENV и APP_ENV , развертывание VPS с использованием действия SSHgitpod.io , repl.it , codesandbox.io и stackblitz.com , в папке envs и notes/envs которые у вас есть конфигурация для всех этих сред, но только GitPod обладает достаточной вычислительной мощностью, чтобы на самом деле ее запуститьВзносы приветствуются. Вы можете найти больше информации, как внести свой вклад в участие.
Image hears.js для локально размещенных изображенийoutput: 'standalone' опция сборки в next.config.jsprisma из зависимостей Prod с отдельным контейнером для миграций, не усложняя рабочий процессcypress: 10.x и next-connect: 1.x (у них есть нарушающие изменения)Есть много разговоров, теории, мнений и шума вокруг фреймворков JavaScript ... но давайте прекратим говорить, выберем самую популярную структуру, прочитаем то, что они предлагают в документации, и попробуем на практике, проверим, как это работает, и посмотрим, сможем ли мы создать что -то полезное и значимое с ним.
Неманджам, LinkedIn
Полные ссылки ссылки прилагаются в файлы DOCS. Наиболее важные ссылки:
next-connect , пример приложения Hoangvvo/nextjs-mongodb-appВ этом проекте используется лицензия MIT: лицензия
