nextjs prisma boilerplate
1.0.0
Esta é a placa de caldeira de pilha completa criada em torno da pilha mais recente do próximo.js. É composto pelas melhores práticas descritas em documentos oficiais combinados com minhas decisões derivadas de minha própria experiência e conhecimento que reuni ao trabalhar com outras pessoas.
Não gaste os próximos 3 meses tomando decisões arquitetônicas, escolhendo bibliotecas, configurando ambientes de desenvolvimento e produto e tubos de CI/CD, escrevendo código de caldeira, instale este caldeira em 15 minutos e comece a trabalhar em seus recursos hoje .
Se o aplicativo for vandalizado, basta usar o link
Reseedno lado direito do rodapé para reenviar o banco de dados.
Você precisa da conta GITPOD e talvez URL do banco de dados do PostGres se meu banco de dados de demonstração for vandalizado. Você pode criar um no elephantsql.com, consulte a seção GITPOD Environment para obter detalhes.
next-auth , etc ...) React 18.2.0 , Next.js 12.2.0 , Node.js 16.13.1 , PRISMA 4 , Postgres 14.3 , TypeScript 4.7.4 , consulta react 4-beta , axios, react gancho formulário 8-alpha , reação de reação de reação, 3 de reação, cibernética, 28 9.6.1
next-auth e Facebook, Google e credenciais.env* arquivos ...pages estrutura de componentes escaláveis e desacopladas -> layouts -> views -> components!important em código inteiro)next-connect com middleware para validação e rotas protegidasgetServerSideProps com classe de erro personalizadatesting-library/react para testes de unidade e integraçãojest-preview VISUAL DEBUGGING, imagens zombadas de poli-bLOB, arquivos separados .env.test*Sem nenhum ajuste especial, há espaço para melhorias adicionais.
Este projeto possui 3 ambientes de desenvolvimento disponíveis:
Você pode escolher qualquer ambiente que preferir.
Qual escolher? Se você gosta de abordagem convencional, escolha o local, se você trabalha em uma equipe e deseja ter ambientes consistentes com colegas para reproduzir facilmente bugs e rapidamente a bordo de novos membros escolhem o Docker, e se você deseja fazer a Sandbox reproduzir um bug e pedir ajuda publicamente o gitpod.
Repositório de clone e instale dependências.
# clone repository
git clone [email protected]:nemanjam/nextjs-prisma-boilerplate.git
cd nextjs-prisma-boilerplate
# install dependencies
yarn installQuando você abre a pasta do projeto pela primeira vez, o código solicita que você instale extensões recomendadas, você deve aceitar todas elas, elas são necessárias para destacar, preenchimento automático, cotonete e código de formato, executar testes, gerenciar contêineres.
Preencha as variáveis de ambiente público exigidas em .env.development . A maneira mais rápida é executar o aplicativo com o servidor http .
Você precisa de
httpslocalmente apenas para login do Facebook OAuth. Para isso, você precisamkcertpara instalar certificados paralocalhost, instruções para isso pode encontrar na pastadocs.
Deixe PORT como 3001, ela é codificada em vários lugares, se você quiser alterá-lo, você deve editar todos eles (ou seja docker-compose.*.yml todos os Dockerfile.*
# .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} Criar arquivo .env.development.local .
# create local file form example file
cp .env.development.local.example .env.development.local
Em todos os ambientes, o contêiner Postgres está configurado para ser executado como um usuário não raiz atual em uma máquina de host Linux. Isso é importante para que os arquivos de banco de dados em volumes sejam criados com a propriedade e as permissões corretas. Para isso, você precisa definir MY_UID e MY_GID . O melhor lugar para defini -los é em ~/.bashrc .
# ~/.bashrc
export MY_UID= $( id -u )
export MY_GID= $( id -g )Preencha as variáveis de ambiente privado exigidas. As únicas variáveis necessárias são para a conexão do banco de dados Postgres e o Secret JWT.
As credenciais do Facebook e do Google são opcionais e usadas apenas para login do OAuth. O Login do Facebook requer
httpspara Redirect URL. Você pode definir quaisquer valores paraPOSTGRES_USER,POSTGRES_PASSWORDePOSTGRES_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= Depois que todas as variáveis são definidas, você pode executar o banco de dados do Postgres dentro do contêiner do docker, executar migrações de prisma que criarão tabelas SQL do schema.prisma e banco de dados de sementes com dados.
# 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 Neste ponto, tudo está pronto, agora você pode iniciar o aplicativo. Abra http://localhost:3001 no navegador para ver o aplicativo em execução.
# start the app in dev mode
yarn devDepois de clonar o contêiner de aplicativos de compilação do repositório.
# terminal on host
yarn docker:dev:build O ambiente do Docker lerá variáveis da pasta envs/development-docker . Crie arquivo Env local do arquivo de exemplo. Já tem todas as variáveis configuradas.
# terminal on host
cp envs/development-docker/.env.development.docker.local.example envs/development-docker/.env.development.docker.local Execute o aplicativo, o banco de dados e os contêineres de administrador. É isso. A pasta do projeto é montada para /app dentro do contêiner, você pode editar a fonte diretamente no host ou abrir a guia Extensão de contêineres remotos e clicar com o botão direito do mouse npb-app-dev e selecione Attach to Container e a pasta aberta /app na instância remota vs de código. Abra http://localhost:3001 no navegador no host para ver o aplicativo em execução.
# terminal on host
yarn docker:dev:up Abra um novo terminal dentro do contêiner e semeia o banco de dados, docker-compose.dev.yml já passa os arquivos Env corretos.
# terminal inside the container
yarn prisma:seedNota: O GIT já existirá no contêiner com sua conta para que você possa se comprometer e pressionar as alterações diretamente do contêiner.
# check that git config is already set inside the container
git config --list --show-originSugiro que você instale o contêiner Portainener Community Edition localmente para facilitar o gerenciamento e a depuração dos contêineres, é uma ferramenta gratuita e muito útil.
Vá para elephantsql.com Crie uma conta gratuita e crie um banco de dados PostGres gratuito de 20 MB. Vá para Gitpod.io, faça o login com o Github. Abra o seu repositório bifurcado em Gitpod, abrindo o link seguinte (substitua your-username pelo real):
https://gitpod.io/#https://github.com/your-username/nextjs-prisma-boilerplate
O ambiente GITPOD lerá variáveis da pasta envs/development-gitpod . Crie arquivo Env local do arquivo de exemplo.
# terminal on Gitpod
cp envs/development-gitpod/.env.development.gitpod.local.example envs/development-gitpod/.env.development.gitpod.local Nesse arquivo local, defina o URL do banco de dados em elephantsql.com . Outras variáveis são definidas automaticamente.
# envs/development-gitpod/.env.development.gitpod.local
DATABASE_URL=postgres://something:[email protected]/somethingAgora migre e semeia o banco de dados.
NOTA: O banco de dados
elephantsql.comnão possui todos os privilégios, então você deve usar o comandoprisma pushem vez deprisma migrate dev. Leia mais detalhes sobre o banco de dados de sombra em documentos/demonstração.md.
# terminal on Gitpod
# migrate db
yarn gitpod:push:env
# seed db
yarn gitpod:seed:envTudo está configurado, agora você pode executar o aplicativo no modo dev e abri -lo na guia Novo navegador.
yarn gitpod:dev:envEste projeto possui 4 configurações de teste separadas e configuração de cobertura de código. Todos os testes podem ser executados localmente, nas ações do Docker e no GitHub.
Nota: Você também pode executar e depurar todos os testes de brincadeira com a extensão
orta.vscode-jestque já está incluída na lista recomendada.
Executando localmente.
yarn test:clientCorrendo em Docker.
yarn docker:test:clientExecutando localmente.
yarn test:server:unitCorrendo em Docker.
yarn docker:test:server:unitCertifique -se de que o banco de dados de teste esteja e migrado. Você não precisa semeá -lo.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envExecutando localmente.
yarn test:server:integrationCorrendo em Docker.
yarn docker:test:server:integrationVocê precisa executar o banco de dados de teste, o mesmo que na etapa anterior.
Executando localmente.
yarn test:coverageCorrendo em Docker.
yarn docker:test:coverageCorrendo localmente:
Você precisa executar e migrar o banco de dados de teste (sem necessidade de semente), criar aplicativo para produção, executar o aplicativo e executar o Cypress.
# run database container
yarn docker:db:test:up
# migrate test database
yarn prisma:migrate:test:envEntão você precisa criar um aplicativo para produção.
# build the app for prod
yarn buildEntão você precisa iniciar o aplicativo e o cipreste ao mesmo tempo. Isso abrirá a GUI do Cypress.
# starts the app and Cypress GUI
yarn test:e2e:envVocê também pode executar o Cypress no modo sem cabeça (sem GUI).
# starts the app and Cypress in headless mode
yarn test:e2e:headless:envCorrendo em Docker:
Crie imagens de aplicativos e ciprestes.
# build testing app image
yarn docker:npb-app-test:build
# build Cypress container
yarn docker:npb-e2e:buildEm seguida, você pode executar o banco de dados de teste, o contêiner de aplicativos de teste e o contêiner CYPRESS (no modo sem cabeça) de uma só vez.
# run db, app and Cypress headless
yarn docker:npb-e2e:upFiz um repositório separado Nemanjam/Traefik-Proxy apenas para implantação com proxy reverso do Traefik, que precisa de apenas variáveis de ambiente e imagem do DockerHub. Também existem fluxos de trabalho de ações do GitHub para criar, impulsionar e reimplementar a imagem mais recente em seu servidor. Você deve usar isso para implantação.
Por uma questão de completude, descrevi aqui como criar e executar o aplicativo de produção localmente e no Docker. Esses dois podem ser úteis como ambientes de estadiamento para teste. Também descrevi como construir e empurrar a imagem ao vivo para o dockerhub da sua máquina de desenvolvimento local.
Ao criar e executar o aplicativo no modo de produção, ele lerá variáveis de .env.production e .env.production.local . No momento da construção, a única variável necessária é NEXTAUTH_URL (é usado para URL base no componente CustomHead responsável pelo SEO). Se você usar getStaticProps (geração estática do site), também precisará passar DATABASE_URL com dados corretos. Em tempo de execução, você precisa definir todas as variáveis públicas e privadas nesses dois arquivos.
Para construir e executar o aplicativo de produção, execute esses dois comandos.
# build app
yarn build
# start app
yarn start Ao criar um aplicativo de produção dentro de uma imagem do Docker novamente, você precisa passar as mesmas variáveis como localmente ( NEXTAUTH_URL e DATABASE_URL para SSG), desta vez estes são encaminhados com ARG_NEXTAUTH_URL e ARG_DATABASE_URL em Dockerfile.prod . As variáveis do ambiente de tempo são lidas em envs/production-docker/.env.production.docker e envs/production-docker/.env.production.docker.local . Em tempo de execução, você precisa definir todas as variáveis públicas e privadas nesses dois arquivos.
Para construir e executar a imagem de produção do Docker, execute isso.
# build production image
yarn docker:prod:build:env
# run production image
yarn docker:prod:up Novamente, você precisa definir NEXTAUTH_URL e DATABASE_URL (para SSG) desta vez em envs/production-live/.env.production.live.build.local . Crie este arquivo a partir do arquivo de exemplo.
cp envs/production-live/.env.production.live.build.local.example envs/production-live/.env.production.live.build.localVocê precisa editar este script de fios e definir seu nome de usuário e nome de imagem do DockerHub real.
# 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} .' " ,
Agora você pode construir, marcar e pressionar para dockerhub sua imagem de produção. Para empurrar a imagem, você deve primeiro fazer login no terminal com docker login .
# build and tag production image
yarn docker:live:build
# push image to Dockerhub
yarn docker:live:push Já existe um fluxo de trabalho configurado para criar e empurrar a imagem de produção em ações do GitHub em .github/workflows/build-docker-image.yml . Nas configurações do seu repositório, você só precisa definir essas variáveis e executar o fluxo de trabalho.
# 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 Você só precisa definir o nome da sua imagem dentro docker-compose.live.yml , transmitir todas as variáveis de ambiente e implantá-lo com docker-compose up -d no seu servidor.
# docker-compose.live.yml
services :
npb-app-live :
container_name : npb-app-live
image : your-dockerhub-username/your-image-name:latest Para esse fim, eu já fiz o repositório separado Nemanjam/Traefik-Proxy com proxy reverso do Traefik, que permite hospedar vários aplicativos dentro dos contêineres do Docker, onde cada contêiner expõe diferentes portas e traefik mapeando portas a subdomínios. Para detalhes, como configurar este arquivo README.md e tutorial vinculado. Você só precisa executar o seu contêiner de aplicativos e o Traefik o buscará automaticamente sem precisar reiniciar manualmente o contêiner do Traefik.
Ao lado do Traefik, ele também já possui contêiner portainer para gerenciar contêineres, contêiner adminer para administrar o banco de dados de produção, uptime-kuma para rastrear o tempo de atividade do site e outro contêiner postgres configurado para aceitar conexões de hosts remotos (úteis para criar aplicativos em ações do github).
ABERTO ESTÃO LISTADOS Todas as variáveis de ambientes que você precisa definir. Por uma questão de simplicidade, mostrei aqui como defini-los no arquivo .env local, o arquivo docker-compose.yml o lerá e encaminhará todas as variáveis necessárias para contêineres. Tudo bem para aplicativos de demonstração, mas para aplicativos de produção reais, a maneira correta de fazer isso é defini -los no painel do seu provedor de nuvem ou usar algum cofre dedicado.
# 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-boilerplateTodas essas são variáveis necessárias.
MY_UIDeMY_GIDsão IDs do seu usuário e grupo atual no seu servidor Linux. Você pode ver os valores deles executandoid -ueid -gno terminal do seu servidor. O melhor lugar para defini -los é globalmente em~/.bashrcporque eles podem ser necessários para vários contêineres. Eles são passados para o contêiner do Postgres, para que os arquivos de dados de volume sejam criados com permissões e propriedade corretas (como usuário atual e não o usuário 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= Para evitar o trabalho manual, já existe o fluxo de trabalho do GitHub em .github/workflows/deploy.yml que removerá a imagem antiga e puxará e executará a imagem mais recente do dockerHub usando a ação SSH. Tudo o que você precisa fazer é desencadeá -lo manualmente ou encadeá -lo na construção existente e empurrar o fluxo de trabalho.
# .github/workflows/deploy.yml
# trigger redeploy with build workflow
on :
workflow_run :
workflows : ['docker build'] Há uma extensa documentação para este projeto na pasta Docs. Você pode encontrar todos os aspectos técnicos cuidadosamente documentados, especialmente partes importantes e difíceis. Lá você pode encontrar descrições de problemas, soluções, trechos de código e referências vinculadas relacionadas.
Atualmente, a documentação está nua, no sentido de que possui apenas informações técnicas nuas de como resolver algo e não é arredondado em artigos amigáveis humanos com contexto adicional.
Aqui está a breve visão geral do que você pode encontrar nele:
next-connect e algumas coisas comuns de reaçãomkcert e detalhes importantes sobre os logins do Google e do Facebookv4 , componentes e ganchos de teste, hidratação, principalmente do Docs e Tkdodo Blognext-themes , temas como implementação de plug -in personalizada do Tailwind do Daisyuiv4elephantsql.com para lidargetServerSideProps , lidando com erros com ErrorBoundies e React Query, TypeScript strict e strictNullChecks Opçõests-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, Configuração jest-preview , configuração de cobertura de códigodocker-compose.yml , configuração de contêiner de produção ao vivo, imagem de cifra personalizadaNODE_ENV e APP_ENV , implantação do VPS usando ação sshgitpod.io , repl.it , codesandbox.io e stackblitz.com , na pasta envs e notes/envs você tem configuração para todos esses ambientes, mas apenas o gitpod tem poder de computação suficiente para executá -loContribuições são bem -vindas. Você pode encontrar mais informações como contribuir para contribuir.
Image Next.js para imagens hospedadas localmenteoutput: 'standalone' Build Option em next.config.jsprisma de dependências de produtos com contêineres separados para migrações sem tornar o fluxo de trabalho muito complicadocypress: 10.x e next-connect: 1.x (eles têm mudanças de quebra)Há muita conversa, teoria, opiniões e zumbidos em torno das estruturas JavaScript ... mas vamos parar de falar, escolher a estrutura mais popular, ler o que elas sugerem na documentação e experimente na prática, verifique como funciona e veja se podemos construir algo útil e significativo com ele.
Nemanjam, LinkedIn
Os links completos de referências são anexados nos arquivos do DOCS. As referências mais importantes são:
next-connect , exemplo app hoangvvo/nextjs-mongodb-appEste projeto usa licença do MIT: licença
