Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Touched up the documentation. #11

Merged
merged 4 commits into from

2 participants

@jaap3

I've touched up the documentation. First I just wanted to correct a small issue, then I wanted to add an example... in the end I just went through everything and did a bunch of cleanup.

Webmake is actually the first node -> browser module I got to work (tried two others and gave up in frustration yesterday). So thank you!

jaap3 added some commits
@jaap3 jaap3 Wanted to fix a small error in the documentation (sourceMap was calle…
…d sourcemap), then added an example of using webmake programatically, ended up touching up all the documentation.
6b01f5d
@jaap3 jaap3 Minor edits
be39f20
@jaap3

You can actually see and read the resulting file here https://github.com/jaap3/modules-webmake/blob/patch-1/README.md

@medikoo medikoo merged commit 27bb7b5 into from
@medikoo
Owner

@jaap3 It looks really good! I think it's a right moment for opening some Contributor's Hall of Fame section. Thanks!

Main reason I wrote Webmake was also that I couldn't find solution that would work well, and now I'm happy to hear that others find Webmake as one that finally works ;)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on May 7, 2012
  1. @jaap3

    Wanted to fix a small error in the documentation (sourceMap was calle…

    jaap3 authored
    …d sourcemap), then added an example of using webmake programatically, ended up touching up all the documentation.
  2. @jaap3

    Minor edits

    jaap3 authored
  3. @jaap3

    Fixed bad indent in.

    jaap3 authored
  4. @jaap3

    Nitpicks

    jaap3 authored
This page is out of date. Refresh to see the latest.
Showing with 98 additions and 46 deletions.
  1. +98 −46 README.md
