update docs

README.md

@@ -7,17 +7,18 @@
 
 
 - [Use ES6 / ES2015 modules in Meteor today!](#use-es6--es2015-modules-in-meteor-today)
-  - [Benefits of this approach](#benefits-of-this-approach)
+  - [File extensions and universe:modules-entrypoint package](#file-extensions-and-universemodules-entrypoint-package)
+  - [Benefits of modules is Meteor](#benefits-of-modules-is-meteor)
 - [Installation](#installation)
 - [Usage](#usage)
   - [Complete app example](#complete-app-example)
   - [Basic usage](#basic-usage)
+  - [Loading file only on the client or server](#loading-file-only-on-the-client-or-server)
   - [Loading modules from packages](#loading-modules-from-packages)
-  - [Loading package-level variables](#user-content-loading-package-level-variables)
-  - [Loading from npm repository](#user-content-loading-from-npm-repository)
+  - [Loading some package exports](#loading-some-package-exports)
+  - [Loading from npm repository](#loading-from-npm-repository)
 - [SystemJS API](#systemjs-api)
   - [Setting nice module names](#setting-nice-module-names)
-  - [SystemJS packages](#systemjs-packages)
 - [Troubleshooting](#troubleshooting)
   - [Module XXX does not exist!](#module-xxx-does-not-exist)
 - [About](#about)
@@ -32,37 +33,46 @@
 
 You can read more about new JavaScript modules and see some examples at [JSModules.io](http://jsmodules.io) or [2ality](http://www.2ality.com/2014/09/es6-modules-final.html)
 
-**This package add new file extensions:** `*.import.js` and `*.import.jsx`.  
-These files will be bundled with your Meteor app, but won't get executed until you request them.
+Files written as modules will be bundled with your Meteor app, but won't get executed until you request them.
 This is somewhat similar to `*.import.less` files, that you can include inside normal `*.less` files.
 
-All `*.import.js` files **have full ES6 support** provided by Meteor's Babel.js implementation.
-`*.import.jsx` files also have JSX/React support.
+All modules have the same ES6 support as core `ecmascript` package + support for `import`/`export` statements.
+`jsx` files have also JSX/React support.
 
 API is compatible with new ES6 modules spec.
 Under the hood [Babel.js](https://babeljs.io) and [SystemJS](https://github.com/systemjs/systemjs) take care of everything, so you can use modules today!
 
 *This package adds SystemJS to your project.*
 
-### Benefits of this approach
+### File extensions and universe:modules-entrypoint package
+
+This package use file extensions `*.import.js` and `*.import.jsx` for compatibility reasons.
+
+By default only files with `.import.js(x)` extension are bundled as modules, all other files are processed as usual.   
+
+If you want to use modules in all `*.js` files check out **[universe:modules-entrypoint](https://github.com/vazco/meteor-universe-modules-entrypoint)**. 
+
+*Entrypoint* package parse all `*.js` files and provide one entry point file to run your application.
+Check [docs](https://github.com/vazco/meteor-universe-modules-entrypoint) for more info how to setup modules in this mode. 
+
+### Benefits of modules is Meteor
 
 Universe Modules allows you to write your code in modular way, something that Meteor lacks by default.
 You also don't have to worry so much about file loading order.
 
 This is especially useful when working with React - creating lots of new components don't have to pollute global namespace.
 Also code is much simpler to reason about, and syntax is more friendly.
 
-Code you write inside `*.import.js(x)` is compiled using Babel, so **you can also use other ES2015 features!** 
 
 ## Installation
 
 Just add this package to your app:
 
     meteor add universe:modules
 
-### Upgrading from 0.4 to 0.5
+#### Upgrading from 0.4 to 0.5 and higher
 
-Version 0.5 introduces some breaking changes, and most probably your app won't work out of the box.
+Version 0.5 introduced some breaking changes, and most probably your app won't work out of the box.
 For more details check CHANGELOG.md
 
 All paths need to be either absolute (starting with `/`, `{}/`, `{author:package}` etc.) or relative (starting with `./`, `../` etc.)
@@ -88,9 +98,14 @@ Instead, index module will be loaded by default if you pass only package name in
 
 ### Complete app example
 
-If you want to see it in action, see our todo example app:
+New example app is in progress, until then you can check out simple game that is using modules - [source code](https://github.com/MacRusher/ColorWars)
+
+##### Outdated examples
 
-- Source code: https://github.com/vazco/demo_modules (note: this example is little outdated and will be updated soon)
+This examples use little outdated (<0.5) version of modules, until updated it could work as a simple reference.
+Just remember that right now paths to modules need to be either absolute or relative. Check upgrading guide above for more info.
+
+- Source code: https://github.com/vazco/demo_modules
 - Live demo: http://universe-modules-demo.meteor.com
 
 You can also check out great `meteor-react-example` app by [optilude](https://github.com/optilude).
@@ -140,12 +155,16 @@ This assumes that file `finalComponent.import.js` is inside main app directory.
 If you have it somewhere else you have to provide full path starting with meteor app directory,
 e.g. `/client/components/finalComponent`.
 
+Of course you can export anything, not only functions.
+When using `modules-entrypoint` package the `.import` part in filenames can be omitted.
+
 
 ### Loading file only on the client or server
 
 Because ES2015 specification won't allow you to write `import` statements inside a condition, you cannot import file selectively only on client or server.
 
-In some cases this could be useful, so we introduced syntax that will allow you to do it. Just add `@client` or `@server` suffix after module name.
+In some cases this could be useful, so we introduced syntax that will allow you to do it.
+Just add `@client` or `@server` suffix after module name.
 On selected platform this will behave like normal import, on the other platform import will return empty module, so every imported variable will be undefined.
 
 ### Loading modules from packages
@@ -154,15 +173,22 @@ To load files from packages prefix path with full package name in brackets, e.g:
 
     import foo from '{author:package}'
 
-to load index file from package, or to load selected module:
+This will load `index.import.js(x)` file from package `author:package`.
+
+Of course package `author:package` must be using our modules.
+
+You can also load selected module inside package:
 
     import foo from '{author:package}/foo'
-
-This syntax was also introduced in Meteor 1.2 to allow importing less/stylus files between packages.
 
-Inside package paths are absolute to package root. To import from main package use `{}/foo` syntax. `{}` Selects main app.
+This will load `foo.import.js(x)` file from package `author:package`.
 
-If you wish you can inside package import modules from other packages (you need to have dependencies on them!)
+Inside package paths are absolute to package root.
+
+This syntax was also introduced in Meteor 1.2 to allow importing less/stylus files between packages.
+
+Inside package you can also import files from main app with `{}/foo` syntax. `{}` selects main app.
+If you wish you can also import modules from other packages (but you need to have dependencies on them!)
 
 ### Loading some package exports
 
@@ -174,12 +200,15 @@ import {UniCollection, UniUsers} from '{universe:collection}!exports'
 ```
 
 Remember that if you want to import from another package, you must have dependency on this package.
+These packages don't have to use `universe:modules` for this to work.
 
 ### Loading from npm repository
 
 There is extension for this package that adds a possibility of importing from npm repositories.
 [universe:modules-npm](https://atmospherejs.com/universe/modules-npm) / [Github repo](https://github.com/vazco/meteor-universe-modules-npm/)
 
+Internally it uses browserify, but it also take care of doubled dependencies which is very important when working with React.
+
 ## SystemJS API
 
 Full SystemJS API docs can be found [on their Github repo](https://github.com/systemjs/systemjs/blob/master/docs/system-api.md)
@@ -218,6 +247,7 @@ You also don't have to worry about this when using `import` inside `*.import.js`
 
 ### Roadmap
 
+- [x] Support `*.js` files 
 - [ ] Allow opt-in for other Babel modules (decorators etc) 
 - [ ] Support for lazy loading modules on the client instead of bundling them with main Meteor app
 - [ ] Full tests coverage