Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

updating usage and adapting readme to latest api

  • Loading branch information...
commit 84c6ad6f6a0e3c06ac07a7ef1c91c4be5632b07e 1 parent acb5197
@thlorenz authored
Showing with 83 additions and 25 deletions.
  1. +81 −23 README.md
  2. +2 −2 bin/browserify-ftw.js
View
104 README.md
@@ -1,18 +1,18 @@
-# browserify-ftw [![build status](https://secure.travis-ci.org/thlorenz/browserify-ftw.png)](http://travis-ci.org/thlorenz/browserify-ftw)
+# browserify-ftw [![build status](https://secure.travis-ci.org/thlorenz/browserify-ftw.png)](http://next.travis-ci.org/thlorenz/browserify-ftw)
-Discovered [browserify](https://github.com/substack/node-browserify) too late and/or want to use common code on server
+Discovered [browserify](https://github.com/substack/node-browserify) too late and/or want to share code on server
and client?
Think you are stuck with requirejs AMD format for your client side code because there is no time to do the huge refactor?
-Don't you fret, browserify-ftw is here to help. For most projects it will be able to perform an upgrade it to a point
+Don't you fret, `browserify-ftw` is here to help. For most projects it will be able to perform an upgrade it to a point
where it can be browserified immediately, for all others it should get you at least 90% there.
## warning
-Running browserify-ftw on your code will rewrite the original files!
+Running browserify-ftw on your project **will rewrite the original files!**
-Therefore you should check all your files into source control and best create a new branch before running it in order to be able to revert to the original state in case something goes wrong.
+Therefore you should **check all your files into source control** and best create a new branch before running it in order to be able to revert to the original state in case something goes wrong.
## features
@@ -20,10 +20,11 @@ Therefore you should check all your files into source control and best create a
- safe since it parses the code and pulls information from AST (not just search/replace which is error prone)
- refactor config allows specifiying code style to use for generated code
- adds proper relative paths deduced from requirejs `main.js` config
+- generates proper `build.js` script which generated the browserify bundle
+- shims commonJS incompatible modules like `jquery`
## limitations
-- will not wrap your jquery, etc., for you, you'll need to do this by hand
- cannot resolve template files (maybe a good time to switch to [precompiled
templates](https://github.com/wycats/handlebars.js/#precompiling-templates)) ;)
- only `'var foo = require('foo');'` require style supported at this point
@@ -37,24 +38,25 @@ examples](https://github.com/thlorenz/browserify-ftw/tree/master/examples) helpf
## **Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)*
- [preparing requirejs config](#preparing-requirejs-config)
- - [global modules](#global-modules)
+ - [shimmed modules](#shimmed-modules)
+ - [npm modules](#npm-modules)
- [local modules](#local-modules)
- [dry run](#dry-run)
- [preparing a custom refactor config](#preparing-a-custom-refactor-config)
- [running browserify-ftw](#running-browserify-ftw)
-
+- [running the generated build script](#running-the-generated-build-script)
## preparing requirejs config
In order to improve browserify-ftw path resolution you should make some edits to the `paths` of your config inside your
requirejs config file.
-The most important step is to set all vendor librarie's (e.g., 'underscore') paths to `null` and afterwards install them
-as `node_modules`.
+The most important step is to set all vendor libraries that are available on [npm](https://npmjs.org/), (e.g.,
+'underscore') paths to `null` and afterwards install them as `node_modules` and to shim all others.
This preparation step should be performed as follows:
-### global modules
+### npm modules
Set all paths that should become global requires to `null`. You should do this for or modules that you will be
installing as `node_modules`.
@@ -71,9 +73,38 @@ installing as `node_modules`.
- generates `require('underscore')` wherever `define(['underscore'], ...` is found
+
+### shimmed modules
+
+In order to instruct `browserify-ftw` to shim a non-commonJS module, you need to include a shim config as part of your
+requirejs config if it isn't part of it already. It has the exact same format as the [requirejs shim
+config](http://requirejs.org/docs/api.html#config-shim). `deps` declarations will be ignored.
+
+**Example:**
+
+```js
+require.config({
+ shim: {
+ jquery: { exports: '$' },
+ // assuming foo is not published as an npm module, but commonJS compatible
+ foo: { exports: null }
+ },
+ paths: {
+ 'jquery': 'modules/jquery',
+ 'foo': 'modules/foo'
+ }
+});
+```
+
+**Note:** When shimming modules, the generated `build.js` will require [browserify-shim](https://github.com/thlorenz/browserify-shim),
+so make sure to install it:
+
+ npm install -S browserify-shim
+
### local modules
-References not included in `paths` or set to `undefined` will be assumed to be in the or relative to the requirejs config path
+References not included in `paths` or set to `undefined` will be assumed to be in the or relative to the requirejs
+config path.
**Example:**
@@ -85,17 +116,14 @@ References not included in `paths` or set to `undefined` will be assumed to be i
}
```
-- generates `require('./mymodule')` if `define(['mymodule'], ...` is found in another module that is also in the
- requirejs config path
-- generates `require('../mymodule')` if `define(['mymodule'], ...` is found in another module that is in a folder one
- level below the requirejs config path
-- since `'myothermodule'` is not mentioned in `paths` it is considered `undefined` and generated `require` statements
- are equivalent to the ones generated for `'mymodule'`
+- generates `require('./mymodule')` if `define(['mymodule'], ...` is found in another module that is also in the requirejs config path
+- generates `require('../mymodule')` if `define(['mymodule'], ...` is found in another module that is in a folder one level below the requirejs config path
+- since `'myothermodule'` is not mentioned in `paths` it is considered `undefined` and generated `require` statements are equivalent to the ones generated for `'mymodule'`
- dependency `'lib/mylib'` will be assumed to be at `'./lib/mylib'` (relative to requirejs config path)
## dry run
-You can try a dry run via `browserify require-config.js`, which will use a default refactor config with
+You can try a dry run via `browserify-ftw -r require-config.js -e ./entry.js`, which will use a default refactor config with
`dryrun` enabled.
## preparing a custom refactor config
@@ -116,16 +144,46 @@ module.exports = {
## running browserify-ftw
-browserify-ftw has a very simple command line interface:
+browserify-ftw has a very simple command line interface. Usage is available via `browserify-ftw`:
- browserify-ftw require-config [refactor-config]
+```sh
+➜ browserify-ftw.js
+Options:
+ -r, --requirejs path to requirejs-config.js file [required]
+ -c, --config path to config to be used for the refactoring [default: (built in refactor config)]
+ -b, --build path at which the generated browserify build script should be saved [default: "./build.js"]
+ -u, --bundle path at which the bundle generated by the browserify build should be saved [default: "./bundle.js"]
+ -e, --entry path at which the entry file for browserify will be located [required]
+```
Therefore after you prepared your `require-config.js` and a `refactor-config.js` the following will upgrade your project
while printing information about which files are being upgraded:
- browserify-ftw require-config.js refactor-config.js
+ browserify-ftw -r require-config.js -c refactor-config.js -e entry.js -b ./build.js -u ./build/bundle.js
It should end with "Successfully upgraded your project.".
-You can then use `valiquire .` (`npm -g install valiquire`) in order to verify that all `require` statements are correct.
+You can then use `valiquire .` in order to verify that all `require` statements are correct. Note that shimmed modules
+are not found by valiquire, so you can safely ignore warnings about those (i.e., jquery).
+
+If you don't have `valiquire` installed on your machine you can do so as follows:
+
+ npm install -g valiquire
+
+## running the generated build script
+
+Assuming you installed `browserify` local to your project and if you shimmed modules, also `browserify-shim`, you can run the generated build
+script in order to create the bundle file.
+
+You then need to change the sourced JavaScript file in your main HTML file e.g., index.html:
+
+**Example:**
+
+```html
+ <script src="library/js/build/bundle.js"></script>
+```
+
+At this point should be ready to run your application.
+
+For more details consult the [step by step examples](https://github.com/thlorenz/browserify-ftw/tree/master/examples).
View
4 bin/browserify-ftw.js
@@ -15,7 +15,7 @@ var util = require('util')
})
.options('c', {
alias : 'config'
- , describe : 'path to config to be used for the refactoring (https://github.com/thlorenz/browserify-ftw#preparing-a-custom-refactor-config)'
+ , describe : 'path to config to be used for the refactoring\n(https://github.com/thlorenz/browserify-ftw#preparing-a-custom-refactor-config)'
, default : path.join(__dirname, '../lib/refactor-config.js')
})
.options('b', {
@@ -30,7 +30,7 @@ var util = require('util')
})
.options('e', {
alias : 'entry'
- , describe : 'path at which will be the entry file for browserify'
+ , describe : 'path at which the entry file for browserify will be located'
, demand : true
})
.argv
Please sign in to comment.
Something went wrong with that request. Please try again.