How to Upgrade to StealJS 1

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 (with just jQuery)
• Angular 2 example
• CanJS example
• React example
• Vue.js example

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!