https://github.com/oncomouse/middleman-jspm
https://github.com/oncomouse/middleman-jspm
Last synced: over 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/oncomouse/middleman-jspm
- Owner: oncomouse
- Created: 2015-08-04T20:57:46.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2016-07-12T23:08:28.000Z (almost 10 years ago)
- Last Synced: 2024-04-24T21:21:15.167Z (about 2 years ago)
- Language: Ruby
- Size: 10.7 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Middleman-JSPM
`middleman-jspm` adds support for using [JSPM](http://jspm.io) in [Middleman](http://middlemanapp.com).
## Installation
To get started using Middleman, install `middleman` and make a project:
```
gem install middleman
middleman init PROJECT
```
Once that's done, add `gem "middleman-jspm"` to your `Gemfile` and run `bundle update`
## Configuring
Add the following somehere in your `config.rb`:
```ruby
activate :jspm
```
The bundle defaults to `source/javascripts/jspm_packages` for installing packages. If you want to use something else, you can activate with:
```ruby
activate :jspm, :jspm_dir => "source/js/jspm_packages"
```
### Optional
As `middleman-jspm` manages your javascript for you, you should consider adding `ignore "javascripts/*"` to your `configure :build` section of `config.rb`. Doing so will prevent the site from building your javascript files unnecessarily.
## Setting Up Node
This project relies on [Node.js](http://nodejs.org) to run JSPM. You will need to install it before you can use this gem.
After you have installed node, run:
```
npm install jspm
middleman jspm install
```
JSPM will ask if you want it to configure `config.js`. Say yes.
You can now install packages by running `middleman jspm install ` according to JSPM's settings.
## Defining Modules
`middleman-jspm` will only compile files defined in its `module.json` file at build time. This file can either be stored in the same directory as `config.rb` or included as a sprockets asset in the default javascript directory. The ability to use sprockets means you can build the JSON file with ERuby if you want to dynamically determine which modules to compile.
`modules.json` defines an array of module objects defined on the following format (where all properties except `name` are optional):
```json
[
{
"name": "main",
"include": [
"jquery"
],
"exclude": [
"react"
],
"self-executing": true
}
]
```
The above `modules.json` file will build a module named `main` that, in addition to dependencies defined in the file, will include jQuery but will not include React. The module will also compile as self-executing (which means JSPM will not add `system.js` and `config.js`) to the resulting file.
## Installing JSPM Packages
You can use `middleman jspm` to run JSPM commands, install packages, and build bundles. For more information, see the [JSPM-CLI documentation](https://github.com/jspm/jspm-cli).
## Building JSPM Pages
This is a minimal working example, that includes the module in `main.js` and all of its dependencies:
```erb
<%=current_page.data.title || "The Middleman"%>
<%= jspm_include_environment %>
<%= jspm_include_module("main") %>
```
`jspm_include_environment` includes the SystemJS and configuration files needed by JSPM and will include the correct files for both build and development environments. If all modules defined in `modules.json` are self-executing, this command returns nothing.
`jspm_include_module()` includes a module into the present document and will include the correct files, in the correct manner, for both build and development environments.
## Other Helpers
Finally, there is also a helper called `jspm_path(, [])` that can give you the path of a file installed with JSPM. For instance, to look the path of jquery that was installed from github, you would use `jspm_path("components/jquery", "github")` to get the path of the jquery used by JSPM. The helper works the same way for NPM packages.
## Additional Help
An example setup is posted at http://github.com/oncomouse/middleman-jspm-example