Cómo usar IronPDF con Cursor

Curtis Chau
Curtis Chau
Actualizado: 26 de octubre de 2026

Pregunta a cualquier asistente AI para que escriba el código de IronPDF y producirá algo que parece correcto. A veces lo es. Otras veces llama a un método que nunca ha existido, y te das cuenta durante la compilación en lugar de la revisión. El modelo no está funcionando mal. Está llenando un vacío en lo que sabe con algo que tiene una forma plausible, que es el mismo instinto que lo hace útil y peligroso a partes iguales.

Cursor es un editor de código prioritariamente AI construido sobre VS Code, y su característica más valiosa para el trabajo con bibliotecas no es el cuadro de chat. Es la capacidad de obtener la documentación de una biblioteca desde un enlace y de consolidar las reglas del proyecto en el repositorio, de modo que el editor responda usando APIs de IronPDF reales y siga las convenciones de tu equipo sin tener que mencionarlo dos veces. IronPDF renderiza HTML, CSS y JavaScript a PDF a través de un motor Chromium incrustado. Ninguna herramienta sabe acerca de la otra y no hay integración que instalar. Lo que configuras en su lugar es el contexto, y esa configuración es lo que cubre la primera mitad de esta guía.

Una distinción antes de comenzar, porque dos temas similares se confunden. Esta guía trata sobre el uso de un editor AI para construir software con IronPDF. No se trata del uso de modelos AI para leer o analizar el contenido de archivos PDF, lo que cubre por separado el tutorial de procesamiento de PDF potenciado por AI.

Inicio rápido
NuGetInstalar con NuGet

PM > Install-Package IronPdf

Instale IronPDF ejecutando el comando arriba en la Consola del Administrador de Paquetes NuGet, o busque el paquete en el Administrador de Paquetes NuGet.

Abre un proyecto de C# en Cursor y solicita la documentación de IronPDF en lugar de la memoria del modelo:

Read https://ironpdf.com/llms.txt and the pages it links to.

In this C# project, create Program.cs that renders "<h1>Hello from IronPDF</h1>"
to hello.pdf. Read the license key from the IRONPDF_LICENSE_KEY environment
variable. Use only methods that appear in the linked documentation.
Text

Cursor escribe las pocas líneas que importan: construye un ChromePdfRenderer, llama a RenderHtmlAsPdf sobre el marcado y SaveAs el resultado en el disco. El enlace de documentación en la primera línea es lo que diferencia esto de la misma solicitud escrita en una ventana de chat general, y configurarlo es la primera sección importante a continuación.

Una breve nota de seguridad. Nunca se debe entregar una clave de licencia en línea a un agente con acceso a escritura de archivos y terminal, así que mantenla en una variable de entorno o en un archivo de configuración que esté excluido del control de origen. La guía de claves de licencia cubre las opciones soportadas.



¿Qué está realmente funcionando detrás del cuadro de chat?

Cursor no viene con un solo modelo adjunto. Incluye el suyo propio, y también te permite apuntar el mismo editor a otro de alguien más.

Composer es el modelo agente propio de Cursor. El selector de modelos también ofrece los modelos Grok de SpaceXAI, que Cursor co-desarrolló, y modelos de OpenAI, Anthropic, Google y otros laboratorios. Puedes cambiar entre ellos dentro de una sola sesión. Tab, la finalización en línea de Cursor, termina una línea y predice la siguiente edición. La prueba a continuación utilizó Grok 4.7.

Para el trabajo con PDF, eso tiene una consecuencia práctica que merece ser considerada. La mayor parte de una sesión de documentos es trabajo barato y repetitivo: ajustar un margen, reconstruir, mirar la salida, ajustar de nuevo. Ocasionalmente, una tabla se rompe al cruzar una página por una razón que ningún compilador explicará, y ese es el momento de pasar a un modelo que piense más antes de editar. Espera que el documento cambie también con la elección. El mismo aviso dado a dos modelos devuelve dos diseños que difieren en espaciado y saltos de página mientras aún cumplen con lo que especificaste explícitamente, que es el argumento para fijar el recuento de páginas, el texto de cabecera, y el formato de pie de página en lugar de confiar en un valor predeterminado.

