modules.md

+# Modules
+
+## Using modules
+
+At the moment sweet.js supports a primitive form of module support with the `--module` flag. This flag concatenates its arguments together, loads any macros it finds, and makes those macros available to the file being compiled. 
+
+For example, if you have a file `macros.js` that defines the `m` macro:
+
+```javascript
+// macros.js
+
+macro m { /* ... */ }
+export m;
+```
+
+and `my_sweet_code.js` uses `m`:
+
+```js
+// my_sweet_code.js
+
+m 42
+```
+
+You would compile this with:
+
+    $ sjs --module ./macros.js  my_sweet_code.js 
+
+Note that modules must use the `export` keyword. This allows modules to define "private" macros that are not visible to the main code.
+
+The `--module` flag uses the node path to look up the module file so you can publish and use macro modules on npm. Checkout [lambda-chop](https://github.com/natefaubion/lambda-chop) for an example of this.
+
+## Limitations
+
+All module files passed to `--module` are concatenated together before being loaded. This means that there is a potential for macros to clash if you try to define the same macro name in two different files. Though there are cases where you might want this behavior, see the discussion [here](https://github.com/mozilla/sweet.js/issues/145).
+
+The biggest limitation with the current approach is that you can't arbitrarily interleave importing compile-time values (macros) and run-time values (functions). This will eventually be handled with support for "proper" modules (issue #43).
+