Skip to content

Commit

Permalink
(docs): add a section on bundler performance optimizations
Browse files Browse the repository at this point in the history
- this is likely an area of concern for users and may even be a
  barrier to adoption for this library, so document it directly in
  the README to reach the greatest amount of people
  - some users may not even know these optimizations exist, so this
    should particularly help them in getting up to speed (pun intended)

- major downside of documenting this officially is that it must now be
  supported / maintained -- namely, this means that changing the path
  to ammo.js would now be considered a breaking change
  - but this library doesn't go through many changes and all that
    physijs code has been split into its own directory, so that's a
    trade-off I'm willing to make
  • Loading branch information
agilgur5 committed Nov 25, 2019
1 parent bdf5e4a commit f292580
Showing 1 changed file with 47 additions and 0 deletions.
47 changes: 47 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,53 @@ npm install -D webworkify

See the [webpack.js](webpack.js) and [browserify.js](browserify.js) files for examples as to how one might configure for a different bundler.

## Bundler Performance Optimizations

**Please note**: this section is entirely _optional_, it is only for advanced users and not necessary to use this library.

Using `physijs-webpack` may bulk up your bundle by quite a bit, primarily because `physijs` depends on `ammo.js`, which is roughly ~1.2MB (minified) alone.
While caching of repeated builds will certainly speed up performance by quite a bit, we can use some other optimizations to further improve your bundler's performance.

### noParse

One of these is the `noParse` config option ([webpack](https://webpack.js.org/configuration/module/#modulenoparse)|[browserify](https://github.com/browserify/browserify#usage)) that instructs the bundler to skip parsing of certain files and is usually used as an optimization for large files (like `ammo.js`!).

With `webpack`, this optimization might look like:

```javascript
// ...
module.exports = {
// ...
module: {
// don't parse ammo
noParse: require.resolve('physijs-webpack/physijs/vendor/ammo.js')
},
// ...
}
```

And with the [`browserify` API](https://github.com/browserify/browserify#browserifyfiles--opts), this optimization might look like:

```javascript
const browserify = require('browserify')
// ...

browserify({
// ...
// don't parse ammo
noParse: [require.resolve('physijs-webpack/physijs/vendor/ammo.js')],
// ...
})
```

### other optimizations

If you are looking to speed up your build even further, you may want to look into configuring `externals` ([webpack](https://webpack.js.org/configuration/externals/)|[browserify](https://github.com/browserify/browserify#bexternalfile)) (and possibly configuring `ignore`s ([webpack](https://webpack.js.org/plugins/ignore-plugin/)|[browserify](https://github.com/browserify/browserify#bignorefile))).

You may also want to apply these same bundler performance optimizations to `three` as well, as it is also a fairly large library.

Please send a PR if you identify any other performance optimizations that you think may be useful to others!

## Credits

Thanks to @silviopaganini for creating the [initial browserify version](https://github.com/silviopaganini/physijs-browserify)!
Expand Down

0 comments on commit f292580

Please sign in to comment.