También significa que esta serie se solapa aquí. Ejecuta un modelo de Claude dentro de Cursor y las observaciones en la guía de código de Claude todavía se aplican a su salida, porque el modelo es el mismo incluso cuando la superficie no lo es.

¿Cómo proporcionas a Cursor la documentación de IronPDF para que deje de adivinar?

Cursor solía indexar documentación externa detrás de una mención @Docs. Sus notas de la versión 3.21 registran que la opción Docs "ya había dejado de agregar documentación al contexto del agente" y la eliminaron del menú @. Lo que funciona hoy es un enlace. El agente de Cursor tiene una herramienta web que obtiene una URL nombrada en la solicitud, y IronPDF publica llms.txt, un índice de sus páginas de documentación. En una prueba con la CLI de Cursor, el agente obtuvo ese índice y luego las páginas de encabezados y pies de página a las que enlaza antes de responder. Proporcionar a Cursor la documentación de IronPDF es el paso de configuración de mayor valor en esta guía, porque reemplaza el recuerdo por la recuperación.

El razonamiento vale la pena expresarlo claramente para cualquiera nuevo en esto. Un modelo preguntado sobre una biblioteca específica se basa en lo que absorbió durante el entrenamiento, que puede estar obsoleto y nunca fue verificado contra la versión actual. Un enlace de documentación le da algo que mirar al editor. La diferencia se muestra inmediatamente en los nombres de método: un modelo sin fundamentos inventa renderer.ConvertHtmlToPdfDocument(), y se lee perfectamente bien hasta que el compilador está en desacuerdo.

El enlace va en un aviso como una línea de texto:

Use the IronPDF docs at https://ironpdf.com/llms.txt.

What are the options for adding a footer with page numbers to a rendered PDF?
Show the exact class and property names from the documentation, and link the
page you took them from.
Text

Pedir la página de origen es un hábito de verificación económica. Si el editor no puede señalar una página de documentación real para la API que acaba de recomendar, es una señal para verificar antes de escribir código contra ella.

Consejos: Esto se compensa nuevamente más tarde, en las clases desconocidas. Solicita al editor que resuma el tipo de opciones de renderizado y enumere cuáles ya establece tu proyecto, y la referencia de API se convierte en algo que consultas en lugar de desplazar.

¿Cómo escribes reglas de proyecto que codifiquen tus convenciones de IronPDF?

Las reglas del proyecto de Cursor viven en un directorio .cursor/rules en la raíz del repositorio y están bajo control de versiones, por lo que se comprometen junto con el código y cada desarrollador hereda el mismo comportamiento sin configurar nada.

Las reglas son archivos .mdc: markdown con frontmatter YAML que lleva description, globs y alwaysApply. Cursor los lee recursivamente, por lo que los subdirectorios funcionan. Un archivo .md simple en esa carpeta se ignora, porque no tiene frontmatter para activar. Una regla para las convenciones de IronPDF se ve así:

---
description: IronPDF conventions for PDF generation in this project
globs: **/Services/**/*.cs, **/Pdf/**/*.cs
alwaysApply: false
---

# IronPDF conventions

- Use ChromePdfRenderer for all HTML-to-PDF conversion.
- Target the IronPDF version pinned in Directory.Packages.props. Do not upgrade it
  as part of an unrelated change.
- Never inline a license key. Read it from configuration or the
  IRONPDF_LICENSE_KEY environment variable.
- Prefer the shared PdfDocumentService helper over constructing a renderer
  per call. A ChromePdfRenderer instance is reusable.
- Use the async rendering methods in web request paths.
- Do not invent IronPDF API names. If a method is uncertain, say so and cite
  the documentation instead of guessing.
Text

Esa última línea hace más trabajo del que parece. Decirle al modelo que admitir incertidumbre es aceptable reduce las APIs inventadas, y ponerlo en una regla comprometida significa que dejas de repetirlo en cada aviso.

La línea globs es la parte que vale la pena copiar deliberadamente. Todo lo marcado como alwaysApply: true se carga en cada solicitud y gasta presupuesto de contexto, por lo que delimitar la regla de IronPDF a las rutas donde el código PDF realmente vive lo mantiene fuera de las solicitudes que no tienen nada que ver con el renderizado.

