Browserify handbook

https://github.com/substack/browserify-handbook

by mambodog • 12 years ago

154 68 12 years ago

github.com

untog6• 12 years ago

I'm so very glad that Browserify exists. After living in RequireJS/Bower/etc. hell it really is a breath of fresh air.

voidfiles• 12 years ago

What problems did you run into while using RequireJS?

untog6• 12 years ago

I write with Node in the backend and JS on the front-end, so switching between CommonJS and RequireJS styles was a source of constant irritation (and let's face it, the RequireJS style is annoying). I tried using the CommonJS style in RequireJS but I could never get it to behave correctly.

Also, though I found bower useful I disliked having yet another package manager, yet another manifest and yet another install step included in my development workflow. Using npm for both server and client side modules has been a dream.

mikegioia• 12 years ago

I must say, there was a bit of a learning curve to Browserify. Now that I have it working I feel it's one of the best tools we have for front-end development.

I auditioned Component and RequireJS but both of those felt like a kludge. Browserify lets you do node style includes as well as compile your JS into separate bundles.

I wrote a very small structure and build system [1] for our front-end projects at work that uses Browserify / Gulp and can compile everything into separate modules. It uses nginx/apache for routing and since it's all HTML/CSS and compiled JS, it's lightning fast to deliver.

I think this guide is fantastic; we just need more things like this to lower the barrier to entry.

[1] https://github.com/TeachBoost/mishra

mateuszf2• 12 years ago

Anyone knows how to use bootstrap using commonjs/browserify? I don't want to use neither bower nor manual download / storing compiled bootstrap inside of project.

Kenan• 12 years ago

https://github.com/ForbesLindesay/twbs

mateuszf2• 12 years ago

Thank you very much!

BenjaminCoe• 12 years ago

I played with Browserify for the first time two weeks ago, building this app:

https://github.com/bcoe/npm-typeahead

Both the libraries that the app depended on (typeahead.js, and jquery) had been published to npm. I found it really straight-forward to setup an asset-pipeline using Browserify.

I'm a big fan :)

eranation3• 12 years ago

Anyone has luck with Browserify + TypeScript while keeping source maps pointing correctly back to TypeScript? (or any other JS transpiler)

cnp6• 12 years ago

What problems are you having exactly? Sourcemaps work great over here.

eranation3• 12 years ago

Here is the SO question I created for this issue with more details: http://stackoverflow.com/questions/23453160/keep-original-ty...

chamakits2• 12 years ago

I recently also started using Browserify with Typescript (along with tds to get some ambient files for popular libraries). I got it to work after tryping countless of hacky things.

What I ended up with was a seperate ts file that is just the module, and variables I export. See this:

http://jsbin.com/gidaneja/1/edit?js,output

So I do a "<reference path=" for the ambient paths of variables. Then I declare require so I can call browserify's require. Then I create a function with it's return type being used based on ambient files I included. Then I create an export variable and call the function to set it's value. Then I can use that variable without a problem everywhere.

I tried using the whole "import lodash = require('lodash.d.ts') thing and other variations and failed miserably. This is the only thing I got to work, and its working perfectly. Email me (email should be on my profile) if it's not clear, I know the explanation was kinda vague.

eranation3• 12 years ago

Awesome, thanks! will try it :)

Kiro• 12 years ago

I keep wondering what kind of applications people build where they have so many dependencies that they need something like Browserify. Am I the only one doing the 1. find CDN link 2. add script tag to body?

quarterto• 12 years ago

It's not just dependencies, it's structuring your own code as well. My codebase at work has ~200 internal module files, wired together with Browserify.

cnp6• 12 years ago

If you've ever worked in other languages that have an "import" function, you'll understand. Having to manually manage script tags, order of operations, rapidly growing 2000 loc script.js files, etc, can only lead you astray, introduce errors, and make debugging your code hell.

// App Controller

var AppModel = require('./models/AppModel');

var NavView = require('./views/NavView');

var HomeView = require('./views/HomeView');

