Skip to content

Commit

Permalink
feat: open up 'three' peer dependency to include future versions
Browse files Browse the repository at this point in the history
  • Loading branch information
lojjic committed May 17, 2021
1 parent 0987d88 commit d4a5b23
Show file tree
Hide file tree
Showing 4 changed files with 8 additions and 9 deletions.
7 changes: 2 additions & 5 deletions docs/getting-started/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,17 +23,14 @@ etc...

#### Three.js

The `troika-3d` package requires `three` ([Three.js](https://threejs.org)) as a _peer_ dependency, which means you will have to declare `three` as a dependency in your own project.
The packages related to 3D require `three` ([Three.js](https://threejs.org)) as a _peer_ dependency, which means you will have to declare `three` as a dependency in your own project.

```sh
npm install --save three
```

You'll need to make sure that you keep your `three` dependency matches the range of supported versions declared in `troika-three-utils/package.json`, and keep that up to date in the future as you update Troika. You should see messages from `npm` in your terminal to remind you if you get behind.
The allowed version range for `three` is open-ended, so you _should_ be able to use any relatively recent version without issues. However, Three.js releases do often contain [breaking changes](https://github.com/mrdoob/three.js/wiki/Migration-Guide) which may introduce incompatibilities in the future. While we try to test against recent `three` versions on a regular basis, some of these may slip by our notice; if you find one, please [open an issue](https://github.com/protectwise/troika/issues) for us.

Because the Three.js API tends to have rather [significant changes between releases](https://github.com/mrdoob/three.js/wiki/Migration-Guide), Troika has to be specific about the range of versions it currently works with. We try to keep that at the largest possible range that we know won't break. You _may_ try using a later version of `three` than officially supported, just no guarantees with that.

(It's a tad inconvenient that you have to manage this yourself, but we went this route because it makes it more obvious which version of Three.js your project uses and decreases the chance of multiple conflicting versions being installed together.)

#### React

Expand Down
4 changes: 4 additions & 0 deletions packages/troika-three-text/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ npm install troika-three-text

You will also need to install a compatible version of [Three.js](https://threejs.org); see the [notes on Three.js versions in the Getting Started docs](../../docs/getting-started/setup.md#threejs) for details.

```sh
npm install three
```

## Usage

```js
Expand Down
4 changes: 1 addition & 3 deletions packages/troika-three-utils/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,12 @@ Get it from [NPM](https://www.npmjs.com/package/troika-three-utils):
npm install troika-three-utils
```

You will also need to install a compatible version of [Three.js](https://threejs.org), which is declared with a wide version range in `peerDependencies` rather than a direct dependency on a specific version, to give you flexibility in choosing a specific version for your application.
You will also need to install a compatible version of [Three.js](https://threejs.org); see the [notes on Three.js versions in the Getting Started docs](../../docs/getting-started/setup.md#threejs) for details.

```sh
npm install three
```

You can look in the [package.json](./package.json) under `"peerDependencies"` for a range of Three.js versions that has been verified to work with this and all other Troika packages. Other versions that have not been specifically tested may also work depending on the features you use, they just haven't been explicitly tested.


## Provided Utilities

Expand Down
2 changes: 1 addition & 1 deletion packages/troika-three-utils/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,6 @@
"module": "dist/troika-three-utils.esm.js",
"module:src": "src/index.js",
"peerDependencies": {
"three": "0.103.x - 0.127.x"
"three": ">=0.103.0"
}
}

0 comments on commit d4a5b23

Please sign in to comment.