3d-effect-cinema 0.5.2 → 0.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/GUIA_SOLUCION_NEXT_3D_CINEMA.md +73 -0
- package/package.json +16 -2
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Guía Completa de Integración y Solución de Errores: Next.js + 3d-effect-cinema (v0.5.0)
|
|
2
|
+
|
|
3
|
+
> [!IMPORTANT]
|
|
4
|
+
> **Resolución Total en v0.5.0**: Todos los 6 errores listados en esta guía han sido corregidos directamente en la arquitectura interna y empaquetado del paquete `3d-effect-cinema@0.5.0`.
|
|
5
|
+
>
|
|
6
|
+
> Ahora la librería es **100% Plug & Play** en cualquier proyecto de Next.js (14, 15 y 16, App Router o Pages Router con Turbopack o Webpack) y React. Los usuarios pueden importar `<AnimatedBackground />` directamente **sin necesidad de `next/dynamic` (`ssr: false`), sin `NextIntlClientProvider`, sin parches `window.React` y sin reglas personalizadas en `next.config.ts`**.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## ⚡ Ejemplo de Uso Ultra-Sencillo (Next.js App Router / Pages Router)
|
|
11
|
+
|
|
12
|
+
### 📁 `app/page.tsx`
|
|
13
|
+
```tsx
|
|
14
|
+
import AnimatedBackground from "3d-effect-cinema";
|
|
15
|
+
|
|
16
|
+
export default function Home() {
|
|
17
|
+
return (
|
|
18
|
+
<div className="w-full h-screen">
|
|
19
|
+
<AnimatedBackground
|
|
20
|
+
title="CINEMULTIPLEX"
|
|
21
|
+
fontFamily="helvetiker"
|
|
22
|
+
effect="blobs,flames"
|
|
23
|
+
effectColor="#00e5ff"
|
|
24
|
+
loaderDuration={5}
|
|
25
|
+
redirectUrl="/home"
|
|
26
|
+
containerSelector="home"
|
|
27
|
+
/>
|
|
28
|
+
</div>
|
|
29
|
+
);
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 🛠️ Detalle de los 6 Errores Solucionados en la Librería v0.5.0
|
|
36
|
+
|
|
37
|
+
### 1. Incompatibilidad de Turbopack/Webpack y Tres.js Duplicado (Errores 1 y 2)
|
|
38
|
+
- **Causa**: Múltiples instancias de `three` cargadas en memoria al importar submódulos ESM no externalizados.
|
|
39
|
+
- **Solución en v0.5.0**: Se configuró `three`, `@react-three/fiber`, `@react-three/drei` y `@react-three/postprocessing` como `external` en `tsup.config.ts` y en `peerDependencies` de `package.json`. Turbopack y Webpack ahora resuelven una única instancia unificada desde el proyecto principal.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
### 2. Error de Contexto de `next-intl` (`NextIntlClientProvider`) (Error 3)
|
|
44
|
+
- **Causa**: La librería llamaba internamente al hook `useTranslations()` de `next-intl`, provocando excepciones si la aplicación consumidora no tenía configurado internacionalización.
|
|
45
|
+
- **Solución en v0.5.0**: Se desacopló `next-intl` de los componentes principales de la librería (`i18n-safe.ts`), permitiendo que `<AnimatedBackground />` funcione de forma independiente en cualquier proyecto sin proveedores ni contextos externos.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
### 3. Restricción `ssr: false` en Server Components (Error 4)
|
|
50
|
+
- **Causa**: Next.js App Router renderiza Server Components por defecto y `next/dynamic` lanzaba error al usar `ssr: false`.
|
|
51
|
+
- **Solución en v0.5.0**: Se integró un **Guard de Hidratación e Incrustación SSR (`isMounted`)** dentro del componente `<AnimatedBackground />`. Durante la fase de SSR en Node.js, renderiza una estructura HTML/CSS limpia con el color/gradiente de fondo, y al hidratarse en el navegador conmuta suavemente al lienzo Canvas 3D de Three.js. No requiere `next/dynamic` ni `"use client"` en la página del usuario.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
### 4. `Uncaught ReferenceError: React is not defined` (Error 5)
|
|
56
|
+
- **Causa**: El empaquetador compilaba JSX asumiendo la existencia del objeto global `window.React`.
|
|
57
|
+
- **Solución en v0.5.0**: Se añadió la cabecera `banner: { js: '"use client";\nimport React from "react";' }` en `tsup.config.ts`. Todo archivo generado CJS/ESM declara explícitamente `import React from "react"`, garantizando que React esté siempre disponible en cualquier entorno de ejecución.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
### 5. Resolución ESM de `lucide-react` (Error 6)
|
|
62
|
+
- **Causa**: Turbopack fallaba al resolver subrutas internas `.mjs` de `lucide-react`.
|
|
63
|
+
- **Solución en v0.5.0**: Se externalizó `lucide-react` y se sustituyeron las dependencias de subrutas por componentes de iconos limpios.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## 📦 Instalación Única
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm install 3d-effect-cinema three @react-three/fiber @react-three/drei
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
¡Listo para usar! 🚀
|
package/package.json
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "3d-effect-cinema",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.4",
|
|
4
4
|
"private": false,
|
|
5
|
+
"description": "High-performance WebGL 3D background effects and cinematic splash intro loader for React and Next.js",
|
|
5
6
|
"main": "./dist/index.js",
|
|
6
7
|
"module": "./dist/index.mjs",
|
|
7
8
|
"types": "./dist/index.d.ts",
|
|
@@ -14,8 +15,21 @@
|
|
|
14
15
|
},
|
|
15
16
|
"files": [
|
|
16
17
|
"dist",
|
|
17
|
-
"public"
|
|
18
|
+
"public",
|
|
19
|
+
"README.md",
|
|
20
|
+
"GUIA_SOLUCION_NEXT_3D_CINEMA.md"
|
|
18
21
|
],
|
|
22
|
+
"readmeFilename": "README.md",
|
|
23
|
+
"repository": {
|
|
24
|
+
"type": "git",
|
|
25
|
+
"url": "https://github.com/esteban284/3d-effect-cinema"
|
|
26
|
+
},
|
|
27
|
+
"homepage": "https://github.com/esteban284/3d-effect-cinema#readme",
|
|
28
|
+
"bugs": {
|
|
29
|
+
"url": "https://github.com/esteban284/3d-effect-cinema/issues"
|
|
30
|
+
},
|
|
31
|
+
"author": "Esteban Puentes",
|
|
32
|
+
"license": "MIT",
|
|
19
33
|
"scripts": {
|
|
20
34
|
"dev": "next dev --turbopack",
|
|
21
35
|
"build": "next build --turbopack",
|