1. Install jspm CLI:

    npm install jspm@0.16x -g

2. Create a project:

Optionally lock down jspm for the project:

    cd my-project
    npm install jspm@0.16x --save-dev

It is advisable to locally install to lock the version of jspm. This will ensure upgrades to the global jspm will not alter the behavior of your application. Use jspm -v to confirm the local version.

Create a new project configuration:

  jspm init

Package.json file does not exist, create it? [yes]: 
Would you like jspm to prefix the jspm package.json properties under jspm? [yes]: 
Enter server baseURL (public folder path) [.]: 
Enter jspm packages folder [./jspm_packages]: 
Enter config file path [./config.js]: 
Configuration file config.js doesn't exist, create it? [yes]:
Enter client baseURL (public folder URL) [/]: 
Which ES6 transpiler would you like to use, Traceur or Babel? [traceur]:

Sets up the package.json and configuration file. Note jspm init happens automatically if you try installing into an empty project too.

  • baseURL: This should be set to the public folder where your server will serve from, relative to the package.json file. Defaults to the package.json folder itself.
  • jspm packages folder: The folder where jspm will install external dependencies.
  • Config file path: The jspm config file for your application. Should be within the baseURL and checked in to version control.
  • Client baseURL: The URL from the browser where the public folder is hosted.
  • Transpiler: Change this option at any time with jspm dl-loader babel. Custom transpilation options can also be set through babelOptions or traceurOptions in the jspm config file.

If you ever need to reset any of these properties, you can modify the package.json, which will update the configuration when you next run jspm install or jspm init to refresh.

It is possible to run through the above prompts again at any time with jspm init -p.

3. Install any packages from the jspm Registry, GitHub or npm:

    jspm install npm:lodash-node
    jspm install github:components/jquery
    jspm install jquery
    jspm install myname=npm:underscore

Multiple installs can also be combined into a single line separated by spaces.

Any npm or Github package can be installed in this way.

Most npm packages will install without any configuration necessary. This is because the npm registry endpoint applies conversion operations based on the assumption of Node require resolution making the Node and npm-style code compatible with jspm.

Github packages may need to be configured for jspm first. Read the guide here on configuring packages for jspm.

All installs are saved into the package.json, so that the jspm_packages folder and configuration file can be entirely recreated with a single jspm install call with no arguments. This is ideal for version-controlled projects where third party packages aren't saved in the repo itself.

The config.js file is updated with the version information and the version is locked down, this configuration file itself forming the lock, which should be added to version control.

4. Write application code

We can now write into our lib folder code that loads our dependencies, in any module format (including ES6):

lib/bootstrap.js

    import _ from 'lodash-node/modern/lang/isEqual.js';
    import $ from 'jquery';
    import underscore from 'myname';

    export function bootstrap() {
      // bootstrap code here
    }

lib/main.js

    import {bootstrap} from './bootstrap.js';
    bootstrap();

Note modules are only detected as ES6 when module syntax is present. This is because the module loader transpilation is linked to the ES module format currently, althought this transpilation layer will be separated in future. Read more about SystemJS module formats at https://github.com/systemjs/systemjs/blob/master/docs/module-formats.md.

5. Run the code

In an HTML page include the automatically downloaded SystemJS loader along with the config file, then import our application main entry point:

  <!doctype html>
  <script src="jspm_packages/system.js"></script>
  <script src="config.js"></script>
  <script>
    System.import('lib/main.js');
  </script>

Run a local server to view the page.

jspm makes requests for many files. For best performance, ideally try to use a performant HTTP/2-enabled development server and set up jspm_packages to be served with far-future expires from the local server so that it is cached in the browser and separate requests don't need to be made.

6. Bundle for production

  jspm bundle lib/main --inject

Refresh the browser, and see the entire app loaded from a single bundle file.

Alternatively, use jspm bundle-sfx lib/main to create a bundle script that can be used on its own with a <script> tag independent of config.js and system.js.

Next Steps

Read more about the production workflows

Read the guide on configuring packages for jspm here.

If you are having any trouble configuring a package for jspm, please just post an issue to the registry and we'll help get it configured.