StealJS 1 has been released! It’s a major new version with some breaking changes, but our migration guide has everything you need to upgrade your app or plugin today.
It is so easy to upgrade a StealJS 0.16.x project to StealJS 1.x that in this post we’re going to upgrade five projects:
Quick Start example
We’ll start with a really simple example that shows using StealJS to load jQuery and some CSS.
Because both steal and steal-tools are devDependencies in package.json, we’ll run the following to upgrade both packages:
npm install steal@1 steal-tools@1 --save-dev
Now the latest 1.x versions of steal and steal-tools are installed!
This project uses npm run build to create the distributable files; after running that command, we get the following error:
ERROR: Error loading "stealjs@1.0.0#styles.css" at file:/quick-start/styles.css.js
Error loading "stealjs@1.0.0#styles.css" from "stealjs@1.0.0#index" at file:/quick-start/index.js
ENOTDIR: not a directory, open '/quick-start/styles.css/index.js'
ERROR:
Build failed
StealJS 1 no longer includes the steal-css plugin in the steal npm package, so we’ll need to install it as a dev-dependency and use the new plugins configuration.
First, let’s install steal-css from npm:
npm install steal-css --save-dev
Next, we’ll add the plugins configuration to package.json (and use steal instead of system):
{
...
"steal": {
...
"plugins": ["steal-css"]
}
}
The last thing we’ll do to take advantage of StealJS 1 is use the pre-configured steal.production.js file.
In our index.html, we’ll replace this:
<script src="./node_modules/steal/steal.production.js" main="index"></script>
With this:
<script src="./dist/steal.production.js"></script>
Less code and configuration, hurrah!
For this simple example, those are the only changes required to upgrade our project to StealJS 1. You can see all of these changes in a pull request in the quick-start project.
Angular 2 example
The StealJS Angular 2 example includes steal ^0.16.12 in its package.json dependencies, so we’ll upgrade it to 1.x:
npm install steal@1 --save
Now that the latest 1.x version of steal is installed, if we load the index.html page in a browser, we’ll see this error in the console: Error loading "styles.less" from "main"
StealJS 1 no longer includes the steal-less plugin in the steal npm package, so we’ll need to install it as a dev-dependency and use the new plugins configuration.
First, let’s install steal-less from npm:
npm install steal-less --save-dev
Next, we’ll add the plugins configuration to package.json (and use steal instead of system):
{
...
"steal": {
...
"plugins": ["steal-less"]
}
}
After those changes, our project will load correctly! You can see all of these changes as part of a pull request that upgraded the project to the latest version of Angular 2 and StealJS.
CanJS example
The StealJS CanJS example also includes steal ^0.16.12 in its package.json dependencies, so we’ll upgrade it to 1.x:
npm install steal@1 --save
Now that the latest 1.x version of steal is installed, if we load the index.html page in a browser, we’ll see this error in the console: Error loading "index.stache!stache" from "app"
When we migrated to CanJS 3, we installed steal-stache as a dependency, and in StealJS 1 we need to use the new plugins configuration for it to work correctly. StealJS 1 also no longer includes the steal-less plugin in the steal npm package, so we’ll need to install it as a dev-dependency.
First, let’s install steal-less from npm:
npm install steal-less --save-dev
Next, we’ll add the plugins configuration to package.json (and use steal instead of system):
{
...
"steal": {
...
"plugins": ["steal-less", "steal-stache"]
}
}
After those changes, our project will load correctly! You can see all of these changes in a single pull request.
React example
The StealJS React example includes steal ^0.16.4 in its package.json dependencies, so we’ll upgrade it to 1.x:
npm install steal@1 --save
Now that the latest 1.x version of steal is installed, if we load the index.html page in a browser, we’ll see this error in the console: Error loading "steal-react-example@1.0.0#world.jsx"
Previous versions of StealJS would load the package.json files for all of a project’s immediate dependencies, which isn’t as efficient as the new plugins configuration. In StealJS 1, we’ll add the plugins configuration with steal-jsx to package.json (and use steal instead of system):
{
...
"steal": {
...
"plugins": ["steal-jsx"]
}
}
After those changes, our project will load correctly! You can see all of these changes as part of a single commit.
Vue.js example
The StealJS Vue.js example includes StealJS 0.16.x in its package.json dependencies, so we’ll upgrade to 1.x:
npm install steal@1 steal-tools@1 --save
Now that the latest 1.x version of steal is installed, if we load the index.html page in a browser, we’ll see this error in the console: Error loading "steal-vuejs-example@1.0.0#styles.less"
StealJS 1 no longer includes the steal-less plugin in the steal npm package, so we’ll need to install it as a dev-dependency and use the new plugins configuration.
First, let’s install steal-less from npm:
npm install steal-less --save-dev
Next, we’ll add the plugins configuration to package.json (and use steal instead of system):
{
...
"steal": {
...
"plugins": ["steal-less"]
}
}
After those changes, our project will load correctly! You can see all of these changes as part of a pull request that upgraded the project to the latest version of Vue.js 2 and StealJS.
Migrate today
The migration guide is a great resource for upgrading your project to StealJS 1 today. In it, you’ll find all of the information that was used in this blog post, and more!
If you have any questions about migrating, please post in our forums or Gitter chat!