Por favor, tenga en cuenta: Cursor también lee un AGENTS.md simple en la raíz del proyecto, el mismo archivo que leen ChatGPT Codex y Google Antigravity. No lleva frontmatter, por lo que no tiene globs y siempre se aplica. Opta por .cursor/rules cuando quieres delimitación, y por AGENTS.md cuando quieres un archivo de instrucciones que honren varias herramientas.

Un límite sorprende a las personas: las reglas se aplican a las interacciones de agente y chat, no a la finalización de Tab o ediciones en línea. Una convención codificada en una regla da forma a lo que el agente escribe y no detendrá a Tab de sugerir otra cosa. Vale la pena saberlo antes de concluir que una regla está siendo ignorada.

¿Qué modo se adapta al cambio?

Cursor expone varias formas distintas de hacer una edición, y elegir la incorrecta desperdicia tiempo. El instinto útil es escalar.

ModoUtilícelo cuandoTarea típica de PDF
TabYa estás escribiendo y la siguiente edición es predecibleTerminar una propiedad de opciones de renderización que has configurado antes
Edición en líneaEl cambio encaja en una oración y vive en un archivoAgregar un margen, un pie de página o configurar el tamaño de página
AgenteEl trabajo abarca archivos, o necesita una compilación y un ciclo de reparaciónConectar un renderizador a un servicio y hacerlo compilar
Planifica primeroUna reescritura es lo suficientemente grande como para que revisarlo después del hecho sea peor que acordar en ello primeroMigrar un generador de reportes de otra biblioteca de PDF
Agente en la nubeLa tarea no necesita ser observada y no bloquea nadaEscribir un conjunto de pruebas sobre la salida PDF

Una edición en línea en un renderizador es la ilustración más clara, porque describes el cambio y revisas una diferencia en su lugar en lugar de leer un nuevo archivo:

Add a 25mm top margin and an HTML footer showing "{page} of {total-pages}",
centered, max height 15mm.
Text

Lo que llega al archivo es lo suficientemente corto para verificarlo de un vistazo:

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.MarginTop = 25;
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
    MaxHeight = 15,
    HtmlFragment = "<div style='text-align:center'>{page} of {total-pages}</div>",
};
C#

MarginTop = 25 reitera el margen superior predeterminado de 25 milímetros de IronPDF, por lo que esa línea deja la página sin cambios. Ningún margen mueve el pie de página. El margen inferior establece dónde se detiene el cuerpo por encima de él, como muestra la corrección del pie de página más adelante en esta página.

{page} y {total-pages} son campos de combinación propios de IronPDF en lugar de marcadores de posición de cadenas que sustituyes tú mismo, lo cual es el tipo de detalle que la documentación acierta y una adivinanza sin fundamentos generalmente no lo hace.

¿Qué cambia realmente una mención de @?

Las menciones de contexto le dicen al editor exactamente qué mirar. Nombrar el archivo que construye un PDF produce un resultado mucho mejor que describirlo, porque una descripción es con pérdida y una referencia de archivo no lo es.

@Services/InvoiceRenderer.cs @Templates/invoice.html Use the IronPDF docs at https://ironpdf.com/llms.txt.

The footer overlaps the last line of the invoice table. Fix it in the renderer
configuration, not the template. Explain which setting causes the overlap.
Text

Junto a los archivos, el menú @ de Cursor toma carpetas para el trabajo que abarca un módulo, salida del terminal, chats anteriores, diferencias de Git y el navegador incorporado. Cuando no sabes qué archivo importa, deja la mención fuera y el agente busca el propio código. Combinar un archivo con un enlace de documentación, como se ve arriba, es el patrón que mantiene el trabajo de IronPDF preciso: el archivo suministra lo que tu código hace actualmente, y la documentación lo que la biblioteca realmente ofrece.

Ese aviso particular también ilustra por qué la fundamentación importa. Un pie de página configurado sin un margen correspondiente se superpone al cuerpo, porque el pie de página ocupa espacio que el contenido no cede por sí solo. Es una configuración de renderizado en lugar de un problema de CSS, y la guía de encabezados y pies de página documenta la relación.

Esta es la factura que el ensayo de prueba generó después de la corrección:

¿Cómo planeas y ejecutas una migración a IronPDF?

