steal
Version:
Gets JavaScript.
260 lines (185 loc) • 6.57 kB
Markdown
@page steal
@parent StealJS.api
@group StealJS.syntaxes syntaxes
@group StealJS.config config
@group StealJS.modules modules
@group StealJS.types types
@group StealJS.functions functions
@group StealJS.schemes schemes
@group StealJS.hooks hooks
@group StealJS.other other
Steal is a module loader that supports a wide variety of
syntaxes and configuration options. It makes modular development, test
and production workflows simple.
There are four basic steps when using Steal:
- Install steal
- Add the steal script tag
- Configure steal
- Import modules and make stuff happen
Steal works slightly differently depending on how it is installed. There
are three ways to install Steal:
- [npm](#section_npmbasics)
- [download](#section_Downloadbasics)
## npm basics
The following details how to use steal installed via [npm](https://www.npmjs.com/) to make
a simple jQuery app.
### Install
```
> npm install steal -S
> npm install jquery
```
Next to your application's _node_modules_ folder, create _myapp.js_ and
_myapp.html_:
```
/
node_modules/
package.json
myapp.js
myapp.html
```
### Add the script tag
In _myapp.html_, add a script tag that that loads _steal.js_ and points
to the [config.main main] entrypoint of your application. If
main is not provided, [config.main] will be set to _package.json_'s main.
```
<!-- myapp.html -->
<script src="./node_modules/steal/steal.js" main="myapp"></script>
```
### Configure
Steal reads your application's _package.json_ and all of its
`dependencies`, `peerDependencies`, and `devDependencies` recursively.
Most configuration is done in the `steal` property of
package.json. The special npm configuration options are listed [npm here].
The following _package.json_ only loads the `dependencies`.
```
{
"name": "myapp",
"main": "myapp",
"dependencies": {
"jquery": "2.1.3"
},
"devDependencies": {...}
"steal": {
}
}
```
If there are problems loading some of your dependencies, read how to configure them on the [npm] page.
### Import modules and make stuff happen
In _myapp.js_, import your dependencies and write your app:
```
// myapp.js
import $ from "jquery";
$("body").append("<h1>Hello World</h1>")
```
### Importing in your app
From here using packages is the same as if you used npm, just import them into
_myapp.js_ and do what you need:
```js
import can from "canjs";
var renderer = can.stache("<h1>StealJS {{what}}</h1>");
can.$("body").append(renderer({
what: "rocks!"
}));
```
## Download basics
The following details how to use steal installed via its download to
make a basic jQuery app.
### Install
[Download Steal](https://github.com/bitovi/steal/archive/master.zip) and unzip into your application's folder.
In your application's folder, create _myapp.js_,
_myapp.html_ and _config.js_. You should have something like:
```
/
steal/
ext/
steal.js
steal.production.js
myapp.js
myapp.html
```
### Add the script tag
In _myapp.html_, add a script tag that that loads _steal.js_ and points
to the [config.configPath configPath] and [config.main main] entrypoint of your application.
```
<!-- myapp.html -->
<script src="../path/to/steal/steal.js"
config="./config.js"
main="myapp">
</script>
```
### <a name="path-configure"></a>Configure
`config.js` is used to configure the behavior of
your site's modules. For example, to load jQuery from a CDN:
```
// config.js
steal.config({
paths: {"jquery": "http://code.jquery.com/jquery-1.11.0.min.js"}
});
```
> Note: Steal makes an AJAX request for the above example. Both client and server will need
> to accept/handle CORS requests properly when using remote resources.
### Import modules and make stuff happen
In _myapp.js_, import your dependencies and write your app:
```js
// myapp.js
import $ from "jquery";
$("body").append("<h1>Hello World</h1>")
```
## Configuring `steal.loader`
Once steal.js loads, its startup behavior is determined
configuration values. Configuration values can be set in three ways:
- Set on a `steal` object prior to loading steal.js like:
<script>
steal = {main: "myapp"};
</script>
<script src="../path/to/steal/steal.js"></script>
- Attributes on the steal.js script tag like:
<script src="../path/to/steal/steal.js"
main="myapp">
</script>
- Calling [config.config]. This technique is typically used in the [config.configMain] module.
steal.config({
paths: {"can/*" : "http://canjs.com/release/2.0.1/can/*"}
})
If you are using npm, your app's package.json will be loaded automatically. Steal configuration happens in their `steal` properties:
{
"name": "myapp",
"dependencies": { ... },
"steal": {
"map": {"can/util/util": "can/util/jquery/jquery"}
}
}
Typically, developers configure the [config.main] and [config.configPath] properties
with attributes on the steal.js script tag like:
<script src="../path/to/steal/steal.js"
main="myapp"
config-path="../config.js">
</script>
Setting [config.configPath] sets [config.baseURL] to the
configPath's parent directory. This would load _config.js_ prior to
loading _../myapp.js_.
When _steal.js_ loads, it sets [config.stealPath stealPath]. [config.stealPath stealPath] sets default values
for [config.baseURL baseURL] and [config.configPath configPath]. If _steal.js_ is in _node_modules_,
[config.configPath] defaults to _node_modules_ parent folder. So if you write:
<script src="../../node_modules/steal/steal.js"
main="myapp">
</script>
This will load `../../package.json` before it loads `../../myapp.js`.
## Writing Modules
Once you've loaded and configured steal's behavior, it's time to start
writing and loading modules. Currently, [syntax.es6 ES6 syntax] is supported
in IE9+. ES6 syntax looks like:
import can from "can";
[@traceur Traceur Compiler] is used and all of
of its [language features](https://github.com/google/traceur-compiler/wiki/LanguageFeatures) will work.
If you must support <IE8, use any of the other syntaxes.
Finally, steal supports [$less less] and [$css css] out of the box. Import, require, or
steal them into your project by adding a "!" after the filename.
// ES6
import "style.less!";
// AMD
define(["style.less!"],function(){ ... });
// CommonJS
require("style.less!");
// steal
steal("style.less!")