Overall, most of the changes needed to upgrade from a StealJS 0.16 project to StealJS 1 are quite small. If you are using an older version of StealJS and want to migrate to StealJS 1, please check out the changelog to see the changes that have occurred since the version you are currently using.
Getting StealJS 1
The recommended way to get StealJS is using npm. If you’re not already using StealJS with npm, we recommend doing so. You can install with:
If you are using Grunt for production builds, the Grunt tasks for StealJS have been moved to their own project, grunt-steal. This is explained in further detail below, but for now you will want to install grunt-steal:
npm install grunt-steal --save-dev
Breaking changes
The following are breaking changes to the way StealJS works that will require you to change your code. Most represent small (often one-line) changes; nothing drastic has changed since 0.16.
Production script tag
If you are using the npm plugin (and you should be!), you may need to change the main attribute in the StealJS script tag for production. If your script tag currently looks like this:
Where app is your package’s name in your package.json. steal-tools now always includes the package name in the bundles it produces, so where it previously might have written to the file dist/bundles/index.js, it now writes to dist/bundles/app/index.js.
Using the new configured steal.production alleviates the need to know about this. The Moving to Production guide has been updated; it contains all of the ways to use StealJS in production.
NPM 3
The npm plugin now defaults to compatibility with npm 3 and above. If you’re using Node version 5+, you have npm 3. If you are using an older version of Node, or are using npm 2 for another reason, you need to update your configuration in your package.json to add:
"steal": {
"npmAlgorithm": "nested"
}
If you are using npm 3+ and have "npmAlgorithm": "flat" in your package.json, you can remove this, but leaving it in your config will not cause any harm.
Plugins configuration
The following plugins are no longer included with the steal npm package, but rather are contained within their own projects:
Likewise, the Grunt tasks are no longer included with steal-tools. This is part of a long-term project of decreasing the size of our core packages; steal-tools being one of them.
The use of bundlesPath in steal-tools is deprecated in favor of the new dest option.
bundlesPath has always been confusing because it means something different when used in the client (to set the path where production bundles are served) vs. in the build (which previously meant where the bundles are written).
dest clears this confusion up. Setting dest tells steal-tools where your production files go. It will write out your bundles inside of this path.
To upgrade, change your build script that looks something like this:
steal-tools will write out bundles to path/to/build/bundles and also write out a pre-configured StealJS script to path/to/build/steal.production.js. More on that below.
bundlesDepth
Two configuration options have been renamed:
bundlesDepth to maxBundleRequests
mainsDepth to maxMainRequests
These options have been renamed to more accurately reflect what their purpose is: to control the number of requests that will be needed in production. The functionality remains the same.
Although StealJS 1 is mostly about solidifying that StealJS is production-ready, there are a few new features worth mentioning.
Loading from your project’s root
Since the introduction of the npm plugin, there has been an issue with wanting to load code from the project’s root, which may not always be a sibling of your project’s node_modules/ folder. In the past this was done by using your project’s package name to load: app/components/tabs where app is the "name" field in your package.json.
This wasn’t ideal because project names could be long, and if your project name changed, these imports would need to be refactored.
In StealJS 1, ~ refers to your project’s root.
import tabs from "~/components/tabs";
~ is treated the same as your project’s package name in StealJS.
Easier production use
Using Steal in development is as easy as adding a script tag that points to steal.js inside your node_modules folder, but up to now when changing to production you have to add a few attributes such as the main, and possibly bundlesPath or even baseURL.
Using Steal 1 in production is just as easy as in development. steal-tools now builds out a pre-configured steal.production.js to your dest folder. By default it will be written to dist/steal.production.js. So now all you need to do is use this script tag in production:
StealJS 1 includes Babel 6! We are using Greenkeeper to keep our packages up-to-date so there will be patch releases as new versions of Babel come out.
You can configure which presets/plugins are used in your package.json config:
The available presets and plugins are listed in the babelOptions docs.
Deprecations
These things still exist in StealJS 1 but are considered deprecated and might be removed in 2.0.
system name replaced by steal
In 0.16, StealJS used a special property called system to configure StealJS. You have probably used this in your package.json like:
"system": {
"map": {
}
}
In StealJS 1, this option is now called steal, so the above would become:
"steal": {
"map": {
}
}
Similarly, to dynamically import code we’ve previously taught to use System.import. This should be replaced by using steal.import instead:
steal.import("my/app").then(function(){
});
StealJS was built on top of a specification for modules that was planned to be part of ES6, but never came to pass. System.import() is supported by StealJS, SystemJS, and WebPack, but will never appear in the browser natively, so we are moving away from the System name so that in the future we can support the browser’s native module system, <script type="module">.
The global System is still available and won’t be removed any time soon, but you should use steal in its place, or steal.loader if you really do need the loader.
Configuring the loader directly
In the past you’ve been able to configure the System object directly to add map, ext, and other configuration values. In Steal 1, this is deprecated in favor of using steal.config():
Overall, most of the changes needed to upgrade from a StealJS 0.16 project to StealJS 1 are quite small. If you are using an older version of StealJS and want to migrate to StealJS 1, please check out the changelog to see the changes that have occurred since the version you are currently using.
Getting StealJS 1
The recommended way to get StealJS is using npm. If you’re not already using StealJS with npm, we recommend doing so. You can install with:
If you’re already using StealJS through npm, you can run the above commands to upgrade and your
package.json
will be updated.If you want to upgrade manually, change the versions of
steal
andsteal-tools
in yourpackage.json
to:If you are using Grunt for production builds, the Grunt tasks for StealJS have been moved to their own project, grunt-steal. This is explained in further detail below, but for now you will want to install
grunt-steal
:Breaking changes
The following are breaking changes to the way StealJS works that will require you to change your code. Most represent small (often one-line) changes; nothing drastic has changed since 0.16.
Production script tag
If you are using the npm plugin (and you should be!), you may need to change the main attribute in the StealJS script tag for production. If your script tag currently looks like this:
Where
"index"
is your application’s main module, you’ll want to change that to:Where
app
is your package’sname
in yourpackage.json
.steal-tools
now always includes the package name in the bundles it produces, so where it previously might have written to the filedist/bundles/index.js
, it now writes todist/bundles/app/index.js
.Using the new configured steal.production alleviates the need to know about this. The Moving to Production guide has been updated; it contains all of the ways to use StealJS in production.
NPM 3
The npm plugin now defaults to compatibility with npm 3 and above. If you’re using Node version 5+, you have npm 3. If you are using an older version of Node, or are using npm 2 for another reason, you need to update your configuration in your
package.json
to add:If you are using npm 3+ and have
"npmAlgorithm": "flat"
in yourpackage.json
, you can remove this, but leaving it in your config will not cause any harm.Plugins configuration
The following plugins are no longer included with the
steal
npm package, but rather are contained within their own projects:To use them, install them as
devDependencies
and use the newplugins
configuration to tell Steal to load theirpackage.json
for metadata.For example, to use
steal-less
, install it with npm:Then update the
plugins
configuration in yourpackage.json
:Grunt tasks
Likewise, the Grunt tasks are no longer included with
steal-tools
. This is part of a long-term project of decreasing the size of our core packages;steal-tools
being one of them.Install grunt-steal as a dev-dependency:
In your
Gruntfile.js
, change:to:
Finally, change the configuration object to be
steal
rather thansystem
like so:This also applies to the steal-export and steal-live-reload tasks. Learn more in the grunt-steal docs.
bundlesPath
The use of bundlesPath in
steal-tools
is deprecated in favor of the newdest
option.bundlesPath has always been confusing because it means something different when used in the client (to set the path where production bundles are served) vs. in the build (which previously meant where the bundles are written).
dest
clears this confusion up. Settingdest
tellssteal-tools
where your production files go. It will write out your bundles inside of this path.To upgrade, change your build script that looks something like this:
To:
steal-tools
will write out bundles topath/to/build/bundles
and also write out a pre-configured StealJS script topath/to/build/steal.production.js
. More on that below.bundlesDepth
Two configuration options have been renamed:
bundlesDepth
tomaxBundleRequests
mainsDepth
tomaxMainRequests
These options have been renamed to more accurately reflect what their purpose is: to control the number of requests that will be needed in production. The functionality remains the same.
Just change this option in your build script:
becomes:
New features
Although StealJS 1 is mostly about solidifying that StealJS is production-ready, there are a few new features worth mentioning.
Loading from your project’s root
Since the introduction of the npm plugin, there has been an issue with wanting to load code from the project’s root, which may not always be a sibling of your project’s
node_modules/
folder. In the past this was done by using your project’s package name to load:app/components/tabs
whereapp
is the"name"
field in yourpackage.json
.This wasn’t ideal because project names could be long, and if your project name changed, these imports would need to be refactored.
In StealJS 1,
~
refers to your project’s root.~
is treated the same as your project’s package name in StealJS.Easier production use
Using Steal in development is as easy as adding a script tag that points to
steal.js
inside yournode_modules
folder, but up to now when changing to production you have to add a few attributes such as the main, and possibly bundlesPath or even baseURL.Using Steal 1 in production is just as easy as in development.
steal-tools
now builds out a pre-configuredsteal.production.js
to yourdest
folder. By default it will be written todist/steal.production.js
. So now all you need to do is use this script tag in production:Babel 6
StealJS 1 includes Babel 6! We are using Greenkeeper to keep our packages up-to-date so there will be patch releases as new versions of Babel come out.
You can configure which presets/plugins are used in your
package.json
config:The available presets and plugins are listed in the babelOptions docs.
Deprecations
These things still exist in StealJS 1 but are considered deprecated and might be removed in 2.0.
system name replaced by steal
In 0.16, StealJS used a special property called
system
to configure StealJS. You have probably used this in yourpackage.json
like:In StealJS 1, this option is now called
steal
, so the above would become:Similarly, to dynamically import code we’ve previously taught to use
System.import
. This should be replaced by using steal.import instead:StealJS was built on top of a specification for modules that was planned to be part of ES6, but never came to pass.
System.import()
is supported by StealJS, SystemJS, and WebPack, but will never appear in the browser natively, so we are moving away from theSystem
name so that in the future we can support the browser’s native module system,<script type="module">
.The global
System
is still available and won’t be removed any time soon, but you should usesteal
in its place, orsteal.loader
if you really do need the loader.Configuring the loader directly
In the past you’ve been able to configure the System object directly to add map, ext, and other configuration values. In Steal 1, this is deprecated in favor of using steal.config():