browserify-example

This is a bare-bones, no-bullshit example of building a static JavaScript demo with budo and browserify.

The demo plays a synth sound with WebAudio and ToneJS.

Click here to see the live demo. The source is here.

Motivation

This template is for developers looking to tinker with JavaScript and npm modules, without getting caught up in Gulp/Grunt scripts, Webpack configuration, React/Angular/etc, and other complex modern practices. It tries to Keep It Simple, Stupid (KISS) without sacrificing the developer experience.

It is the workflow I use for prototyping with WebGL, canvas, and other APIs.

This demo uses ToneJS to interface with WebAudio, but this workflow supports many npm modules such as:

It uses budo for development and bundles to a static JavaScript file with browserify and uglify-js. It uses plain ES5 JavaScript (no transpilers) and CSS for styles, but I've included some instructions on ES2015 Transpiling.

Quick Start

You can clone this template for a quick start, or follow the Custom Setup to get this working from scratch.

First, make sure git, npm (v3 or higher), and node (v6 or higher) is installed. It's recommended to download the latest versions of these tools.

Now clone this repo and cd into it, then install the project's dependencies:

git clone https://github.com/mattdesl/browserify-example.git
cd browserify-example

# now install dependencies
npm install

💡 Also make sure you've fixed your npm permissions so you don't need to prefix everything with sudo

Now you can run the development server:

npm run start

It will start a development server on http://localhost:9966/. Now, when you save the ./index.js file, the browser page will reload. When you change ./style.css, the changes will be injected into the page.

You can publish a bundle.js file with the following command:

npm run build

Then, your static site is ready for a host like gh-pages, surge.sh or DropBox.

Custom Setup

The above will get you started immediately, but you might be left wondering how this project was set up. Here's how you can do it from scratch.

boilerplate

Create a new folder and move into it:

mkdir my-app
cd my-app

Stub a new package.json file, you can just use default answers if you like:

npm init

Now create an index.js file, something like this:

var url = require('url');
console.log(url.parse(window.location.href));

dependencies

Once you've got a package.json, run the following:

# install our client-side dependencies
npm install tone --save

# install some build/dev tools
npm install budo browserify uglify-js --save-dev

It might take a couple minutes to install. Once finished, it should update your package.json with the new dependencies.

scripts

Next, add a "scripts" field to your package.json file:

  "scripts": {
    "start": "budo index.js:bundle.js --live",
    "build": "browserify index.js | uglifyjs -cm > bundle.js"
  }

Now you can start the dev server:

npm run start

Open http://localhost:9966/ and you should see our console.log in the DevTools.

💡 You can also run budo from the command-line for quick development.

release

To release, you need an index.html and optional style.css. Make sure the HTML includes a <script> tag like so:

...
<body>
  <!-- used by dev/build script -->
  <script src="bundle.js"></script>
</body>

You can run the following to build a static JavaScript bundle, ready for gh-pages or your host of choice!

npm run build

If you plan to put your project on GitHub, you might want to include a .gitignore to avoid including any npm dependencies.

bower_components
node_modules
*.log
.DS_Store

ES2015 Transpiling

^{(this step is optional)}

Follow these steps to add ES2015 support, using Babel.

Install babelify (browserify transform for Babel) and a ES2015 language preset.

npm install babelify babel-core babel-preset-es2015 --save-dev

Add a .babelrc file to the directory:

{
  presets: [ "es2015" ]
}

From here, you have two options.

Option A: Package Transforms

Add a "browserify" field to your package.json configuration:

  ...
  "browserify": {
    "transform": [ "babelify" ]
  }

This is convenient, but not always the best course if you are building a module or library.

Option B: Explicit Transforms

Alternatively, you can explicitly list the transforms during the dev/build step. Use the --transform or -t flag:

  "scripts": {
    "start": "budo index.js:bundle.js --live -- -t babelify",
    "build": "browserify index.js -t babelify | uglifyjs -cm > bundle.js"
  }

💡 budo assumes all options after -- are for browserify.

License

MIT, see LICENSE.md for details.

wegiangb / browserify-example Goto Github PK