steal

@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. ```  <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. ```  <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!")