View
144 README.md
@@ -1,13 +1,18 @@
-# modules-webmake - Bundle CommonJS/Node.js modules for web browser
+# modules-webmake
-It's about organizing JavaScript code for browser same way as we do for Node.js.
+_Bundle CommonJS/Node.js modules for web browsers._
-If you're not that familiar with it, see plain [specification](http://www.commonjs.org/specs/modules/1.0/) and slides from Warsaw's MeetJS meetup presentation:
-__[JavaScript Modules Done Right](http://www.slideshare.net/medikoo/javascript-modules-done-right)__
+Webmake allows you to organize JavaScript code for the browser the same way
+as you would for Node.js.
-## How it works?
+For a more in depth look into JavaScript modules and the reason for _webmake_,
+see the slides from my presentation at Warsaw's MeetJS:
-Let's say in package named _foo_ we have following individual file modules:
+**[JavaScript Modules Done Right][slides]**
+
+## How does it works?
+
+Let's say in package named _foo_ you have following individual module files:
_add.js_
@@ -36,11 +41,11 @@ var a = 1;
inc(a); // 2
```
-Let's pack _program.js_ with all it's dependencies for browser:
+Let's pack _program.js_ with all it's dependencies so it will work in browsers:
- $ webmake program.js build.js
+ $ webmake program.js build.js
-In result we have generated _build.js_ that looks like:
+The generated file _build.js_ now contains the following:
```javascript
(function (modules) {
@@ -70,82 +75,129 @@ In result we have generated _build.js_ that looks like:
("foo/program");
```
-When loaded in browser, immediately _program.js_ module is executed
+When loaded in browser, _program.js_ is immediately executed.
## Installation
- $ npm install -g webmake
+ $ npm install -g webmake
## Usage
### From the shell:
- $ webmake <input> <output>
+ $ webmake <input> <output>
+
+_input_ is the path to the initial module that should be executed when
+script is loaded.
+_output_ is the path to which the bundled browser ready code is written.
-_input_ is path to your initial module that would be executed when script is loaded, and _output_ is path where browser ready file should land.
+Additionally you may output modules with [source maps][], for easier debugging.
-Additionally you may output modules as [source maps](http://pmuellr.blogspot.com/2011/11/debugging-concatenated-javascript-files.html).
+ $ webmake --sourcemap <input> <output>
- $ webmake --sourcemap path/to/program-module.js path/to/output.js
+Source maps work very well in WebKit and Chrome's web inspector. Firefox's Firebug
+however has some [issues][firebug issue].
-It works very well in webkit web inspector but it's [not that well supported by firefox's firebug](http://code.google.com/p/fbug/issues/detail?id=2198)
+### Programmatically
-### Programmatically:
+Webmake can also be used programmatically. For example to create a server that
+builds a fresh bundle on each request.
```javascript
-var webmake = require('webmake');
-webmake('/path/to/program-module.js', function (err, source) {
- if (err) {
- // handle eventual error
- }
- // Do whatever you need with generated source
+var http = require('http'),
+ webmake = require('webmake'),
+ server;
+
+server = http.createServer(function (request, response) {
+ webmake('program.js', {'sourceMap': true}, function (err, src) {
+ if (err) {
+ response.writeHead(500, {'Content-Type': 'text/plain'});
+ response.end(err);
+ } else {
+ response.writeHead(200, {'Content-Type': 'application/javascript'});
+ response.end(src);
+ }
+ });
});
-````
-#### Options:
+server.listen(8000);
+````
-You can pass additional options:
+#### Options
```javascript
webmake(inputPath[, options], callback);
```
##### output `string`
+
Path of output file, if you want _webmake_ to create one
##### include `string|Array`
-Additional module(s) that need to be included (but due specific reasons can't be picked by parser).
-##### sourcemap `boolean`
-Generate [source maps](http://pmuellr.blogspot.com/2011/11/debugging-concatenated-javascript-files.html).
+Additional module(s) that need to be included (but due specific reasons can't
+be picked by parser).
+
+##### sourceMap `boolean`
+
+Include [source maps][].
## Limitations
-Application calculates dependencies via static analysis of source code (with help of [find-requires](https://github.com/medikoo/find-requires) module)
+The application calculates dependencies via static analysis of source code
+(with the help of the [find-requires][] module). So in some edge cases
+not all require calls can be found.
-### Supported are relative paths and outer packages paths
+Only relative paths and outer packages paths supported, so this will work:
-This will work:
+```javascript
+require('./module-in-same-folder');
+require('./module/path/deeper');
+require('./some/very/very/very/long' +
+'/module/path');
+require('../../module-path-up'); // unless it goes out of package scope
+require('other-package');
+require('other-package/lib/some-module');
+```
+
+But this won't work:
- require('./module-in-same-folder');
- require('./module/path/deeper');
- require('./some/very/very/very/long' +
- '/module/path');
- require('../../module-path-up'); // unless it doesn't go out of current package scope
- require('other-package');
- require('other-package/lib/some-module);
+```javascript
+require('/Users/foo/projects/awesome/my-module');
+```
-### Absolute paths won't work (TODO)
+## Known issues
- require('/Users/foo/projects/awesome/my-module');
+ * Absolute file paths in require calls don't work
+ * Different versions of same package will collide
-### Different versions of same package will colide (TODO)
+ Let's say, package A uses version 0.2 of package C and package B uses
+ version 0.3 of the same package. If both package A and B are required,
+ package B will most likely end up buggy.
-Let's say, required package A uses version 0.2 of package C and required package B uses version 0.3 of same package, it will most likely crash. Currently webmake will take C in version that was called first and will give it to both A and B.
+ This is because webmake will only bundle the version that was called
+ first. So in this case package B will end up with version 0.2 instead
+ of 0.3.
## Tests
-Before running tests make sure you've installed project with dev dependencies
-`npm install --dev`
+Before running tests make sure you've installed project with dev dependencies:
+
+ `npm install --dev`
+ $ npm test
+
+[slides]:
+ http://www.slideshare.net/medikoo/javascript-modules-done-right
+ 'JavaScript Modules Done Right on SlideShare'
+
+[source maps]:
+ http://pmuellr.blogspot.com/2011/11/debugging-concatenated-javascript-files.html
+ 'Debugging concatenated JavaScript files'
+
+[firebug issue]:
+ http://code.google.com/p/fbug/issues/detail?id=2198
+ 'Issue 2198: @sourceURL doesn't work in eval() in some cases'
- $ npm test
+[find-requires]:
+ https://github.com/medikoo/find-requires
+ 'find-requires: Find all require() calls'
Something went wrong with that request. Please try again.