Cómo usar IronPdfEngine con Node.js
IronPdfEngine es un servidor gRPC que maneja todas las operaciones de PDF: creación, edición y lectura, en nombre del cliente Node.js. El paquete @ironsoftware/ironpdf es un envoltorio API delgado que se comunica con IronPdfEngine a través de gRPC; cada llamada de método en su código Node.js se ejecuta dentro de ese proceso del servidor. Por defecto, IronPDF for Node.js engendra IronPdfEngine como un subproceso local, pero también puede señalarlo a una instancia alojada remotamente para despliegues compartidos o en contenedor.
Inicio rápido: Configure IronPdfEngine for Node.js
Instale el paquete y IronPdfEngine se ejecuta automáticamente en la primera operación PDF:
//:path=shell
npm install @ironsoftware/ironpdf//:path=shell
npm install @ironsoftware/ironpdfFlujo de trabajo mínimo (5 pasos)
- Instale el paquete Node.js de IronPDF con
npm install @ironsoftware/ironpdf. - En la primera ejecución, IronPDF detecta su plataforma y descarga los binarios correctos de IronPdfEngine.
- Para despliegues fuera de línea o de inicio más rápido, instale un paquete de motor específico de plataforma como
@ironsoftware/ironpdf-engine-windows-x64. - Verifique la versión requerida del motor con la propiedad
IronPdfGlobalConfig.ironPdfEngineVersionantes de desplegar una instancia remota. - Para un motor remoto, llame a
IronPdfGlobalConfig.setConfig({ ironPdfEngineDockerAddress: "host:port" })antes de cualquier operación PDF.
¿Por qué IronPDF for Node.js requiere IronPdfEngine?
IronPDF for Node.js no incluye un renderizador PDF independiente. El paquete de Node.js es un cliente gRPC, e IronPdfEngine es el servidor que realiza el trabajo real de renderización, edición y lectura. Cuando su aplicación llama a cualquier método de IronPDF, la solicitud viaja por gRPC al proceso del motor, que devuelve el resultado a su código Node.js.
Esta arquitectura mantiene el paquete de Node.js ligero y aísla el entorno de renderización. También significa que la versión del motor debe coincidir exactamente con la versión del paquete: no se admiten combinaciones entre versiones.
Cada versión de @ironsoftware/ironpdf requiere la misma versión de IronPdfEngine. Verifique la compatibilidad leyendo la propiedad IronPdfGlobalConfig.ironPdfEngineVersion antes de implementar cualquier actualización del motor.
¿Cómo ejecuta IronPdfEngine localmente?
El despliegue local es el modo predeterminado. IronPDF for Node.js engendra IronPdfEngine como un subproceso al inicio y se comunica con él hasta que su aplicación se cierra. Dos enfoques de instalación están disponibles, cada uno con diferentes compensaciones.
Opción 1: Descargar IronPdfEngine en tiempo de ejecución
Después de instalar @ironsoftware/ironpdf, no se requieren paquetes adicionales. En la primera ejecución, IronPDF detecta la plataforma host (por ejemplo, Windows x64) y descarga de internet los binarios coincidentes de IronPdfEngine.
//:path=shell
npm install @ironsoftware/ironpdf//:path=shell
npm install @ironsoftware/ironpdfPros:
- Mantiene el paquete de aplicación pequeño.
- Despliega a múltiples plataformas sin configuración específica de plataforma.
Contras:
- Requiere acceso a internet en las primeras ejecuciones.
- Tiempo de inicio más lento en la ejecución inicial mientras se recuperan los binarios.
Opción 2 (recomendada): Instalar IronPdfEngine como una Dependencia
IronPDF for Node.js admite paquetes de motor dedicados que agrupan el binario de IronPdfEngine para una plataforma específica. Instale uno o más de estos paquetes junto con la biblioteca principal para eliminar la descarga en tiempo de ejecución.
Los paquetes ironpdf y ironpdf-engine-xxx-xxx deben ser de la misma versión. El número de versión del paquete de motor se refiere al lanzamiento de IronPDF, no a la compilación interna del motor.)}]
Windows x64:
//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x64//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x64Windows x86:
//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x86//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x86Linux x64:
//:path=shell
npm install @ironsoftware/ironpdf-engine-linux-x64//:path=shell
npm install @ironsoftware/ironpdf-engine-linux-x64macOS x64:
//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-x64//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-x64macOS arm64:
//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-arm64//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-arm64Pros:
- Inicio más rápido: no se necesita descarga en tiempo de ejecución.
- No se requiere acceso a internet después de instalar la dependencia.
Contras:
- Tamaño mayor del paquete de la aplicación.
- Requiere especificar plataformas objetivo en tiempo de compilación.
¿Cómo se conecta a un IronPdfEngine remoto?
El despliegue remoto es apropiado cuando la generación de PDF es un servicio compartido, por ejemplo, en una arquitectura de microservicios en contenedor, un clúster de Kubernetes donde varios servicios de Node.js comparten un pod de motor, o cualquier entorno donde centralizar el proceso de renderizado reduce la sobrecarga por servicio. Antes de conectar, tire e inicie la imagen Docker de IronPdfEngine siguiendo Cómo Tirar e Iniciar IronPdfEngine.
¿Cómo Verificar la Versión Requerida del Motor?
La versión del motor debe coincidir con la versión del paquete de Node.js. Lea la propiedad ironPdfEngineVersion para confirmar qué versión descargar:
//:path=get-started/use-ironpdfengine/check-version.js
const ironPdfEngineVersion = IronPdfGlobalConfig.ironPdfEngineVersion;
console.log(`Required IronPdfEngine version: ${ironPdfEngineVersion}`);//:path=get-started/use-ironpdfengine/check-version.js
const ironPdfEngineVersion = IronPdfGlobalConfig.ironPdfEngineVersion;
console.log(`Required IronPdfEngine version: ${ironPdfEngineVersion}`);Use el número de versión impreso al especificar la etiqueta de imagen Docker. Ejecutar una versión no coincidente causará errores de comunicación gRPC.
¿Cómo se configura la conexión remota?
Suponga que IronPdfEngine está ejecutándose en 123.456.7.8:33350. Coloque la llamada de configuración al inicio de su aplicación, antes de cualquier invocación de método de IronPDF.
//:path=get-started/use-ironpdfengine/remote-config.js
IronPdfGlobalConfig.setConfig({
ironPdfEngineDockerAddress: "123.456.7.8:33350"
});//:path=get-started/use-ironpdfengine/remote-config.js
IronPdfGlobalConfig.setConfig({
ironPdfEngineDockerAddress: "123.456.7.8:33350"
});La dirección debe ser accesible desde el host de Node.js. Verifique que ninguna regla del firewall bloquee el puerto 33350 entre el servidor de la aplicación y el host del motor.
Cuando utilice un IronPdfEngine remoto, no necesita instalar ningún paquete de dependencia ironpdf-engine-xxx-xxx. El motor local se omite por completo una vez que se establece ironPdfEngineDockerAddress.
¿Cuáles son los próximos pasos?
Configurar IronPdfEngine es la base para todo el trabajo en PDF en Node.js. Una vez que el motor está funcionando, ya sea local o remotamente, la API completa de IronPDF está disponible: convertir HTML a PDF, fusionar documentos, agregar sellos y marcas de agua, extraer texto y más.
- Comience una licencia de prueba gratuita para desbloquear todas las funciones sin marcas de agua.
- Compre una licencia para despliegues de producción.
- Continúe con el tutorial completo para comenzar con Node.js: IronPDF for Node.js — Getting Started.
Preguntas Frecuentes
¿Qué es IronPdfEngine y por qué se requiere for Node.js?
IronPdfEngine es un servidor gRPC que maneja todas las operaciones de renderización, edición y lectura de PDF. El paquete de Node.js @ironsoftware/ironpdf es un cliente que se comunica con IronPdfEngine a través de gRPC, por lo que el motor debe estar en funcionamiento —local o remotamente— para que cualquier operación PDF tenga éxito.
¿Cómo se instala IronPDF for Node.js?
Ejecute npm install @ironsoftware/ironpdf en su directorio de proyecto. En la primera ejecución, IronPDF detecta la plataforma del host y descarga automáticamente los binarios de IronPdfEngine que concuerdan.
¿Cuál es la diferencia entre la opción de descarga en tiempo de ejecución y la opción de dependencia incluida?
La opción de descarga en tiempo de ejecución no requiere paquetes adicionales pero necesita acceso a internet en la primera ejecución y tiene un inicio más lento. La opción de dependencia incluida (Opción 2, recomendada) instala un paquete específico de la plataforma como @ironsoftware/ironpdf-engine-windows-x64, que incluye el binario del motor para que el inicio sea más rápido y no se necesite acceso a internet después de la instalación, a costa de un paquete más grande.
¿Cómo aseguro que la versión de IronPdfEngine coincida con la versión de mi paquete IronPDF?
Lea la propiedad IronPdfGlobalConfig.ironPdfEngineVersion en tiempo de ejecución para obtener la cadena de versión exacta requerida. El paquete ironpdf y cualquier dependencia ironpdf-engine-xxx-xxx deben ser de la misma versión; no se admiten combinaciones de versiones cruzadas.
¿Cuándo debo usar un IronPdfEngine remoto en lugar de uno local?
Un IronPdfEngine remoto es apropiado para arquitecturas de microservicios en contenedor, implementaciones de Kubernetes donde múltiples servicios Node.js comparten un único pod de renderización, o cualquier escenario donde centralizar el procesamiento PDF reduzca la sobrecarga de recursos por servicio.
¿Cómo conecto Node.js a un IronPdfEngine remoto?
Llame a IronPdfGlobalConfig.setConfig({ ironPdfEngineDockerAddress: "host:port" }) al inicio de su aplicación, antes de cualquier método de IronPDF. Reemplace host:port con la dirección IP y puerto del motor remoto (por defecto 33350). Asegúrese de que la dirección sea accesible y no bloqueada por un firewall.
¿Necesito instalar un paquete de dependencia de motor cuando uso un IronPdfEngine remoto?
No. Cuando se establece ironPdfEngineDockerAddress, IronPDF omite por completo cualquier motor local. No es necesario instalar ningún paquete ironpdf-engine-xxx-xxx para implementaciones remotas.
¿Qué plataformas soporta IronPdfEngine?
Los paquetes de motor específicos de la plataforma están disponibles para Windows x64, Windows x86, Linux x64, macOS x64 y macOS arm64. Instale el paquete que coincida con su objetivo de implementación, o use la opción de descarga en tiempo de ejecución para soportar múltiples plataformas desde una sola instalación.
¿Puedo instalar múltiples paquetes de motor específicos de plataforma en el mismo proyecto?
Sí. Puede instalar más de un paquete ironpdf-engine-xxx-xxx en el mismo proyecto. IronPDF selecciona el binario correcto para la plataforma del host en tiempo de ejecución, lo cual es útil para proyectos que construyen e implementan en múltiples sistemas operativos.
¿Qué puerto usa IronPdfEngine para la comunicación gRPC?
IronPdfEngine escucha en el puerto 33350 de forma predeterminada. Al configurar una conexión remota, incluya este puerto en el valor de ironPdfEngineDockerAddress y verifique que el puerto esté abierto entre el host de Node.js y el host del motor.
¿Aún desplazándote?
¿Quieres una prueba rápida?
ejecutar una muestra Mira cómo tu HTML se convierte en PDF.
Comience gratis
Comience gratis
Reserve demostración en vivo gratis
No se requiere tarjeta de crédito ni creación de cuenta