// Do stuff

You can immediately know whats going on inside of your class or module simply by looking at the imports, the LOC is greatly reduced, and refactoring, via imports, makes your code about a thousand times more maintainable.

sync• 12 years ago

You mean like the "import" function in ES6?

dugmartin2• 12 years ago

I've been working on a front-end project in CoffeeScript using React and running Browserify via Gulp has been both a great time saver and has helped keep my project organized.

One tip I can give is that I ended up organizing each of my React components and mixins as a module in their own folders and files and my gulpfile adds the parent source path to the NODE_PATH environment variable. By adding the coffeeify transform and .coffee extension to the browserify gulp task I can just do this in my code:

    SomeComponent = require 'react-components/some-component'
    SomeMixin = require 'react-mixins/some-mixin'

No need to worry about relative paths or if it is CoffeeScript code or plain Javascript.

The other tip is to NOT require react within your browserfied code. Just load it as a script tag before your browserfied code and use window.React to get a reference.

sanderjd2• 12 years ago

Huh, care to expand on why you shouldn't `require` React? Just doesn't play nicely with Browserify?

untog6• 12 years ago

Because writing the require statement in every file is annoying, probably. I do something similar with jQuery - I require it in my bootstrap file, then do

    window.$ = jQuery

Global variables are a bad thing until they're a really convenient thing.

dugmartin2• 12 years ago

Yeah, sorry I wasn't clear why. The first is that React is pretty large so it slows down the watch/build cycle enough that there is a lag and second is that in production React can be loaded via a cdn. Since everything is bundled into one file with Browserify its better for the end user download speed if you pull 3rd party libs out.

I also didn't give the main reason for using the NODE_PATH method. Browserify doesn't resolve duplicate relative paths so if you have a structure like this:

    /src
      main.js
      components/a.js
      components/foo/b.js
      components/foo/c.js

and a.js requires c.js via relative paths:

    require('./foo/c.js')

and b.js also requires c.js via

    require('./c.js')

then c.js is included twice in your bundled code since Browserify uses the pure string path as the key. If instead you put /src in your NODE_PATH you can do this in a.js:

    require('components/foo/c.js')

and this in b.js

    require('components/foo/c.js')

and c.js will only be bundled once since it has the same path.

kelkes• 12 years ago

Main problem is when npm modules are not up to date. This is the reason i still have to use bower but debowerify helps a lot...

cwmma2• 12 years ago

require('name/repo#commitish') works with npm/browserify, considering that bower uses git repos you can require them that way.

ghostwords2• 12 years ago

Here is a browserify/watchify-based script I use for building a browser extension's JS bundles: https://github.com/ghostwords/chameleon/blob/master/tools/bu...

The script

- Creates multiple bundles, with Underscore template precompilation and source code minification (for some bundles).

