Getting Started With jspm & SystemJS


After watching Glen Maddern’s brilliant JavaScript in 2015 video a couple of dozen times I figured it was about time I documented the steps required to get your next JavaScript project up and running with jspm and SystemJS.

jspm is a package management tool which makes using any of the various JavaScript module formats a breeze. For this example I'll be using the shiny new ES6 module syntax.

SystemJS is a shim for the upcoming loader specification which aims to align module loading across JavaScript environments.


Setup

Ensure you have Node.js installed along with npm before beginning.

Begin by creating a project directory where all your code will live.

mkdir awesome-project && cd awesome-project

Install jspm locally as a development dependency.

npm install jspm --save-dev

Initialise jspm.

jspm init -y

jspm asks a variety of setup questions, passing through the -y flag will skip the setup and just use the defaults.

jspm prints out those default choices so if you want to run through the prompts again and change anything you can.

jspm init -p

Once jspm has installed everything required you'll be left with a config.js file, a /jspm_packages/ directory and a basic package.json file which includes a custom jspm object.

config.js contains the SystemJS config which will be referenced from within your HTML.

/jspm_packages/ is where your dependencies live, similarly to /node_modules/ it can be .gitignored. You can reinstall your dependencies at any time.

jspm install

Writing Code

It’s now time to start writing some code.

Begin by creating an index.html file in the root directory of your project and write a simple HTML document. Within the document you need to include two script tags, once referencing the system.js file located within the /jspm_packages/ directory and the other at the config.js file in the root directory.

Finally you need a small piece of inline JavaScript to import your main module via SystemJS. Main references a JavaScript file in the same directory.

<script>
System.import('main.js')
</script>

Here’s the full index.html example.

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible” content=”IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title></title>
</head>
<body>
     <script src="jspm_packages/system.js"></script>
<script src="config.js"></script>
     <script>
System.import('main.js')
</script>
   </body>
</html>

Next create a file called main.js, again within the root directory, this is the entry point to your JavaScript which was referenced in the index.html file. Let’s just check the main module is being loaded before going any further.

console.log('is this thing on?')

You can spin the application up in the browser using just a static server like live-server or Python’s built in server (python -m SimpleHTTPServer).

It’s worth noting there’s also a fork of live-server called jspm-server, again from Glen Maddern which, although in its early stages right now, aims to be the development server for jspm.

Once you're happy things are working as expected you can start using ES6 module imports to build your application. Here’s a quick example but there are lots of great resources out there for the new syntax.

import myModule from 'my-module'
myModule.init()

External Dependencies

jspm has its own registry which routes package install requests to the correct source and builds them ready for use in your project.

jspm install package-name

If a package isn't referenced in the jspm registry you can request it directly by passing through the module’s location.

jspm install custom-package-name=npm:package-name

You can then import these dependencies in your code

import packageName from 'package-name'
import custom from 'custom-package-name'

Production Workflows

Until we can truly harness the benefits of HTTP/2's multiplexing features the need to reduce HTTP requests with concatenation exists.

Thankfully jspm offers smart code bundling in a couple of different ways, both of which create a single unminified file complete with source maps to help with debugging.

You can either bundle all the modules you've written and keep the exact same setup in your HTML file.

jspm bundle main --inject

Or you can bundle SystemJS, the config and all your modules into a single self executing file, which means replacing the setup within your HTML file with a script tag loading the compiled file.

jspm bundle-sfx main

Conclusion

There you have it, jspm and SystemJS offer a quick and painless way to start writing ES6 for the web right now. All with the added benefit of knowing your setup will scale for the future as protocols, languages and the environments we’re building in advance.

If you want a setup which uses JSPM, SystemJS and Babel out of the box without the configuration then check out my simple seed project which uses most of the settings I've mentioned above, you can get it from GitHub now.