1 | # disc ![gittip: hughsk](http://img.shields.io/gittip/hughsk.svg) ![npm](http://img.shields.io/npm/dm/disc.svg) ![stable](http://img.shields.io/badge/stability-stable-green.svg) #
|
2 |
|
3 | Disc is a tool for analyzing the module tree of
|
4 | [browserify](http://browserify.org) project bundles. It's especially handy
|
5 | for catching large and/or duplicate modules which might be either bloating up
|
6 | your bundle or slowing down the build process.
|
7 |
|
8 | The demo included on disc's [github page](http://hughsk.github.io/disc)
|
9 | is the end result of running the tool on browserify's own code base.
|
10 |
|
11 | ## Installation ##
|
12 |
|
13 | Disc lives on [npm](http://npmjs.org/package/npm), so if you haven't already
|
14 | make sure you have [node](http://nodejs.org/) installed on your machine first.
|
15 |
|
16 | Installing should then be as easy as:
|
17 |
|
18 | ``` bash
|
19 | sudo npm install -g disc
|
20 | ```
|
21 |
|
22 | ## Command-Line Interface ##
|
23 |
|
24 | ***Note:*** *you'll need to build your bundle with the `--full-paths` flag
|
25 | for disc to do its thing.*
|
26 |
|
27 | ``` bash
|
28 | discify [bundle(s)...] {options}
|
29 |
|
30 | Options:
|
31 | -h, --help Displays these instructions.
|
32 | -o, --output Output path of the bundle. Defaults to stdout.
|
33 | -O, --open Opens disc in a new browser window automatically
|
34 | -m, --mode the default file scale mode to display: should be
|
35 | either "count" or "size". Default: size
|
36 | ```
|
37 |
|
38 | When you install disc globally, you the `discify` command-line tool is made
|
39 | available as the quickest means of checking out your bundle. As of disc v1.0.0,
|
40 | this tool takes any bundled browserify script as input and spits out a
|
41 | standalone HTML page as output.
|
42 |
|
43 | For example:
|
44 |
|
45 | ``` bash
|
46 | browserify --full-paths index.js > bundle.js
|
47 | discify bundle.js > disc.html
|
48 | open disc.html
|
49 | ```
|
50 |
|
51 | You can easily chain this file into another command, or use the `--open`
|
52 | flag to open disc in your browser automatically:
|
53 |
|
54 | ``` bash
|
55 | browserify --full-paths index.js | discify --open
|
56 | ```
|
57 |
|
58 | ## Module API ##
|
59 |
|
60 | ***Note:*** *you'll need to build your bundle with the `fullPaths` option
|
61 | for disc to do its thing.*
|
62 |
|
63 | ### `require('disc')(opts)` ###
|
64 |
|
65 | Creates a through stream that you can pipe a bundle into, and get an HTML file
|
66 | in return – much like you would expect when working with the command-line tool.
|
67 |
|
68 | So to perform the above example with Node instead of Bash:
|
69 |
|
70 | ``` javascript
|
71 | var browserify = require('browserify')
|
72 | var open = require('opener')
|
73 | var disc = require('disc')
|
74 | var fs = require('fs')
|
75 |
|
76 | var input = __dirname + '/index.js'
|
77 | var output = __dirname + '/disc.html'
|
78 |
|
79 | var bundler = browserify(input, {
|
80 | fullPaths: true
|
81 | })
|
82 |
|
83 | bundler.bundle()
|
84 | .pipe(disc())
|
85 | .pipe(fs.createWriteStream(output))
|
86 | .once('close', function() {
|
87 | open(output)
|
88 | })
|
89 | ```
|
90 |
|
91 | This method takes the following options:
|
92 |
|
93 | * `header`: HTML to include above the visualisation. Used internally to render
|
94 | the "Fork me on GitHub" ribbon.
|
95 | * `footer`: HTML to include beneath the visualisation. Used internally for the
|
96 | description on the demo page.
|
97 | * `mode`: the default file scale mode to display: one of either `"count"` or
|
98 | `"size"`, defaulting to `"size"`.
|
99 |
|
100 | ### `disc.bundle(bundles, [opts], callback)` ###
|
101 |
|
102 | A callback-style interface for disc: takes an array of `bundles` (note: the
|
103 | file contents and not the file names), calling `callback(err, html)` with
|
104 | either an error or the resulting standalone HTML file as arguments.
|
105 |
|
106 | This currently mirrors how disc is currently implemented, but the stream API is
|
107 | a little more convenient to work with.
|
108 |
|
109 | ### `disc.json(bundles, callback)` ###
|
110 |
|
111 | Takes an array of bundle contents (as strings, or Buffers), and gathers the
|
112 | required data - calling `callback(err, json)` with either an error or the
|
113 | results.
|
114 |
|
115 | ## Palettes ##
|
116 |
|
117 | You can switch between multiple color palettes, most of which serve to highlight
|
118 | specific features of your bundle:
|
119 |
|
120 | ### Structure Highlights ###
|
121 |
|
122 | ![Structure Highlights](http://i.imgur.com/LO6Gio3.png)
|
123 |
|
124 | Highlights `node_modules` directories as green and `lib` directories as orange.
|
125 | This makes it easier to scan for "kitchen sink" modules or modules with lots of
|
126 | dependencies.
|
127 |
|
128 | ### File Types ###
|
129 |
|
130 | ![File Types](http://i.imgur.com/A8zDrbN.png)
|
131 |
|
132 | Highlights each file type (e.g. `.js`, `.css`, etc.) a different color. Helpful
|
133 | for tracking down code generated from a transform that's bloating up your bundle
|
134 | more than expected.
|
135 |
|
136 | ### Browserify Core ###
|
137 |
|
138 | ![Browserify Core](http://i.imgur.com/AtiKgwR.png)
|
139 |
|
140 | Highlights the automatically included and/or inserted modules that come courtesy
|
141 | of browserify in red. Makes it easy to quantify just how much space in your
|
142 | bundle is the result of shimming node's core functionality.
|
143 |
|
144 | ### Original/Pastel ###
|
145 |
|
146 | Nothing particularly special about these palettes – colored for legibility and
|
147 | aesthetics respectively.
|