- Converts every vendor library into shared modules (you don't want Underscore included in every bundle that needs it, but you want to be able to require() it in those bundles).

- Monitors your files for changes and recompiles bundles as needed when run with --watch.

I found working with Browserify a pleasant experience after RequireJS and r.js (its build tool).

hamburglar4• 12 years ago

Browserify is awesome, and I look forward to reading this guide in detail, but I must say I'm disappointed about the "avoiding ../../../.." section. I've never seen a solution to this problem that wasn't a hack. The doc is correct that using NODE_PATH makes your app "tightly coupled to a runtime environment configuration", but what it fails to note is that the other two solutions offered are just as ugly. Checking code into a directory managed by npm is simply asinine, and putting symlinks in there is just as "coupled to the runtime environment configuration" as the NODE_PATH solution. What is really needed is a reasonable (and supported) method of programmatically managing the node search path.

Why the node community is so stubborn about this point is a mystery to me and it makes me wary of node in general, because who wants to be locked into an environment where such an obvious pain point is ignored due to stubbornness?

cshenoy• 12 years ago

Do you have a better solution in mind? I'm actually wondering because I've thought of workarounds but they'd all be hacks like the ones in the handbook. I'd imagine other node developers are in the same boat (not due to stubbornness) otherwise we would've seen something by now.

Basically, what would be your ideal solution?

indirectlylit• 12 years ago

There are good discussions of this issue at https://gist.github.com/branneman/8048520/ and http://stackoverflow.com/questions/10860244/

My preference is to add structure with file names instead of directories: app.foo.bar.js instead of app/foo/bar.js

hamburglar4• 12 years ago

The obvious thing is what most other environments do: there's a system default search path, you can override that using an environment var, and then once your runtime is up, you can further override it via an API at runtime. E.g. with ruby there is an array called $: which is the current search path in array-of-strings form, and manipulating that array affects the module loading behavior. This provides a lot of flexibility in how apps find their modules. Node provides basically none.

Dictating that the only way to control dependency-loading is by manipulating the filesystem is really braindead.

wetmore• 12 years ago

I like the approach found here: https://github.com/DSKrepps/requireFrom

It doesn't work with browserify but it wouldn't be too hard to write a transform that does it.

mambodog• 12 years ago

I think it is acceptable at the application level to use NODE_PATH, provided you have a normal node_modules directory at the root of your app for npm modules, and are strict about pulling out any generic modules to that location (and ideally, to npm), and that they never reference your private modules.

Most substantial applications are going to have at least some small amount of internal coupling around their business logic and configuration, and as long as you limit knowledge of the custom NODE_PATH to that code you should be alright.

eg. you could have

    # assuming git, find repo root
    APP_ROOT=$(git rev-parse --show-toplevel)

    # /app is for private, checked in modules
    # `npm root` will find your root node_modules dir 
    NODE_PATH="$APP_ROOT/app:`npm root`"

and then all of your app-coupled private modules can live in /app, and get checked into your git repo, while all the dependencies would be referenced in the package.json at the root of your app, and installed to node_modules (eg. npm root for the app package).

I should emphasise that taking this approach requires quite a bit of developer responsibility to avoid coupling between modules when it's not required, and it's really overkill for small apps.

oulipo2• 12 years ago

I use browserify and I'm happy with it, but I have one question that perhaps someone can answer :

how can I develop a library with different modules, say lib/module/func, lib/module/other, and compile the library as static, then import it in another project and be able to require lib/module/other from the other project using only the compiled lib?

ghostwords2• 12 years ago

I believe you are looking for https://github.com/substack/node-browserify#external-require... and/or https://github.com/substack/node-browserify#multiple-bundles

mattdesl3• 12 years ago

Why compile the module? Browserify lets you use a module's CommonJS export, so the only build step is at the application level. Utils etc should not be built except for non-node users (umd).

oulipo2• 12 years ago

It would allow to distribute and package the library simply, rather than having to checkout the library in the other projects dir and have weird require(../../lib/module/other)

lobster_johnson2• 12 years ago

Just package the library as an NPM module -- that's the reason why Browserify exists, after all -- then reference it in the other project's package.json file. If it's private (not open source), you can still reference it via Git or a private NPM repository.

flog• 12 years ago

A printable version: https://gitprint.com/substack/browserify-handbook

rming• 12 years ago

Wow, what a great app. So simple and easy to use. Love it!

bkurtz13• 12 years ago

I came across and played with beefy[1] today. Has anyone here integrated it into their workflow?

[1] http://didact.us/beefy/

mattdesl3• 12 years ago

I use beefy for almost all my modules, demos, and protoypes. For websites, I usually go with gulp watch since I need LESS anyways.

DEADB17• 12 years ago

After using browserify for a while now, I recently came across webpack (http://webpack.github.io/docs/what-is-webpack.html) which I'm finding more convenient and as efficient.

Advantages:

- requiring and pre-prosessing files other than js is easier

- ability to use AMD modules if you have to

- code splitting

jaekwon• 12 years ago

Here's a simpler alternative if you don't want all the bells and whistles of Browserify

https://github.com/jaekwon/demodule

Browserify handbook

Related Stories