Bundling y frontends web

Needle Engine se construye como un web component. Esto significa que basta con instalar @needle-tools/engine en tu proyecto e incluir <needle-engine src="path/to/your.glb"> en cualquier parte de tu proyecto web.

• Instalar usando npm: npm i @needle-tools/engine

Con nuestra plantilla de proyecto por defecto basada en Vite, Needle Engine se empaqueta (bundled) en una aplicación web en el momento del despliegue. Esto asegura archivos más pequeños, tree-shaking (similar a code stripping en Unity) y optimiza los tiempos de carga. En lugar de descargar numerosos scripts y componentes pequeños, solo se descargan uno o unos pocos que contienen el código mínimo necesario.

Vite (nuestro bundler por defecto) tiene una buena explicación de por qué las aplicaciones web deberían ser empaquetadas (bundled): Why Bundle for Production

Vite, Vue, React, Svelte, React Three Fiber...

Needle Engine no tiene preferencia sobre la elección del framework. Nuestra plantilla por defecto usa el popular vite como bundler. Desde ahí, puedes añadir vue, svelte, nuxt, react, react-three-fiber u otros frameworks, y tenemos ejemplos para muchos de ellos. También puedes integrar otros bundlers, o no usar ninguno — solo HTML y Javascript planos.

Aquí tienes algunos ejemplos de stacks tecnológicos posibles y con los que usamos Needle Engine:

• Vite + HTML — ¡Esto es lo que usa nuestra plantilla por defecto!

• Vite + Vue — ¡Esto es lo que usa la web de Needle Tools! Encuentra un ejemplo para descargar aquí.

• Vite + Svelte

• Vite + SvelteKit

• Vite + React — ¡Hay una plantilla experimental incluida con la integración de Unity para esto que puedes elegir al generar un proyecto!

• react-three-fiber — ¡Hay una plantilla experimental incluida con la integración de Unity para esto que puedes elegir al generar un proyecto!

• Vercel & Nextjs — Encuentra un proyecto de ejemplo con nextjs aquí

• CDN sin ningún bundler — Encuentra un ejemplo de código aquí

En resumen: actualmente proporcionamos una plantilla minimalista con vite, pero puedes extenderla o cambiar a otros frameworks – Cuéntanos qué y cómo construyes, y cómo podemos mejorar la experiencia para tu caso de uso o proporcionar un ejemplo.

Tree-shaking para reducir el tamaño del bundle

Tree shaking se refiere a una práctica común en el bundling de aplicaciones web (ver docs de MSDN). Significa que las rutas de código y características que no se usan en tu código serán eliminadas del archivo(s) javascript final empaquetado para reducir el tamaño del archivo. Consulta a continuación las características que Needle Engine incluye y cómo eliminarlas:

Creando una PWA

Apoyamos la creación sencilla de una Progressive Web App (PWA) directamente desde nuestra plantilla de vite. Las PWAs son aplicaciones web que se cargan como páginas web o sitios web normales, pero pueden ofrecer funcionalidades de usuario como trabajar sin conexión, notificaciones push y acceso al hardware del dispositivo, tradicionalmente solo disponibles para aplicaciones móviles nativas.

Por defecto, las PWAs creadas con Needle tienen soporte sin conexión y opcionalmente pueden actualizarse automáticamente cuando publicas una nueva versión de tu aplicación.

1. Instala el plugin Vite PWA en tu proyecto web: npm install vite-plugin-pwa --save-dev
2. Modifica vite.config.js como se muestra a continuación. Asegúrate de pasar el mismo objeto pwaOptions tanto a needlePlugins como a VitePWA.

import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig(async ({ command }) => {

    // Create the pwaOptions object.
    // You can edit or enter PWA settings here (e.g. change the PWA name or add icons).
    /** @type {import("vite-plugin-pwa").VitePWAOptions} */
    const pwaOptions = {};

    const { needlePlugins } = await import("@needle-tools/engine/plugins/vite/index.js");

    return {
        plugins: [
            // pass the pwaOptions object to the needlePlugins and the VitePWA function
            needlePlugins(command, needleConfig, { pwa: pwaOptions }),
            VitePWA(pwaOptions),
        ],
        // the rest of your vite config...

Probando PWAs

Para probar tu PWA, despliega la página, por ejemplo usando el componente DeployToFTP. Luego, abre la página desplegada en un navegador y comprueba si las funcionalidades de la PWA funcionan como se espera:

• la aplicación aparece como instalable
• la aplicación funciona sin conexión
• la aplicación es detectada como PWA capaz de funcionar sin conexión por pwabuilder.com

Las PWAs usan Service Workers para cachear recursos y proporcionar soporte sin conexión. Los Service Workers son algo más difíciles de usar durante el desarrollo, y típicamente solo se habilitan para builds (por ejemplo, cuando usas un componente DeployTo...).

Puedes habilitar el soporte para PWA en desarrollo añadiendo lo siguiente al objeto de opciones en tu vite.config.js.

const pwaOptions = {
  // Note: PWAs behave different in dev mode.
  // Make sure to verify the behaviour in production builds!
  devOptions: {
    enabled: true,
  }
};

Ten en cuenta que las PWAs en modo de desarrollo no soportan el uso sin conexión; intentarlo puede resultar en un comportamiento inesperado.

Actualizar automáticamente aplicaciones en ejecución

Las webs típicamente muestran contenido nuevo o actualizado al refrescar la página.

En algunas situaciones, puede que desees que la página se refresque y recargue automáticamente cuando se haya publicado una nueva versión – como en un museo, feria comercial, pantalla pública u otros escenarios de larga duración.

Para habilitar las actualizaciones automáticas, establece la propiedad updateInterval en el objeto pwaOptions a una duración (en milisegundos) en la que la aplicación debe buscar actualizaciones. Si se detecta una actualización, la página se recargará automáticamente.

const pwaOptions = {
  updateInterval: 15 * 60 * 1000, // 15 minutes, in milliseconds
};

Más opciones de PWA

Dado que Needle usa el plugin Vite PWA internamente, puedes usar todas las opciones y hooks proporcionados por este. Por ejemplo, puedes proporcionar un manifiesto parcial con un título de aplicación o color de tema personalizado:

const pwaOptions = {
  // manifest options provided here will override the defaults
  manifest: {
    name: "My App",
    short_name: "My App",
    theme_color: "#B2D464",
  }
};

Para requisitos complejos como cacheo parcial, Service Workers personalizados o diferentes estrategias de actualización, puedes eliminar la opción { pwa: pwaOptions } de needlePlugins y añadir la funcionalidad PWA directamente a través del plugin Vite PWA.

Acceso a Needle Engine y Componentes desde javascript externo

El código que expones puede ser accedido desde JavaScript después del bundling. Esto permite construir viewers y otras aplicaciones donde hay una división entre los datos conocidos en tiempo de edición y los datos conocidos solo en tiempo de ejecución (por ejemplo, archivos cargados dinámicamente, contenido generado por el usuario). Para acceder a componentes desde javascript regular fuera del motor, consulta la sección de interoperabilidad con javascript regular

Personalizando la apariencia de carga

Consulta la sección Loading Display en la referencia de componentes de needle engine

Estilos integrados

La apariencia de carga de needle-engine puede usar un skin claro u oscuro. Para cambiar la apariencia, usa el atributo loading-style en el web component <needle-engine>. Las opciones son light y dark (por defecto):

<needle-engine loading-style="light"></needle-engine>

Estilo de carga personalizado — PRO feature

Consulta la sección Loading Display en la referencia de componentes de needle engine

Página traducida automáticamente con IA