beefy
a local development server designed to work with browserify.
it:
- can live reload your browser when your code changes (if you want)
- works with whatever version of browserify or watchify; globally installed or
locally installed to
node_modules/
. - will spit compile errors out into the browser so you don't have that 1-2 seconds of cognitive dissonance and profound ennui that follows refreshing the page only to get a blank screen.
- will spit out a default
index.html
for missing routes so you don't need to even muck about with HTML to get started - serves up static files with grace and aplomb (and also appropriate mimetypes)
- is designed to fall away gracefully, as your project gets bigger.
- loves you, unconditionally
how do I get it?
npm install -g beefy
; and if you want to always have a browserify available
for beefy to use, npm install -g browserify
.
usage
$ cd directory/you/want/served
$ beefy path/to/thing/you/want/browserified.js [PORT] [-- browserify args]
what bundler does it use?
Beefy searches for bundlers in the following order:
- First, it checks your local project's node_modules for watchify.
- Then it checks locally for browserify.
- Failing that, it checks for a global watchify.
- Then falls back to a global browserify.
path/to/file.js
the path to the file you want browserified. can be just a normal node module.
you can also alias it: path/to/file.js:bundle.js
if you want -- so all requests
to bundle.js
will browserify path/to/file.js
. this is helpful for when you're
writing gh-pages
-style sites that already have an index.html, and expect the
bundle to be pregenerated and available at a certain path.
You may provide multiple entry points, if you desire!
--browserify command
--bundler command
use command
instead of browserify
or ./node_modules/.bin/browserify
.
in theory, you could even get this working with if you want
to use r.js
, but that would probably
be scary and bats would fly out of it. but it's there if you need it!r.js
with beefy, you'll need a config that can write the resulting bundle
to stdout, and you can run beefy with beefy :output-url.js --bundler r.js -- -o config.js
.
NB: This will not work in Windows.
--live
Enable live reloading. this'll start up a sideband server and an fs
watch on
the current working directory -- if you save a file, your browser will refresh.
if you're not using the generated index file, beefy has your back -- it'll still automatically inject the appropriate script tag.
<script src="/-/live-reload.js"></script>
--cwd dir
serve files as if running from dir
.
--debug=false
turn off browserify source map output. by default, beefy automatically inserts
-d
into the browserify args -- this turns that behavior off.
--open
automatically discover a port and open it using your default browser.
--index=path/to/file
Provide your own default index! This works great for single page apps,
as every URL on your site will be redirected to the same HTML file. Every
instance of {{entry}}
will be replaced with the entry point of your app.
api
var beefy = require('beefy')
, http = require('http')
var handler = beefy('entry.js')
http.createServer(handler).listen(8124)
Beefy defaults the cwd
to the directory of the file requiring it,
so it's easy to switch from CLI mode to building a server.
As your server grows, you may want to expand on the information you're giving beefy:
var beefy = require('beefy')
, http = require('http')
http.createServer(beefy({
entries: ['entry.js']
, cwd: __dirname
, live: true
, quiet: false
, bundlerFlags: ['-t', 'brfs']
, unhandled: on404
})).listen(8124)
function on404(req, resp) {
resp.writeHead(404, {})
resp.end('sorry folks!')
}
beefy(opts: BeefyOptions, ready: (err: Error) => void)
Create a request handler suitable for providing to http.createServer
.
Calls ready
once the appropriate bundler has been located. If ready
is not provided and a bundler isn't located, an error is thrown.
BeefyOptions
Beefy's options are a simple object, which may contain the following attributes:
cwd
: String. The base directory that beefy is serving. Defaults to the directory of the module that first required beefy.quiet
: Boolean. Whether or not to output request information to the console. Defaults to true.live
: Boolean. Whether to enable live reloading. Defaults to false.bundler
: null, String, or Function. If a string is given, beefy will attempt to run that string as a child process whenever the path is given. If a function is given, it is expected to accept a path and return an object comprised of{stdout: ReadableStream, stderr: ReadableStream}
. If not given, beefy will search for an appropriate bundler.bundlerFlags
: Flags to be passed to the bundler. Ignored ifbundler
is a function.entries
: String, Array, or Object. The canonical form is that of an object mapping URL pathnames to paths on disk relative tocwd
. If given as an array or string, entries will be mapped like so:index.js
will map/index.js
to<cwd>/index.js
.unhandled
: Function accepting req and resp. Called for 404s. If not given, a default 404 handler will be used.watchify
: defaults to true -- when true, beefy will prefer using watchify to browserify. If false, beefy will prefer browserify.
Beefy may accept, as a shorthand, beefy("file.js")
or beefy(["file.js"])
.
license
MIT