Guia de integração do Next.js - SDK para Web
Nesta página
GraphQL está obsoleto. Saiba mais.
O guia a seguir explica como integrar o Realm Web SDK em um Next.js aplicação. Você pode utilizar o Realm Web SDK para acessar dados no MongoDB Atlas a partir de aplicativos da web, como aqueles criados com Next.js. O Realm Web SDK interface com seus dados no MongoDB Atlas via Atlas App Services. Em seguida.js é uma estrutura da Web baseada no React que lida com a configuração e a estrutura do aplicativo e oferece suporte à renderização estática e do lado do cliente.
O Realm SDK da Web suporta todos estes modos de renderização em Next.js:
Renderização no lado do cliente: Consulte o MongoDB diretamente do navegador usando a API Atlas GraphQL ou o MongoDB Data Access.
Renderização do lado do servidor: autentique usuários com o App Services a partir do navegador e consulte usando a API GraphQL no servidor
Renderização estática: obtém dados do MondoDB Atlas para gerar páginas no tempo de construção.
Antes de começar
Antes de usar este guia de integração, você deve:
Esteja familiarizado com Next.js. Considere consultar a documentação do Next.js.
Crie um aplicativo Next.js. Se estiver a criar um aplicativo Next.js pela primeira vez, considere referir-se ao Tutorial Next.js.
Adicione o Realm SDK da Web em seu aplicativo Next.js. Para obter mais informações, consulte a documentação de Instalação da Web do Realm.
Dica
Integração MongoDB Atlas Vercel
Se você estiver utilizando o Vercel para hospedar seu aplicativo Next.js, adicione a integração do MongoDB Atlas para conectar facilmente seu aplicativo Next.js ao Atlas.
Adicionar autenticação
Antes de consultar o MongoDB a partir do seu aplicativo, você deve inicializar o cliente do App Services e autenticar um usuário. Você pode seguir as etapas abaixo para conectar o Realm SDK da Web ao Next.js do lado do cliente.
Neste exemplo, vamos expor uma instância Realm.App
autenticada em todo o aplicativo usando Realm.getApp() em um React Hook personalizado.
Dica
Veja também:
Para obter maneiras adicionais de expor a autenticação de Realm em todo o aplicativo, consulte a documentação de autenticação .js Avançar.
Adicione uma variável de ambiente do App ID
Utilize o ID do Aplicativo para conectar o aplicativo Next.js ao Atlas App Services. Exponha o ID do aplicativo em todo o aplicativo como uma variável de ambiente fazendo o seguinte:
Crie o arquivo
.env.local
no diretório raiz do projeto.Adicione uma variável de ambiente para o ID do aplicativo. Para tornar o ID do Aplicativo acessível a partir do navegador, além do servidor, prefaça seu nome com
NEXT_PUBLIC_
.
NEXT_PUBLIC_APP_ID=<YOUR App Services App ID>
Crie um React Hook para obter o aplicativo
O cliente usa um React Hook para instanciar e acessar o Realm.App, que você usa para se conectar ao App Services usando o ID do aplicativo. Você usará esse gancho em todas as páginas que criar neste guia.
Crie o arquivo
components/useApp.js
.Adicione o seguinte código para instanciar e acessar a instância do
App
:
import { useEffect, useState } from "react"; import * as Realm from "realm-web"; export function useApp() { const [app, setApp] = useState(null); // Run in useEffect so that App is not created in server-side environment useEffect(() => { setApp(Realm.getApp(process.env.NEXT_PUBLIC_APP_ID)); }, []); return app; }
Faça login do usuário
Agora você pode acessar a instância app
com o gancho useApp()
e utilizá-la para fazer login de um usuário. Autenticar anonimamente no pages/index.js
quando um usuário chega na página inicial do aplicativo.
import { useEffect } from "react"; import * as Realm from "realm-web"; import Link from "next/link"; import { useApp } from "../components/useApp"; export default function Home() { const app = useApp(); // note: useEffect runs in the browser but does not run during server-side rendering useEffect(() => { // If no logged in user, log in if (app && !app.currentUser) { const anonymousUser = Realm.Credentials.anonymous(); app.logIn(anonymousUser); } }, [app, app?.currentUser]); return ( //Your app ); }
Em um aplicativo real, você gostaria de ter um fluxo de autenticação mais complexo. Para mais informações, consulte a documentação de autenticação do Next.js.
Renderização do lado do cliente
Esta seção mostra como você pode integrar a renderização de cliente Next.js com o Realm Web SDK. Seguindo essas etapas, você pode consultar diretamente o MongoDB e interagir com um backend sem servidor do Atlas App Services por meio do JavaScript do lado do cliente em seu aplicativo Next.js. Você pode consultar o MongoDB usando o MongoDB Data Access ou a API Atlas GraphQL.
Acesso aos dados do MongoDB
Após o cliente do App
ser inicializado e um usuário ser autenticado, você poderá utilizar o MongoDB Data Access para consultar o MongoDB diretamente do código do cliente em seu aplicativo.
Acesse a interface de acesso de dados MongoDB a partir do objeto app
com App.User.mongoClient(), e use-o para consultar o MongoDB.
import { useEffect, useState } from "react"; import { useApp } from "../components/useApp"; function MongoDbDataAccess({ name }) { const [plant, setPlant] = useState(); const app = useApp(); useEffect(() => { if (app?.currentUser) { const mongo = app?.currentUser?.mongoClient("mongodb-atlas"); const plants = mongo.db("example").collection("plants"); plants.findOne({ name }).then((foundPlant) => { setPlant(foundPlant); }); } }, [app, app?.currentUser, app?.currentUser?.id, name]); return ( <div> <h1>Data from MongoDB Access</h1> {plant ? ( <div> <p>{plant.name}</p> <p>{plant.color}</p> </div> ) : ( "no plant" )} </div> ); } export default function DaffodilInformation() { return <MongoDbDataAccess name="daffodil" />; }
GraphQL API do Atlas
Como alternativa, você pode usar a API do Atlas GraphQL para consultar o MongoDB via GraphQL a partir do código do lado do cliente Next.js.
Este exemplo usa o cliente Apollo GraphQL para executar queries GraphQL. Instale o cliente Apollo com seu npm pacote @apollo/client e sua dependência GraphQL.
npm install @apollo/client graphql
Agora você pode adicionar uma página para realizar queries do GraphQL. O código na página faz o seguinte:
Importa as dependências necessárias
Cria o cliente GraphQL em um componente do provedor.
Define a query do GraphQL.
Cria um componente que consome o provedor GraphQL e executa a consulta.
Exporta o componente provedor agrupando o componente consumidor.
Ao todo, a página do GraphQL deve ter a seguinte aparência:
// 1. Import dependencies import { ApolloClient, ApolloProvider, HttpLink, InMemoryCache, useQuery, gql, } from "@apollo/client"; import { useApp } from "../components/useApp"; // 2. Add GraphQL client provider function GraphQLProvider({ children }) { const app = useApp(); const client = new ApolloClient({ link: new HttpLink({ uri: process.env.NEXT_PUBLIC_GRAPHQL_API_ENDPOINT, // We get the latest access token on each request fetch: async (uri, options) => { const accessToken = app.currentUser?.accessToken; options.headers.Authorization = `Bearer ${accessToken}`; return fetch(uri, options); }, }), cache: new InMemoryCache(), }); return <ApolloProvider client={client}>{children}</ApolloProvider>; } // 3. GraphQL query const GET_PLANT = gql` query Plant($name: String!) { plant(query: { name: $name }) { _id sunlight name color type _partition } } `; // 4. Consumer of provider and query function PlantInformation({ name }) { const { loading, error, data } = useQuery(GET_PLANT, { variables: { name }, }); if (loading || !data) return <p>Loading ...</p>; if (error) console.error("Failed with error:", error); return ( <div> {data.plant ? ( <div> <p>{data.plant.name}</p> <p>{data.plant.color}</p> </div> ) : ( "no plant" )} </div> ); } // 5. Export page with the GraphQL query export default function FullGraphQLPage() { return ( <GraphQLProvider> <PlantInformation name="daffodil" /> </GraphQLProvider> ); }
Dica
Para obter mais informações sobre como consultar o Atlas com a API GraphQL com React, consulte a documentação do Apollo Client (React).
Renderização do lado do servidor
Esta seção mostra como você pode integrar a renderização de servidor Next.js com o Realm Web SDK. Usar o Realm Web SDK com renderização do lado do servidor permite que você acesse dados como um usuário específico. Ao fazer isso, você aplica as Regras e Permissões doAtlas App Services a essas queries de usuários.
Para consultar o MongoDB Atlas diretamente do servidor Next.js, você deve configurar dois componentes diferentes: Atlas GraphQL API no servidor Next.js e Realm SDK da Web no navegador. Esta seção explica a configuração de ambos.
Você pode querer integrar o SDK da Web e o Next.js porque ele permite que você:
Acesse os dados armazenados no Atlas diretamente no carregamento da página.
Aplique as regras e permissões do Atlas App Services às solicitações para reduzir o código do lado do servidor.
Reduz o uso do JavaScript do lado do cliente.
Executar manipulação de dados do lado do servidor.
Em um nível alto, o processo para usar o Realm SDK da Web com a renderização do lado do servidor Next.js é o seguinte:
No navegador, crie uma instância do seu cliente do App Services e faça login em um usuário. Salve o accessToken do usuário como um cookie. Este exemplo usa o pacote nookies, que simplifica o gerenciamento de cookies em um aplicativo Next.js.
No servidor, analise o cookie accessToken e utilize-o para buscar dados do MongoDB usando a API Atlas GraphQL.
No servidor, pré-renderize os dados do MongoDB em sua página da web antes de enviá-los ao navegador.
Observação
Não use o acesso a dados MongoDB com renderização no lado do servidor
Embora seja possível usar o MongoDB Data Access em ambientes do lado do servidor para consultar o MongoDB, geralmente não é aconselhável. Você precisaria manter as credenciais do usuário no navegador para passar para o servidor em cada solicitação, o que é uma vulnerabilidade de segurança. Além disso, o MongoDB Data Access faz solicitações de um objeto de usuário, que precisaria ser re-instanciado e autenticado novamente em cada solicitação.
As etapas a seguir descrevem o uso do Realm SDK da Web com a renderização do lado do servidor do Next.js.
Crie um wrapper de aplicativo personalizado para adicionar accessToken aos cookies
Crie um wrapper de página App
personalizado. Crie o arquivo pages/_app.js
e obtenha a instância Realm.App
com o gancho useApp()
.
Se houver um usuário atualmente autenticado, salve seu accessToken como um cookie. Isso transfere o accessToken do navegador para o servidor em cada solicitação. Defina seu cookie em um gancho useEffect
que é executado toda vez que há uma alteração no objeto de usuário, como mostrado abaixo. O setInterval
também redefine a credencial em cookies antes que o token expire.
import { useApp } from "../components/useApp"; import { setCookie } from "nookies"; // Import the useEffect hook import { useEffect } from "react"; function MyApp({ Component, pageProps }) { const app = useApp(); // Reset the user access token in cookies on a regular interval useEffect(() => { const user = app?.currentUser; if (user) { setCookie(null, "accessToken", user.accessToken); // Refresh token before session expires const TWENTY_MIN_MS = 1200000; const resetAccessToken = setInterval(async () => { await app?.currentUser?.refreshCustomData(); setCookie(null, "accessToken", user.accessToken); }, TWENTY_MIN_MS); // Clear interval setting access token whenever component unmounts or // there's a change in user. return () => clearInterval(resetAccessToken); } }, [app, app?.currentUser]); return ( <> <Component {...pageProps} app={app} /> </> ); } export default MyApp;
O lado do servidor renderiza os dados
Crie um novo arquivo de página para executar a renderização do lado do servidor. Na página, adicione o código para executar o seguinte:
Importe as dependências relevantes.
Adicione uma função que cria um cliente GraphQL do lado do servidor em cada solicitação com o token de autenticação atual do usuário.
Crie a solicitação do GraphQL que o servidor usa para buscar dados.
Use a função Next.js getServerSideProps para executar o seguinte:
Analise o token de acesso dos cookies.
Crie um cliente GraphQL com o token de acesso.
Execute a query do GraphQL.
Retorne dados a serem usados na renderização do lado do servidor.
Exporte o componente da página para renderizar os dados.
Ao todo, a página de renderização do lado do servidor tem a seguinte aparência:
// 1. import dependencies import nookies from "nookies"; import { ApolloClient, InMemoryCache, HttpLink, gql } from "@apollo/client"; // 2. Function to create GraphQL client const createClient = (token) => new ApolloClient({ link: new HttpLink({ ssrMode: true, uri: process.env.NEXT_PUBLIC_GRAPHQL_API_ENDPOINT, headers: { Authorization: `Bearer ${token}`, }, }), cache: new InMemoryCache(), }); // 3. GraphQL Query used in SSR const GET_PLANT = gql` query Plant($name: String!) { plant(query: { name: $name }) { _id sunlight name color type _partition } } `; // 4. Server-side logic to parse cookie and run query export async function getServerSideProps(context) { const { accessToken } = nookies.get(context); const client = createClient(accessToken); const { data: { plant: lily }, } = await client.query({ query: GET_PLANT, variables: { name: "daffodil" }, }); return { props: { lily }, }; } // Full page exported that gets the data from SSR export default function Ssr({ lily }) { return ( <div> <h1>Data from Server-Side Rendering</h1> {lily ? ( <div> <p>{lily.name}</p> <p>{lily.color}</p> </div> ) : ( "no plant" )} </div> ); }
Renderização estática
Você pode usar a renderização estática Next.js com o Realm SDK da Web para extrair dados do MondoDB Atlas e gerar página HTML no tempo de construção.
Você pode querer usar o Realm SDK da Web com renderização estática para os seguintes casos de uso:
Extraia dados do sistema de gerenciamento de conteúdo
Adicionar informações de configuração
Criar conteúdo internacionalizado
Criando e protegendo sua chave API
Você precisa criar uma chave de API do servidor para autenticação. Siga as etapas na página de configuração da chave API para concluir esta etapa. Em seguida, no aplicativo Next.js, adicione a chave API ao seu arquivo .env.local
. A variável armazenada não é acessível a partir do navegador, desde que você não prefixe-a com PUBLIC_NEXT_
.
REALM_API_KEY=secret_api_key
Agora você pode acessar a variável em seu aplicativo, exceto na renderização do lado do cliente.
const { REALM_API_KEY } = process.env;
Executar renderização estática com getStaticProps()
.
Você pode usar a função Next.js getStaticProps() para consultar MongoDB durante a geração estática.
Para pré-render sua página usando o getStaticProps()
, conecte seu aplicativo Next.js ao SDK da Web do Realm. Então, você pode usar getStaticProps()
para buscar dados do MongoDB. O exemplo a seguir mostra como consultar MongoDB com renderização estática.
import * as Realm from "realm-web"; export async function getStaticProps() { const apiKey = process.env.REALM_API_KEY; const app = new Realm.App({ id: process.env.NEXT_PUBLIC_APP_ID }); // Log in user using realm API key const credentials = Realm.Credentials.apiKey(apiKey); const user = await app.logIn(credentials); // Connect to database const mongo = user.mongoClient("mongodb-atlas"); const plants = mongo.db("example").collection("plants"); // Use plants.findOne to query the database const data = await plants.findOne({ name: "daffodil" }); // You must parse data as JSON to use it as a prop const json = JSON.parse(JSON.stringify(data)); return { props: { plant: json, }, }; } export default function Static({ plant }) { return ( <div> <h1>Data from Static Rendering</h1> <div> <div> <p>{plant.name}</p> <p>{plant.color}</p> </div> </div> </div> ); }
Maneiras alternativas de consultar o MongoDB a partir do Next.js
Além do SDK web do Realm, você pode consultar o MongoDB do Next.js de várias maneiras:
Integre o MongoDB com seu aplicativo Next.js e execute suas queries do MongoDB usando o MongoDB Node Driver. Para obter mais informações, consulte a publicação do blog How to Integration MongoDB Into Your Next.js App. O uso MongoDB de drivers do não é compatível com as Atlas App Services regras e permissões baseadas no .
Use a MongoDB Atlas Data API do Atlas para consultar o MongoDB Atlas a partir do servidor Next.js. Para obter mais informações, consulte Endpoints daAtlas Data API .