Upgrade your app from requireJS AMD to commonJS module format via an automated refactor step in order to browserify it.
Discovered 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
where it can be browserified immediately, for all others it should get you at least 90% there.
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.
shim.js is incompatible with the newest browserify and browserify-shim. Therefore it should only be
used as guideline to add the proper config to the
package.json as explained
- converts all modules of a given project from requirejs AMD to commonjs (nodejs and thus browserify compatible)
- 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
- generates proper
build.jsscript which generated the browserify bundle
- shims commonJS incompatible modules like
- cannot resolve template files (maybe a good time to switch to precompiled templates) ;)
directoryFilternot yet supported
Additionally to the below documentation you will find the step by step examples helpful.
Table of Contents generated with DocToc
- preparing requirejs config
- dry run
- preparing a custom refactor config
- running browserify-ftw
- running the generated build script
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 libraries that are available on npm, (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:
Set all paths that should become global requires to
null. You should do this for or modules that you will be
paths:// we'll use the underscore node_module'underscore': null
define(['underscore'], ...is found
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
deps declarations will be ignored.
requireconfigshim:jquery: exports: '$'// assuming foo is not published as an npm module, but commonJS compatiblefoo: exports: nullpaths:'jquery': 'modules/jquery''foo': 'modules/foo';
Note: When shimming modules, the generated
build.js will require browserify-shim,
so make sure to install it:
npm install -S browserify-shim
References not included in
paths or set to
will be assumed to be in the or relative to the requirejs
paths:// omitting below line has the same effect since then 'mymodule' is as well'mymodule':
define(['mymodule'], ...is found in another module that is also in the requirejs config path
define(['mymodule'], ...is found in another module that is in a folder one level below the requirejs config path
'myothermodule'is not mentioned in
pathsit is considered
requirestatements are equivalent to the ones generated for
'lib/mylib'will be assumed to be at
'./lib/mylib'(relative to requirejs config path)
You can try a dry run via
browserify-ftw -r require-config.js -e ./entry.js, which will use a default refactor config with
Update the following file to match the style of your project and save it next to the
require-config.js (i.e. as
moduleexports =quote : '\'' // '\'' or '"'style : 'var' // 'var', 'comma', 'comma-first'indent : 2 // the tab size used in your projectdirectoryFilter : null // not supported yetfileFilter : '.js' // the extension of the file to upgradedryrun : true // true|false if true no changes will be written to upgraded files;
browserify-ftw has a very simple command line interface. Usage is available via
➜ browserify-ftw.jsOptions:-r, --requirejs path to requirejs-config.js file [required]-c, --config path to config to be used
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 -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 . 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
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.
At this point should be ready to run your application.
For more details consult the step by step examples.