Docs Menu
Docs Home
/ /
Web SDK

Guía de integración de Next.js - SDK web

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 utilizar esta guía de integración, debes:

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.

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.

1

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:

  1. Encuentra el ID de tu aplicación.

  2. Crea el archivo .env.local en el directorio raíz del proyecto.

  3. 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_.

.env.local
NEXT_PUBLIC_APP_ID=<YOUR App Services App ID>
2

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.

  1. Crea el archivo components/useApp.js.

  2. Agregue el siguiente código para crear una instancia y acceder a la instancia App:

components/useApp.js
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;
}
3

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.

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.

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" />;
}

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:

  1. Importa las dependencias necesarias

  2. Crea el cliente GraphQL en un componente proveedor.

  3. Define la consulta GraphQL.

  4. Crea un componente que consume el proveedor GraphQL y ejecuta la consulta.

  5. 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).

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:

  1. 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.

  2. En el servidor, se analiza la cookie accessToken y se usa para obtener datos de MongoDB usando la API de Atlas GraphQL.

  3. 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.

1

Instale los siguientes paquetes npm:

npm install nookies
npm install @apollo/client graphql
2

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;
3

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:

  1. Importe las dependencias relevantes.

  2. 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.

  3. Crea la solicitud GraphQL que el servidor utiliza para obtener datos.

  4. Utilice la función getServerSideProps de Next.js para realizar lo siguiente:

    1. Analizar el token de acceso de las cookies.

    2. Cree un cliente GraphQL con el token de acceso.

    3. Ejecute la consulta GraphQL.

    4. Devuelve datos que se utilizarán en la representación del lado del servidor.

  5. 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>
);
}

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

1

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.

.env.local
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;
2

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>
);
}

Además del SDK de Realm Web, puedes consultar MongoDB desde Next.js de varias maneras:

Volver

Cliente Apollo GraphQL (React)

En esta página