three.js -> peer dependency (#4135)

* switch three to peer dep * update readme * updated faq
google · Feb 17, 2023 · 8c14189 · 8c14189
1 parent fc61c5d
commit 8c14189
Show file tree

Hide file tree

Showing 12 changed files with 84 additions and 56 deletions.
diff --git a/README.md b/README.md
@@ -16,6 +16,8 @@ Check out the README.md files for specific projects to get more details:
 
 🎨 **[shared-assets](packages/shared-assets)** • 3D models, environment maps and other assets shared across many sub-projects
 
+🚀 **[space-opera](packages/space-opera/)** • The source of the `<model-viewer>` [editor](editor)
+
 ## Development
 
 When developing across all the projects in this repository, first install git,

diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/model-viewer/README.md b/packages/model-viewer/README.md
@@ -1,13 +1,15 @@
+<script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.1/model-viewer.min.js"></script>
 <p align="center">
-  <img alt="A 3D model of an astronaut" src="screenshot.png" width="480">
+  <model-viewer alt="Neil Armstrong's Spacesuit from the Smithsonian Digitization Programs Office and National Air and Space Museum" src="https://modelviewer.dev/shared-assets/models/NeilArmstrong.glb" ar environment-image="https://modelviewer.dev/shared-assets/environments/moon_1k.hdr" poster="https://modelviewer.dev/shared-assets/models/NeilArmstrong.webp" shadow-intensity="1" camera-controls touch-action="pan-y" style="width: 480px; height: 600px"></model-viewer>
 </p>
 
 # `<model-viewer>`
 
- [![Build Status](https://github.com/google/model-viewer/workflows/Unit%20tests/badge.svg?branch=master)](https://github.com/google/model-viewer/actions?query=branch%3Amaster)
- [![NPM](https://img.shields.io/npm/v/@google/model-viewer.svg)](https://www.npmjs.com/package/@google/model-viewer)
- [![Bundlephobia](https://badgen.net/bundlephobia/minzip/@google/model-viewer)](https://bundlephobia.com/result?p=@google/model-viewer)
- [![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/model-viewer)
+ [![Min Zip](https://badgen.net/bundlephobia/minzip/@google/model-viewer)](https://bundlephobia.com/result?p=@google/model-viewer)
+ [![Latest Release](https://img.shields.io/github/v/release/google/model-viewer)](https://github.com/google/model-viewer/releases)
+
+ [![follow on Twitter](https://img.shields.io/twitter/follow/modelviewer?style=social&logo=twitter)](https://twitter.com/intent/follow?screen_name=modelviewer)
+ [![Github Discussions](https://img.shields.io/github/stars/google/model-viewer.svg?style=social&label=Star&maxAge=2592000)](https://github.com/google/model-viewer/discussions)
 
 `<model-viewer>` is a web component that makes rendering interactive 3D
 models - optionally in AR - easy to do, on as many browsers and devices as possible.
@@ -18,21 +20,21 @@ As new standards and APIs become available `<model-viewer>` will be improved
 to take advantage of them. If possible, fallbacks and polyfills will be
 supported to provide a seamless development experience.
 
-[Demo](https://model-viewer.glitch.me) • [Documentation](https://modelviewer.dev/) • [Kanban](https://github.com/google/model-viewer/projects/1) • [Quality Tests](https://modelviewer.dev/fidelity/)
+[Demo](https://model-viewer.glitch.me) • [Documentation](https://modelviewer.dev/) • [Quality Tests](https://modelviewer.dev/fidelity/)
 
 
 ## Installing
 
 The `<model-viewer>` web component can be installed from [NPM](https://npmjs.org):
 
 ```sh
-npm install @google/model-viewer
+npm install three @google/model-viewer
 ```
 
-It can also be used directly from various free CDNs such as Google's own [hosted libraries](https://developers.google.com/speed/libraries#model-viewer):
+It can also be used directly from various free CDNs such as [jsDelivr](https://www.jsdelivr.com/package/npm/@google/model-viewer) and Google's own [hosted libraries](https://developers.google.com/speed/libraries#model-viewer):
 
 ```html
-<script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.0/model-viewer.min.js"></script>
+<script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.1/model-viewer.min.js"></script>
 ```
 
 For more detailed usage documentation and live examples, please visit our docs
@@ -51,6 +53,14 @@ testing).
 
 If you’ve installed via [NPM](https://npmjs.org), you’re all set - you’ll only
 upgrade when you run [`npm update`](https://docs.npmjs.com/cli/update.html).
+Note that three.js is a peer dependency, so that must also be installed, but can
+be shared with other bundled code. Note that `<model-viewer>` requires the
+version of three.js we test on to maintain quality, due to frequent upstream
+breaking changes. We strongly recommend you keep your three.js version locked to
+`<model-viewer>`'s. If you must use a different version, npm will give you an
+error which you can work around using their `--legacy-peer-deps` option, which
+will allow you to go outside of our version range. Please do not file issues if
+you use this option. 
 
 ## Browser Support
 

diff --git a/packages/model-viewer/package-lock.json b/packages/model-viewer/package-lock.json
diff --git a/packages/model-viewer/package.json b/packages/model-viewer/package.json
@@ -73,9 +73,11 @@
     "3d"
   ],
   "dependencies": {
-    "three": "^0.149.0",
     "lit": "^2.2.3"
   },
+  "peerDependencies": {
+    "three": "^0.149.0"
+  },
   "devDependencies": {
     "@open-wc/karma-esm": "^4.0.0",
     "@rollup/plugin-commonjs": "^22.0.1",
@@ -103,7 +105,8 @@
     "rollup-plugin-dts": "^4.2.2",
     "rollup-plugin-polyfill": "^3.0.0",
     "rollup-plugin-terser": "^7.0.2",
-    "typescript": "4.8.4"
+    "typescript": "4.8.4",
+    "three": "^0.149.0"
   },
   "publishConfig": {
     "access": "public"

diff --git a/packages/modelviewer.dev/data/faq.json b/packages/modelviewer.dev/data/faq.json
@@ -74,9 +74,10 @@
       {
         "name": "How should I access &lt;model-viewer&gt;?",
         "htmlName": "cdn",
-        "description": "If you control your own hosting, the safest option is always to host model-viewer.min.js yourself on the same server as your site. For smaller sites and blogs, it is often more convenient to use one of various free CDNs - Google provides &lt;model-viewer&gt; as one of its hosted libraries, which we recommend as it is a fast and reliable CDN. Simply specify your desired version in the URL: <code>https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.0/model-viewer.min.js</code>. We used to recommend unpkg, but it has had several serious outages recently. It can automatically pick the most recent version, but this is not a good practice as it slows loading (two requests) and ideally you should test when updating to ensure no bugs have been introduced.",
+        "description": "If you control your own hosting, the safest option is always to host model-viewer.min.js yourself on the same server as your site. For smaller sites and blogs, it is often more convenient to use one of various free CDNs - Google provides &lt;model-viewer&gt; as one of its hosted libraries, which we recommend as it is a fast and reliable CDN. Simply specify your desired version in the URL: <code>https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.0/model-viewer.min.js</code>. We used to recommend unpkg, but it has had several serious outages recently. It can automatically pick the most recent version, but this is not a good practice as it slows loading (two requests) and ideally you should test when updating to ensure no bugs have been introduced. Another good option is jsDelivr.",
         "links": [
-          "<a href='https://developers.google.com/speed/libraries#model-viewer'>Google Hosted Libraries</a>"
+          "<a href='https://developers.google.com/speed/libraries#model-viewer'>Google Hosted Libraries</a>",
+          "<a href='https://www.jsdelivr.com/package/npm/@google/model-viewer'>jsDelivr</a>"
         ]
       },
       {
@@ -94,6 +95,14 @@
         "links": [
           "<a href='https://dev.to/asross311/a-strongly-typed-google-model-viewer-implementation-in-react-3m5c'>Working with React types</a>"
         ]
+      },
+      {
+        "name": "How do I avoid duplicating three.js in my bundle?",
+        "htmlName": "duplication",
+        "description": "Three.js used to be marked as our dependency, which meant it was duplicated if you used it in another part of your code base too. As of v3.0.2, it is marked as our peer dependency, allowing you to share it. Note that we pin its version due to frequent breaking changes, so you will not have much version flexibility. This can be worked around using npm's --legacy-peer-deps mode, but please do not file issues if you do this, as we can only ensure our tested quality on one version of three.js at a time.",
+        "links": [
+          "<a href='https://docs.npmjs.com/cli/v7/using-npm/config#legacy-peer-deps'>NPM legacy-peer-deps documentation</a>"
+        ]
       }
     ]
   },

diff --git a/packages/modelviewer.dev/examples/twitter/player.html b/packages/modelviewer.dev/examples/twitter/player.html
@@ -22,7 +22,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no"/>
   <meta name="color-scheme" content="dark light">
 
-  <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.0/model-viewer.min.js"></script>
+  <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.1/model-viewer.min.js"></script>
   <script>
     window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
     ga('create', 'UA-169901325-1', { 'storage': 'none' });

diff --git a/packages/modelviewer.dev/index.html b/packages/modelviewer.dev/index.html
@@ -68,10 +68,10 @@ <h3 class="grouping-title grouping-title-new quick-start">Quick Start</h3>
               <example-snippet inert-script stamp-to="demo-container" highlight-as="html">
                 <template>
 <!-- Import the component -->
-<script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.0/model-viewer.min.js"></script>
+<script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.1/model-viewer.min.js"></script>
 
 <!-- Use it like any other HTML element -->
-<model-viewer alt="Neil Armstrong's Spacesuit from the Smithsonian Digitization Programs Office and National Air and Space Museum" src="shared-assets/models/NeilArmstrong.glb" ar environment-image="shared-assets/environments/moon_1k.hdr" poster="shared-assets/models/NeilArmstrong.webp" shadow-intensity="1" camera-controls touch-action="pan-y" generate-schema></model-viewer>
+<model-viewer alt="Neil Armstrong's Spacesuit from the Smithsonian Digitization Programs Office and National Air and Space Museum" src="shared-assets/models/NeilArmstrong.glb" ar environment-image="shared-assets/environments/moon_1k.hdr" poster="shared-assets/models/NeilArmstrong.webp" shadow-intensity="1" camera-controls touch-action="pan-y"></model-viewer>
                 </template>
               </example-snippet>
             </div>

diff --git a/packages/modelviewer.dev/package-lock.json b/packages/modelviewer.dev/package-lock.json
diff --git a/packages/render-fidelity-tools/package-lock.json b/packages/render-fidelity-tools/package-lock.json
diff --git a/packages/space-opera/package-lock.json b/packages/space-opera/package-lock.json
diff --git a/packages/space-opera/src/components/best_practices/constants.ts b/packages/space-opera/src/components/best_practices/constants.ts
@@ -30,7 +30,7 @@ export const modelViewerTemplate = `<!doctype html>
     <!-- <model-viewer> HTML element -->
     REPLACEME
     <!-- Loads <model-viewer> for browsers: -->
-    <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.0/model-viewer.min.js"></script>
+    <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.1/model-viewer.min.js"></script>
   </body>
 </html>`;