Las migraciones son donde una reescritura de varios archivos no revisada se vuelve costosa, porque desarmar una es más difícil que escribirla. Planificar antes de la implementación existe exactamente para esto: toma el objetivo, hace preguntas aclaratorias y produce un plan editable antes de que se escriba cualquier código.

@Reports/ Use the IronPDF docs at https://ironpdf.com/llms.txt.

This folder builds PDFs by positioning text at coordinates with another library.
Plan a migration to IronPDF using HTML templates.

Summarize what the current output looks like, covering page size, sections, and
fonts, then propose the template structure and the files that change. Keep
existing public method signatures so callers don't change. Don't write code yet.
Text

Revisa el plan, corrígelo en una o dos oraciones y devuélvelo para implementarlo. El modo agente lee la base de código, edita archivos, ejecuta comandos de terminal, lee la salida e itera, por lo que el seguimiento es breve:

Implement the approved plan. Then run dotnet build, fix what breaks, and
show me the diff. Don't add new packages.
Text

Restringir al agente al plan aprobado y prohibir nuevos paquetes importa más de lo que parece. Los agentes sin restricciones tienden a tratar una migración como una invitación para rediseñar la convención de llamadas como un extra.

El trabajo que no necesita supervisión puede ejecutarse en un agente en la nube mientras continúas en otro lugar. Un conjunto de pruebas sobre la salida de PDF es un buen candidato, porque las pruebas afirman sobre el documento en lugar de la implementación y no necesitan que la migración se termine primero:

Write xUnit tests for the migrated report output: result is non-empty, begins
with the %PDF- signature, extracted text contains the bound company name, and
page count matches expectation. No golden-file byte comparisons, since
rendering output is not byte-stable across versions or platforms.
Text

Descartar la comparación de bytes previene toda una clase de pruebas inestables que de otro modo le costarían a alguien una tarde.

¿Dónde realmente residen los problemas de renderizado?

Tres de las causas que IronPDF documenta para las diferencias entre el navegador y el PDF son un hoja de estilo escrita para medios de pantalla en lugar de medios de impresión, una fuente web que no cargó cuando se calculó el diseño, y contenido producido por JavaScript que fue capturado demasiado pronto. Nombrar el síntoma y el archivo obtiene una respuesta mucho más útil que pegar todo el proyecto.

@Templates/report.html @Services/ReportRenderer.cs Use the IronPDF docs at https://ironpdf.com/llms.txt.

The report renders correctly in Chrome but the PDF drops the logo and splits a
table row across pages. Explain the cause of each before changing anything,
then fix the table break in CSS and the logo in the renderer configuration.
Text

Separar el diagnóstico de la solución te da algo para evaluar en lugar de un cambio para retro-ingeniería. En este caso, los dos problemas tienen diferentes hogares: el comportamiento de ruptura de página pertenece a la hoja de estilo, cubierto por la guía de saltos de página, mientras que un logo que se resuelve en un navegador y no en el render suele ser una cuestión de ruta base, porque una cadena HTML sin formato no lleva ninguna ubicación de documento para resolver URLs relativas.

Este es el informe del sitio que el ensayo de prueba generó después de ambas correcciones:

Las fallas de implementación son donde el acceso terminal gana su lugar, ya que la respuesta generalmente vive en el contenedor en lugar del código.

@Dockerfile Use the IronPDF docs at https://ironpdf.com/llms.txt.

Rendering works on Windows but fails in our Linux container with:

[PASTE FULL EXCEPTION AND STACK TRACE HERE]

Check for missing native dependencies IronPDF's Chromium engine needs on
Debian-based images. Explain the cause, then propose the Dockerfile change.
Don't modify C# code unless the cause is there.
Text

La instrucción de no tocar el código de la aplicación es deliberada. Una biblioteca compartida ausente en una imagen no es un problema de C#, y un agente con carta blanca a veces envolverá la llamada en un try/catch que oculta la falla en lugar de arreglarla. La guía de implementación de Docker documenta los requisitos actuales, que cambian entre lanzamientos.

¿Qué produjeron los prompts en una ejecución real?

