La siguiente guía explica cómo integrar el SDK web de Realm en un Next.js Aplicación. Puede usar el SDK web de Realm para acceder a datos en MongoDB Atlas desde aplicaciones web, como las creadas con Next.js. El SDK web de Realm interactúa con sus datos en MongoDB Atlas a través de Atlas App Services. Next.js es un framework web basado en React que gestiona la configuración y la estructura de las aplicaciones y admite renderizado estático, del lado del cliente y del servidor.
El Realm Web SDK soporta todos estos modos de renderizado en Next.js:
Representación del lado del cliente: consulte MongoDB directamente desde el navegador utilizando la API Atlas GraphQL o MongoDB Data Access.
Representación del lado del servidor: autentique a los usuarios con App Services desde el navegador y realice consultas mediante la API GraphQL en el servidor
Representación estática: obtiene datos de MondoDB Atlas para generar páginas en el momento de la compilación.
Antes de comenzar
Antes de utilizar esta guía de integración, debes:
Familiarícese con Next.js. Considere consultar la documentación de Next.js.
Crea una aplicación Next.js. Si es la primera vez que creas una aplicación Next.js, consulta el Tutorial de Next.js.
Agrega el SDK web de Realm en tu aplicación de Next.js. Para ver más información, consulta la documentación de instalación de Realm Web.
Tip
Integración de MongoDB Atlas Vercel
Si utiliza Vercel para alojar su aplicación Next.js, agregue la integración MongoDB Atlas para conectar fácilmente su aplicación Next.js a Atlas.
Obtenga más información sobre la integración de Vercel MongoDB Atlas.
Agregar autenticación
Antes de poder consultar MongoDB desde su aplicación, debe inicializar el cliente de App Services y autenticar un usuario. Puede seguir los pasos a continuación para conectar el SDK web de Realm a Next.js del lado del cliente.
En este ejemplo, vamos a exponer un servidor autenticado. Realm.App instancia en toda la aplicación usando Realm.getApp() en un React Hook personalizado.
Tip
Para conocer formas adicionales de exponer la autenticación de Realm en toda su aplicación, consulte la documentación de autenticación de Next.js.
Agrega una variable de entorno ID de la aplicación
Use el ID de la aplicación para conectar la aplicación Next.js a Atlas App Services. Exponga el ID de la aplicación como una variable de entorno en toda la aplicación haciendo lo siguiente:
Crea el archivo
.env.localen el directorio raíz del proyecto.Agregar una variable de entorno para el ID de la aplicación. Para hacer que el ID de la aplicación sea accesible desde el navegador además del servidor, antepón su nombre con
NEXT_PUBLIC_.
NEXT_PUBLIC_APP_ID=<YOUR App Services App ID>
Crea un React Hook para obtener la aplicación
El cliente usa un React Hook para instanciar y acceder a Realm.App, que se usa para conectarse a App Services mediante el ID de la aplicación. Usarás este hook en todas las páginas que crees en esta guía.
Crea el archivo
components/useApp.js.Agregue el siguiente código para crear una instancia y acceder a la instancia
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; }
Iniciar sesión del usuario
Ahora puede acceder a la instancia app con el gancho useApp() y usarlo para iniciar sesión como usuario. Autenticarse de forma anónima en pages/index.js cuando un usuario llega a la página de inicio de la aplicación.
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 ); }
En una aplicación real, sería conveniente contar con un flujo de autenticación más complejo. Para más información, consulte la documentación de autenticación de Next.js.
Renderizado del lado del cliente
Esta sección muestra cómo puedes integrar la renderización lado del cliente de Next.js con el Realm Web SDK. Siguiendo estos pasos, puedes directamente query MongoDB y tener una interacción con un backend sin servidor de Atlas App Services mediante JavaScript del lado del cliente en tu aplicación Next.js. Puedes consultar MongoDB usando acceso a los datos de MongoDB o la API de Atlas GraphQL.
Acceso a datos de MongoDB
Una vez que se inicializa el cliente App y se autentica un usuario, puede usar MongoDB Data Access para consultar MongoDB directamente desde el código del cliente en su aplicación.
Acceda a la interfaz de acceso a datos de MongoDB desde el app objeto con App.User.mongoClient() y luego úsela para consultar 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" />; }
API de Atlas GraphQL
Alternativamente, puede utilizar la API Atlas GraphQL para consultar MongoDB a través de GraphQL desde el código del lado del cliente Next.js.
Este ejemplo utiliza el cliente Apollo GraphQL para ejecutar consultas GraphQL. Instale el cliente Apollo con su paquete npm @apollo/client y su dependencia de pares graphql.
npm install @apollo/client graphql
Ahora puedes agregar una página para realizar consultas GraphQL. El código de la página hace lo siguiente:
Importa las dependencias necesarias
Crea el cliente GraphQL en un componente proveedor.
Define la consulta GraphQL.
Crea un componente que consume el proveedor GraphQL y ejecuta la consulta.
Exporta el componente del proveedor que envuelve al componente consumidor.
En conjunto, la página GraphQL debería verse así:
// 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> ); }
Tip
Para obtener más información sobre cómo consultar Atlas con la API GraphQL con React, consulte la documentación de Apollo Client (React).
Renderizado del lado del servidor
Esta sección muestra cómo integrar la renderización del lado del servidor de Next.js con el SDK web de Realm. Usar el SDK web de Realm con la renderización del lado del servidor le permite acceder a los datos como un usuario específico. Al hacerlo, aplica reglas y permisos de App Services a las consultas de esos usuarios.
Para consultar MongoDB Atlas directamente desde el servidor Next.js, debes configurar dos componentes distintos: la API GraphQL de Atlas en el servidor Next.js y el SDK web de Realm en el navegador. Esta sección explica la configuración de ambos.
Es posible que desee integrar el SDK web y Next.js porque le permite:
Acceda a los datos almacenados en Atlas directamente al cargar la página.
Aplique reglas y permisos de Atlas App Services a las solicitudes para reducir el código del lado del servidor.
Reducir el uso de JavaScript del lado del cliente.
Realizar manipulación de datos del lado del servidor.
En un nivel alto, el proceso para usar el Realm Web SDK con la representación del lado del servidor de Next.js es el siguiente:
En el navegador, crea una instancia de tu cliente de App Services e inicia sesión como usuario. Guarda el token de acceso del usuario como cookie. Este ejemplo usa el paquete nookies, que simplifica la gestión de cookies en una aplicación Next.js.
En el servidor, se analiza la cookie accessToken y se usa para obtener datos de MongoDB usando la API de Atlas GraphQL.
En el servidor, renderiza previamente los datos de MongoDB en tu página web antes de enviarlos al navegador.
Nota
No utilice el acceso a datos de MongoDB con la representación del lado del servidor
Si bien es posible usar MongoDB Data Access en entornos del lado del servidor para consultar MongoDB, generalmente no es recomendable. Sería necesario conservar las credenciales de usuario en el navegador para pasarlas al servidor en cada solicitud, lo cual supone una vulnerabilidad de seguridad. Además, MongoDB Data Access realiza solicitudes desde un objeto de usuario, que debería reinstalarse y autenticarse en cada solicitud.
Los siguientes pasos describen el uso del SDK web de Realm con la representación del lado del servidor de Next.js.
Cree un contenedor de aplicación personalizado para agregar un token de acceso a las cookies
Crea un contenedor de página App personalizado. Crea el archivo pages/_app.js y obtén la instancia Realm.App con el gancho useApp().
Si hay un usuario autenticado, guarde su token de acceso como una cookie. Esto transfiere el token de acceso del navegador al servidor en cada solicitud. Configure su cookie en un gancho useEffect que se ejecute cada vez que se produzca un cambio en el objeto de usuario, como se muestra a continuación. El setInterval también restablece la credencial en las cookies antes de que caduque el token.
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;
Representación de los datos en el lado del servidor
Cree un nuevo archivo de página para realizar la renderización del lado del servidor. En la página, agregue código para realizar lo siguiente:
Importe las dependencias relevantes.
Agregue una función que cree un cliente GraphQL del lado del servidor en cada solicitud con el token de autenticación actual del usuario.
Crea la solicitud GraphQL que el servidor utiliza para obtener datos.
Utilice la función getServerSideProps de Next.js para realizar lo siguiente:
Analizar el token de acceso de las cookies.
Cree un cliente GraphQL con el token de acceso.
Ejecute la consulta GraphQL.
Devuelve datos que se utilizarán en la representación del lado del servidor.
Exportar el componente de página para representar los datos.
En conjunto, la página de renderizado del lado del servidor se ve de la siguiente manera:
// 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> ); }
Representación estática
Puede utilizar la representación estática de Next.js con Realm Web SDK para extraer datos de MondoDB Atlas y generar HTML de página en el momento de la compilación.
Es posible que desee utilizar el SDK web de Realm con representación estática para los siguientes casos de uso:
Extraer datos del sistema de gestión de contenido
Agregar información de configuración
Crear contenido internacionalizado
Creando y protegiendo su clave API
Necesita crear una clave API de servidor para la autenticación. Siga los pasos de la página Configuración de la clave API para completar este paso. Luego, en su aplicación Next.js, agregue la clave API a su .env.local archivo. La variable almacenada no es accesible desde el navegador, siempre que no le agregue el PUBLIC_NEXT_ prefijo.
REALM_API_KEY=secret_api_key
Ahora puedes acceder a la variable en tu aplicación, excepto en la representación del lado del cliente.
const { REALM_API_KEY } = process.env;
Realizar representación estática getStaticProps() con.
Puede utilizar la función getStaticProps() de Next.js para consultar MongoDB durante la generación estática.
Para pre-renderizar tu página usando getStaticProps(), conecta tu aplicación Next.js al SDK web de Realm. Luego, puedes usar getStaticProps() para obtener datos de MongoDB. El siguiente ejemplo muestra cómo consultar MongoDB con renderizado estático.
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> ); }
Formas alternativas de query MongoDB desde siguiente.js
Además del SDK de Realm Web, puedes consultar MongoDB desde Next.js de varias maneras:
Integre MongoDB con su aplicación Next.js y luego ejecute sus consultas de MongoDB usando el controlador de nodo de MongoDB. Para más información, consulte la entrada del blog "Cómo integrar MongoDB en su aplicación Next.js". El uso de controladores de MongoDB no es compatible con las reglas y permisos basados en el usuario de App Services.
Utiliza la API de datos de MongoDB para query MongoDB Atlas desde el servidor de Next.js. Para más información, consulta Data API Endpoints.