Libraries
Libraries loader for Broccoli to make it easier and more efficient. We should avoid re-packaging every javascript library as a simple Ember CLI addon wrapper!!
Status
It works :)
You are encouraged to extend the API as you see fit and integrate more of the API as CLI commands to improve the user experience!
Why?
This project was created in response to ember-cli #2177. It aims to make it easier and more flexible to configure libraries to be imported by Broccoli.
Select libraries
selected
is a simple text file, where each line is a library you wish to include :)
bootstrap
datepicker
...
or use the library CLI to add/remove selected libs:
Add library add foundation
Remove library rm bootstrap
Configuration
Libraries can be grouped by category (bower
, vendor
, libs
etc.).
You can configure a simple directory alias mechanism if you like in the config section config
.
config.json
contains configurations for all the simple (or custom) libraries
// config.json config: 'vendor': 'vendor/libs' containers: bower: "components": "bootstrap" ... "libs: { "datepicker": {"date": "dist/datepickerjs"}, "calendar": "calendarjs", ... } }, vendor: { "components": [ "bootstrap", ...], "libs: ...
The libs
entry is for simple libraries that are a single javascript file.
Anything library with more than one file is a "component" and should have its own component configuration.
Component configuration:
// bootstrap.json "dir": "dist" "scripts": "dir": "js" "files": "bootstrap.js" "main": "bootstrap/core": "bootstrap.js" // can be used to remap "styles": "dir": "css" "files": "x.css" "fonts": "dir": "fonts" "files": "xyz.eof" "xyz.svg"
The dir
entries are optional (but useful). The component structure will make it easy to do all kinds of
interesting things in the future... (see Notes + Design documents for some ideas floating around in mind space...)
Registry
The global registry will contain an index.js
file and a list of library config files.
Note: Currently it is a json
file (for extensibility). It could perhaps be a simple line-divided text file
like the selected
file if no other info is needed...
// index.json registry: 'bootstrap' ...
Registry files:
index.json
bootstrap.json
...
On library install
, the libraries you have selected which don't have a local library config in your local repo will
be downloaded from the global registry.
Then you just have can run library build
to build the imports.js
file which libraries
will use to
apply on your app
to do the magic imports! Awesome 8>)
{ module { app; app; }};
When you build, it will build anxlibs/builds/imports-dev.js
if your current environment is dev
and so on...
This way you can better manage which libraries have been tested to go into production without overwriting them
when in dev or test mode. Super bonus!
Note: In future versions we might split up all configuration according to environment so you can opt-in to manage libraries per environment.
Petal integration for ES6 goodness
We also aim to integrate it nicely with petal and broccoli petal, in order that we can easily export (almost) any javascript library as an ES6 module for Ember CLI consumption :)
Petal test example:
var source = fs;var m = 'bower_components/moment/moment.js' source; // moment.js exposed as 'moment' module as defaultassert;
Petal will read the source file and convert it to en ES6 module to be saved on top of original (in this example).
new Petal(destination, source)
The ember-cli petal integration will likely support something an API like this:
app.import('bower_components/famous/core', { remap: 'famous/core'' }
;`
which would somehow output all of this (/8>?
https://github.com/abuiles/famous-remap/tree/master/famous-remapped
According to comments in #2177
Ember config
The ember-config generator will soon be refactored
to instead export library/component config files instead of directly injecting app.import
statements into the
Brocfile.js
. This will let you simply select the libraries you like via the generator and then install, build and import
all the import goodness directly into the Brocfile.js
>>> pure MAGIC!!
Usage example
Here simulating the app object and doing console.log
of the
commands that the app object would normally execute on app.import
Brocfile example
var EmberApp = ; var app = ; ; moduleexports = app;
CLI support
Deprecated See bin/library
for more recent CLI API
- Add CLI interface to add/remove via CLI commands
Add a library to selection
library add bootstrap
Remove a library from selection
library rm bootstrap
Install all library configs selected that are not part of local library configuration repo Missing configurations are fetched from remote repo/repository and installed locally!
library install
Runs install to install any selected components without a config.
Build javascript imports from selected libraries, using local library configuration.
Save as javascript file, ready to be used via require('libraries').applyOn(app);
in Brocfile.js
library build
Please help out to make this an awesome experience and greatly enhance productivity for all of us... ;)
Enjoy :)
Customization
The library API is very customizable. See the code for yourself!
The build
calls can each take a callback which allows you to fine-tune the output of
any build, so as to not be hardcoded to be used for the Broccoli build process ;)
License
MIT