Siete de los nueve avisos en esta página se ejecutaron en orden en una sola sesión de CLI de Cursor, versión 2026.10.14-941492e. La edición en línea se ejecutó en la aplicación de escritorio de Cursor, versión 3.23.23. El proyecto era una pequeña aplicación .NET 8 en IronPDF 2026.10.3 con cada archivo que los avisos nombran y los defectos que describen. Las cifras a continuación provienen de generaciones independientes del código que escribió el agente, no de sus respuestas.

  • El agente obtuvo 21 páginas diferentes de documentación de IronPDF durante la sesión, comenzando desde llms.txt.
  • Cada clase y miembro nombrado en la respuesta del pie de página existía en IronPDF 2026.10.3, y las siete páginas que citaba cargaron.
  • El programa Quickstart escribió un hello.pdf de una página de 17,385 bytes con la clave establecida y lanzó una LicensingException en SaveAs sin ella.
  • La edición en línea agregó un margen superior de 25 mm, que es el predeterminado de IronPDF, y un pie de página centrado que imprimió "1 de 1".
  • Antes de la corrección del pie de página, la fila Total adeudado se imprimía sobre la primera línea del pie de página de una factura de una página.
  • La corrección elevó el margen inferior en InvoiceRenderer.cs de 10 a 40 milímetros y dejó la plantilla sin cambios.
  • Después de la corrección, ninguna línea de la factura tocó el pie de página, y los totales se movieron a una segunda página.
  • La migración mantuvo las cuatro firmas de métodos públicos, eliminó PDFsharp y no añadió ningún paquete.
  • El informe migrado mantuvo dos páginas A4, las fuentes Arial, el orden de las secciones y el total regional.
  • Dos renders del mismo informe migrado tenían el mismo tamaño y bytes diferentes.
  • Las pruebas xUnit pasaron 4 de 4 con la clave y 0 de 4 sin ella.
  • Antes de la corrección de renderizado, el informe del sitio mostraba el texto alternativo del logo y dividía su última fila de tabla entre las páginas 1 y 2.
  • La corrección pasó la carpeta de plantillas como la ruta base, y una regla de hojas de estilo mantuvo cada fila de la tabla junta.
  • Después de la corrección, el logo apareció en la página 1 y la última fila se trasladó completa a la página 2.
  • En las pruebas de CLI, el archivo de reglas se aplicó en 6 de 6 pruebas con globs separados por comas y en 0 de 6 con una lista YAML.
  • Algunos pasos se ejecutaron de manera diferente a lo esperado. La CLI envió cada mención @ como texto simple, y el agente abrió los archivos nombrados con sus propias herramientas. Después del plan de migración, la sesión se mantuvo en modo plan, por lo que los dos avisos siguientes devolvieron planes que un mensaje de seguimiento generó. El suite de pruebas se ejecutó como un agente local, porque los agentes en la nube necesitan un repositorio hospedado. El aviso de edición en línea se ejecutó en la aplicación de escritorio de Cursor, que lo registró como un chat de agente con la línea seleccionada adjunta. El aviso de Docker no se ejecutó, porque la máquina de prueba no tiene Docker ni entorno Linux.

El registro de ejecución en la guía de asistentes de codificación de IA enumera la herramienta, el modelo y la duración de cada guía en esta serie.

¿Qué debería configurar primero?

La fundamentación, antes que cualquier otra cosa. Vincular la documentación de IronPDF y comprometer una regla de proyecto delimitada lleva unos quince minutos, se aplica a cada aviso después, y es toda la diferencia entre este flujo de trabajo y pegar preguntas en un asistente de chat general. Todo después de eso, las ediciones en línea, las menciones, la planificación, los agentes, es uso ordinario del editor que sucede a funcionar mejor una vez que la fundamentación está en su lugar.

El hábito de verificación permanece igual independientemente del modelo que esté respondiendo: compila temprano, abre el PDF y revisa los nombres de API contra la documentación antes de que se envíe nada. La versión reproducible de esa verificación, ejecutada de inicio a fin con un resultado publicado, vive en la guía de asistentes de codificación AI, junto a las guías para ChatGPT Codex, GitHub Copilot, y Google Antigravity.


Solución de problemas


¿Preguntas?

Si tienes alguna pregunta, contacta a support@ironsoftware.com

Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.

Leer más

¿Listo para empezar?

Descargas de NuGet 22,198,312Versión:2026.11recién lanzado