Skip to content

Latest commit

 

History

History
260 lines (186 loc) · 6.49 KB

steal.md

File metadata and controls

260 lines (186 loc) · 6.49 KB
Raw

@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 basics

The following details how to use steal installed via npm 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:

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 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>

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:

// 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 bower or npm, your app's bower.json or 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 bower_components, [config.configPath] defaults to bower_components parent folder. So if you write:

<script src="../../bower_components/steal/steal.js"
        main="myapp">
</script>

This will load ../../bower.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 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!")