> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# guía marco

> Dónde reside la clave API, cuándo usar @markpdf/react directo y cuándo utilizar el proxy con @markpdf/nextjs.

# Guía marco

## La tecla API en el navegador

`MarkpdfProvider` inicializa un `MarkpdfClient` **en el cliente**, por lo que la clave API que le pasa termina en el paquete JS que se descarga en el navegador. Cualquiera puede abrir las herramientas de desarrollo, ir a la pestaña Red o inspeccionar el paquete y copiarlo.

Esto es aceptable cuando:

* Estás creando un prototipo o construyendo una herramienta interna con acceso controlado.
* Ya tienes una clave de privilegios bajos, con límites de uso ajustados, dedicada únicamente a esa interfaz.
* El "costo" de que alguien use su clave para convertir archivos PDF no es una preocupación real (por ejemplo, herramienta de usuario único, demostración, entorno de prueba).

No es aceptable que una aplicación de producción pública tenga una clave que también proteja la facturación o los límites compartidos.

<Warning>
  No hay forma de "ocultar" la clave en un componente del cliente solo con ofuscación: el navegador necesita el valor real en texto sin formato para enviarlo en el encabezado `x-api-key`. La única mitigación real es no exponerlo: mueva la llamada a API al servidor.
</Warning>

## Patrón recomendado para producción: proxy en tu propio backend

Si su aplicación tiene un backend (Next.js, Express, cualquier marco con rutas del lado del servidor), no inicialice `MarkpdfClient`/`MarkpdfProvider` en el cliente. En cambio:

1. Cargue el archivo en su propio punto final (`/api/convert` o similar).
2. Su servidor llama a markpdf con la clave guardada como una variable de entorno del lado del servidor.
3. Su servidor devuelve el Markdown al cliente.

Si su aplicación está en Next.js, `@markpdf/nextjs` ya implementa este patrón; consulte [Instalación de Next.js](/docs/public/es/sdks/nextjs/installation) y [Guía del marco de trabajo de Next.js](/docs/public/es/sdks/nextjs/framework-guide) (Controladores de rutas y acciones del servidor). El componente de React que carga el archivo aún puede parecerse al de `useConvertFile`, pero apuntando a su propia ruta:

```tsx theme={null}
async function upload(file: File) {
  const form = new FormData();
  form.append("file", file);
  const res = await fetch("/api/convert", { method: "POST", body: form });
  return res.text();
}
```

Con otros marcos (Express, Fastify, etc.), se aplica el mismo principio: implemente su propio punto final con `@markpdf/sdk` en el servidor y consuma ese punto final desde React con `fetch` normal en lugar de `@markpdf/react`.

## Cuándo usar `@markpdf/react` directo

* Aplicaciones sin su propio backend (SPA estáticas servidas desde CDN) donde de todos modos no tienes dónde ocultar las claves.
* Herramientas internas detrás de VPN/SSO donde el público que puede ver la clave ya está autorizado a usarla.
* Prototipos y demostraciones.

## Representación del lado del servidor (SSR) / Componentes del servidor

`MarkpdfProvider` usa `useMemo`, `useContext` y crea el cliente en el momento del renderizado; es un componente del cliente. Compruébalo explícitamente si tu marco lo requiere:

```tsx providers.tsx theme={null}
"use client";

import { MarkpdfProvider } from "@markpdf/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return <MarkpdfProvider apiKey={process.env.NEXT_PUBLIC_MARKPDF_API_KEY!}>{children}</MarkpdfProvider>;
}
```

<Note>
  Si necesita marcar la clave como `NEXT_PUBLIC_*` (o el prefijo público equivalente de su marco) para que `MarkpdfProvider` la reciba, ya ha asumido el compromiso de exponerla al navegador. Revisa el apartado anterior antes de hacerlo en producción.
</Note>