Module / Package Refactor

[dcramer]

Goals

• Support browserify, webpack, bower, and Sentry's CDN (which means native bundled distribution)
• Break raven.js into a more modular system, where the ideal installation doesnt use our CDN, but rather uses require() technologies
• Combine raven-node and raven-js codebases and npm package
  • package.json can specify a 'browser' attribute to override this for npm
• Get the codebase into a position for future code reuse between the two projects

Proposal

API

The primary target here is module-based usage, so the following should work:

var Raven = require('raven');

Raven.config().install()

Both the node.js client and the javascript client should expose the same APIs. That is, they should expose the spec from Sentry with identical arguments (to the best of their ability).

Code Exposure

Internally (via the module system) we want to expose a great deal of Raven. If we can, all of it. That said, 'raven' itself would only export the public namespaces, and you'd have to include other module(s) to get access to those.

Plugins

Modeled after webpack, instead of straight up patching, each plugin would have a load/unload hook responsible for it's behavior:

var ravenjQ = require('raven/plugins/jquery');

Raven.config({
    plugins: [new ravenjQ()]
});

Alternatively we could namespace builtin plugins:

Raven.config({
    plugins: [new Raven.plugins.jQuery()]
});

See #282

Bundling

We need to determine how best to bundle things with the umd wrapper. There are things like grunt-umd to aid with this.

See also: https://github.com/umdjs/umd/blob/ce6c20e318e58cd301ee929135cf651b02392c08/returnExports.js

This will still need a build task, but the primary resource for this is the Sentry CDN, so it's possible we can move the dist/ out of the codebase.

The raven.js bundle would expose the identical namespace as 'raven'. That is, only the public API and none of the others.

Notes

• raven-node isn't very used
• code reuse is the lowest priority, the goal is simply a better experience for end-users

[matthewwithanm]

👍 to putting each plugin in its own module. The second option (Raven.plugins.jQuery) would mean they'd always be included in browser builds—even when you don't want them.

Also, if you already plan on using webpack, it can target UMD.

[benvinegar]

Echoing @matthewwithanm – 👍 to having each plugin in its own module.

[bendrucker]

Browserify can also build for UMD. It has the advantage of being able to expose build configure via package.json that parent packages can consume. Webpack has some very compelling features for building browser apps but I'm still very wedded to browserify since I publish a ton of modules.

For actually generating these UMD builds and getting the ./dist dir out of master, check out https://github.com/bendrucker/publicist

It's very much geared towards my style right now but I'd be happy to make it more configurable.

[elicwhite]

👍

[danse]

While refactoring, keep in mind the possibility of offline use, see #279

[mattrobenolt]

This has been done as of 2.0. 🍰

[mattrobenolt]

I'm going to open a separate ticket regarding raven-node possibly merging in since that's a separate topic and not sure yet if we still think that's a good idea or not.