geelen / jspm-server

A live-reloading development server for JSPM

JSPM Server

This is a development server for JSPM static sites. It's based on @tapio's excellent live-server, which I used for a long time very happily.

Installation

You'll need NodeJS and NPM, then to install the jspm-server command-line utility globally:

npm install -g jspm-server

Usage from command line

Run jspm-server from your project's directory.

Additional parameters:

• --no-browser - suppress automatic web browser launching
• --quiet - suppress logging
• --open=PATH - launch browser to PATH instead of server root
• --port=8081 - open with port
• --proxy=http://localhost:8080 - proxy a running server
• --only-exts="" - watch only files with the specified extensions
• --ignore-exts="" - exclude files with the specified extensions

How it works

Note: you must have System.trace = true set in your HTML or config.js file for live-reloading to work.

You can mark any ES6 file as being live-reloadable by adding the following line:

export let __hotReload = true

This is a short hand for exporting __hotReload as a named export (the full version is let __hotReload = true; export { __hotReload };)

Setting __hotReload = true indicates the following:

• This file can be safely reloaded (the new file will be simply executed)
• On reload:
  • if the new file changes its exports (using ===), the reload event will propagate
  • if the new file's exports are equal, the reload will stop

If your file exports something new on each execution (such as a class, function or nested data structure), setting __hotReload = true will cause all dependents of this file to be reloaded as well. To override that behaviour, you can declare __hotReload as a function:

export function __hotReload() {
  // return true has the same meaning as above - propagate if and when the exports change
  // return false halts propagation
}

This function runs directly after the new module is executed, allowing you to clean up any state in this file that is no longer relevant. That might be removing event listeners, canceling any future-scheduled work, that sort of thing.

Loaders

Loaders can inject a __hotReload export by appending to the source in a fetch. The css loader does this, so all CSS files are live-reloadable.

Proxying

When proxying a server, be sure to either start jspm-server from your static assets directory, or utilize the root directory argument, e.g. jspm-server --proxy=http://localhost:8000 --port=8001 public/src

Include only extensions

To make jspm-server only react to wanted extensions, use the --only-exts option. This is useful, for example, while writing Sass, as jspm-server will do a hard reload when it encounters an scss file.

Usage example: jspm-server --only-exts=".js, .jsx, .html, .css"

Note that you do not have to include a space after the delimiting comma. The periods in the extension names are likewise optional.

Ignore extensions

This is a reverse of the --only-exts option. To make jspm-server exclude certain extensions from the reloading, use --ignore-exts="" and specify the extensions you want to ignore.

Usage example: Usage example: jspm-server --ignore-exts=".scss, .less"

The ignore filter is executed before the include filter, so if you specify an identical extension in both filters, it will be excluded.

Version history

• v0.1.6
  • Supports multiple browsers to be connected and live-reloaded simultaneously.
• v0.1.5
  • Support for --only-exts and --ignore-exts added. Thanks @danieldunderfelt!
• v0.1.4
  • Proxying support is added. Thanks @kevrom!
• v0.1.3
  • Ensured System.baseURL is taken into consideration.
• v0.1.0
  • Changed the format of live-reloading, from requiring the plugin to define a hotReload handler to deciding on a per-file basis. Propagation is now far more powerful and predictable. System.trace = true is now required.
• v0.0.3
  • Added dependency-tracking, once a file has been live-reloaded, attempt to live-reload all of its dependents. Note: requires System.trace = true to be in your project ahead of your initial System.import to take effect.
• v0.0.2
  • Added a html5mode, where if a 200.html is present in the root directory, any url that doesn't contain a . will serve it instead. Enables single-page apps nicely.
• v0.0.1
  • Forked from v0.7.1 of live-server

Development

Friends, come and hack and make things better!

• Check out this project
• npm install to fetch the dependencies
• npm run build to rebuild the injected file
• ./jspm-server.js to run your local dev copy

Because the injected file needs to be rebuilt and the server restarted for every change, a useful command is:

npm run build && ./jspm-server.js ~/path/to/project --no-browser

Note: You'll need to hard-refresh (⌘⇧R) your browser for the injected file to be definitely picked up.

License

Uses MIT licensed code from live-server, Connect and Roots.

(MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

jspm-server's Issues

No luck with ReactRouter :(

Trying to use this on a project with React Router but it doesn't seem to be playing ball. Both the command line & browser logs that it detected the files have changed and refreshed them, but the browser output doesn't actually change. I'm not entirely able to figure out what might be going on here. Does something need to change to tell ReactRouter that the component has changed?

Expire headers?

jspm/jspm-cli#872 (comment) mentions expire headers configuration for browser-sync. Is this something that will be implemented in jspm-server at one point?

Future of this project ?

I would like to raise a discussion about the future of this project and wether we should intend / expect to make it more stable.

I really would like to invest some time in making this the default dev server for jspm, the same way webpack has its webpack-dev-server.

Some quick notes I've been taking regarding what should be improved in my opinion to reach a decent usable state:

• Cleanup the use of systemJS.
• Tests: I have been playing a bit with selenium today to be able to test a running jspm-server and so far I was able to test jspm-server from a browser point of view but it is still unclear how to correctly observe the hot reloading behavior. I think the problem is with the websocket, but it's just a wild guess. Maybe we should focus more on pure unit tests if this can't be achieved.
• jspm / systemjs version requirements: this should be clearly expressed in the doc.
• release notes
• Keep track of github issues and PR.
• Keep the documentation up to date and improve it when needed.

What I plan to do:

• I think having #27 finalized and merged would be nice.
• I will keep looking at improving tests.
• I will then improve the project whenever I need improvements for my personnal projects.
  (eg: I'm interested in getting jsx hot reloading back in shape)
• Contribute the best I can to answer people questions and review pull requests.

Now and before taking any further commitment I would like to take the mood of the people around the project and have a bit of feedback.

@geelen sorry to ping you again but I think you are probably the most interested in this ;-)

Allow embedding as a middleware

It would be great to separate the middlware and actual server parts, and allow embedding under any node-http compliant middleware server.

Cannot read property 'push' of undefined

Hi !
I spent quite a lot of time digging this today but I'm helpless...
I have a demo project running that does all I want, but on my actual project I cannot get this to work I keep having the following error when doing any change to a hot-reloaded file.

Uncaught TypeError: 
Cannot read property 'push' of undefined(anonymous function) @ (index):529
(anonymous function) @ (index):521
updateDepMap @ (index):519
ChangeHandler @ (index):488
exports.default @ (index):649
socket.onmessage @ (index):625

I checked all the dependencies between the 2 project and they look the same.
It does happen because of a jsx file...

When removing references to the jsx files I don't get the error anymore but hot reloading is not working, I get a full reload instead.

any pointer ?

Hot reloading error: "Change to X cannot be handled gracefully" & "Change occurred to a file outside SystemJS loading"

Hi, I've written a simple es6 module which I'm trying to get Hot-reloading using jspm + jspm-server (fork of live-server).

When jspm-server first loads, the modules work fine. But when I make a change I get the following error

$ node test/server.js
Serving "/Users/ashleycoleman/github/inbro" at http://127.0.0.1:8080
🤘  Client connected. JSPM watching enabled
Change detected: test/async-dom-operation.js
✅  SystemJS loaded. Initialising ChangeHandler

# Then the below error occurs when I make a change to "async-dom-operation.js"
💥  Change to http://127.0.0.1:8080/test/async-dom-operation.js cannot be handled gracefully:
👉  Change occurred to a file outside SystemJS loading

This is my project setup:

.
├── config.js
├── package.json
└── test
    ├── async-dom-operation.js
    ├── index.html
    ├── main.js
    └── server.js

server.js:

var jspmServer = require("jspm-server");

var params = {
    host: "0.0.0.0", // Set the address to bind to. Defaults to 0.0.0.0.
    open: '/test/' // When false, it won't load your browser by default.
};
jspmServer.start(params);

main.js:

import {asyncDomOperation} from '/test/async-dom-operation.js';
export let __hotReload = true; // For jspm-server hot reloading
asyncDomOperation();

async-dom-operation.js:

export function asyncDomOperation() {
    var writePara = (msg) => () => document.writeln('<p>'+msg+'</p>');
    setTimeout( writePara('Start...'), 100 );
    setTimeout( writePara('...middle'), 200 );
    setTimeout( writePara('...end'), 300 );
}
export let __hotReload = true; // For jspm-server hot reloading

config.js:

System.config({
  baseURL: "/",
  defaultJSExtensions: true,
  transpiler: "babel",
  babelOptions: {
    "optional": [
      "runtime",
      "optimisation.modules.system"
    ]
  },
  paths: {
    "github:*": "jspm_packages/github/*",
    "npm:*": "jspm_packages/npm/*"
  },

  map: { ...  etc ...}
});

Automated testing

For a project like this, I really want regression tests to ensure that all these bug fixes stay fixed. Maybe I can orchestrate something using JSDOM. Or shudder phantomjs

Document `port` CLI option

Document the port CLI option:

jspm-server --port=8081

On NPM, the repo link is to tapio/jspm-server

Seems like you forgot his vendorname in your package.json!

This project looks fantastic, going to test-drive it a bit.

Reloading in proxy mode looses jspm watcher

Whenever I hit refresh in my browser or a reload event is triggered, the JSPM watcher is not started again.

Initial run of jspm-server --proxy=http://127.0.0.1:8000 --port=8080 , all is fine

Navigated to http://127.0.0.1:8080/login/
content_script.js:84 Bind hotkeys 
(index):449 JSPM watching enabled!
main.js:10 I changed
(index):362 Reloaded js/main

Hitting refresh in the browser.

Navigated to http://127.0.0.1:8080/login/
content_script.js:84 Bind hotkeys 
main.js:8 I changed

No more subsequent changes are detected.

Noob alert: How do you rebuild ?

How do you rebuild the injected.js file ?

Proxy Path

I am probably just missing this. How can I specify that a certain path (ie, /api/*) be proxied to another URI (http://localhost:8080/api)?

JSPM/SystemJS live-reloading hot-swapping dev server?

Ok, this is me just starting an issue to discuss with @guybedford about where this might fit in to the JSPM landscape. It didn't seem ready to add something against jspm-cli or systemjs yet because it's really early days, but I do have something working and I'd like to get feedback.

This project is a fork of live-server which I've been using for all my dev with JSPM. It has the best collection of defaults I've seen for any 0-configuration server, and doesn't build upon tiny-lr or anything, so I found the code really easy to get going with (thanks @tapio!)

Anyway, on to the proof-of-concept!

The main change from live-server is the behaviour here, where now I'm actually passing through the paths of the files that change, rather than deciding whether to 'reload css' or 'reload the whole page' on the server.

That logic has now moved into ChangeHandler, which uses System._loader.modules to figure out what's been loaded, and what plugin it used. It then loads the plugin and sees if a flag reloadable is set. Since my CSS plugin uses a side-effect to insert the CSS into <head>, I can simply call System.load (with a cache-busted URL) and cause the CSS to be reloaded.

Of course, I had to actually set my plugin up to work that way: post-css.js. I've changed this now to only ever add one <link> tag to the HEAD, but use a Map (which is ordered) to keep track of the source files so far loaded. When any new ones are translated, add them to the map (if they haven't been seen before they'll go at the end, if they have they'll take their older version's place) and regenerate the one <link> tag with a new URL. This means you can define variables in one file and use them in another, since postcss is being called on the full concatenated source each time.

In the end, I got a lot further than I thought I would have, because live-server had done so much already. Designing my CSS plugin to handle updates wasn't too bad, and actually bought me that variable support between two imports: defined with this import then used with this one

All in all, this server + plugin combo gives me super freaking fast CSS feedback, which was the whole goal. I'd love to extend this to support React hot-reloading too, but I understand that a lot less at the moment.

What do you think? Is there a better way to figure out what's loaded than System._loader.modules? And a better way to force a reload than using a cache busting query-string?

live-server backporting features

I've just started playing with your jspm-server tool, and it seems very promising. I've used jspm on many of my projects, but I didn't know live reloading was even possible!

I see that you've added new base functionality to the live-server tool, such as:

• --proxy=http://localhost:8080 - proxy a running server
• --only-exts="" - watch only files with the specified extensions
• --ignore-exts="" - exclude files with the specified extensions

Would you consider porting these features back to the base live-server project? Our users have asked for some sort of --proxy functionality too (tapio/live-server#36), but I don't have experience using live-server in this way.

If you don't have time for a PR, I could look into doing it for you.

Thanks for the great work!

NotAcceptableError

I am just starting to play around with System.js and jspm-server, I love the idea and the direction this is going.

Still working out if we can integrate this into our existing project but I am getting some strange errors sometimes:

NotAcceptableError: Not Acceptable
    at /Users/markus/.node_modules/lib/node_modules/jspm-server/node_modules/serve-index/index.js:169:32
    at FSReqWrap.oncomplete (fs.js:82:15)

Still investigating when exactly it happens.

How to make css files reloadbable if I don't use jspm-loader-css?

Thank you for this great project.

use commander for parsing cli options

wouldn't it be nicer to use this library instead of parsing options manually?

Compatibility with jspm 0.16

The project seems to be broken with the new version of jspm and systemjs.

The first big thing I spotted is an issue with path that I almost fixed in #27

I'm still experiencing issues with jsx file and I need help with that :/

@geelen or @kevrom any insight ?

Improve the way we are marking modules as hot-reloadable

Follow-up of discussion going in #1, should go here :-)

Quoting @guybedford:

It could be worth allowing load metadata as an alternative way to indicate hot reloading as well (and that would also avoid the export * issue for hot reloadable modules as well if that causes problems down the line).

That would allow something like:

System.config({
meta: {
'*.js': { hotReload: true }
}
});

Quoting @geelen:

That could be a great solution @guybedford. I think hot-reloading should be opt-in, but yeah, it would be good to not to have to specify it on each and every file...

change detected but browser is not reloading

simple project link https://github.com/timcash/jspmtest

OS X 10.10.4
Chrome 44.0.2403.155 (64-bit)
Node v0.12.6

Any ideas why I cannot get the browser to reload when lib/main.js changes? The server logs that it detects the change but the browser does not reload.

Add host option

It would be great to have an option for jspm-server to open the browser at an address other than 127.0.0.1. I'm working with services that use the a specific domain from the request origin to validate CORS access and it is annoying to have to change the address from 127.0.0.1 to the correct host each time I start the server.

I think something like a --host option would do the trick.

Note: Of course, I've setup my own host files locally so I'm not looking for that behavior. Just something to load the browser with a specified domain.

Relative jsx reference are not hot-reloaded ?

Hi again !

This is how I load my main module:

<script type="text/javascript">
    System.import('js/main');
</script>

Then If I load the app.jsx file that lives right next to the main.js file like this:

import App from 'app.jsx!';

Hot reloading fails and I get a full browser refresh instead.

However if I do this:

import App from 'js/app.jsx!';

All is fine.

Maybe this is a silly question but I'm trying to wrap my head around this.
Thanks already ;-)

Experimental fork

I'm doing my own experimentation in a fork
The goal is to provide an server capable of

• Use HTTP2 / SPYD / HTTP (with or without ssl)
• Tracing dependencies graph for System.js
• Doing some back end transpilation
• In memory pre bundling
• Re-adding your cold/hot reload

I publish my result on npm so we can test stuff. douglasduteil...jspm-server

Page reloading query

I'm struggling with my application still wanting to reload even though I seem to have everything in place to allow modules to be replaced without a full page refresh and was hoping to get some insight/troubleshooting help.

AFAIK I've got everything set up correctly, I've got System.trace = true in index.html and within each component I'm exporting __hotReload = true. Things are working correctly, hot replacement happens with no page refresh, but then the page refreshes straight after that. See screenshot & gif below.

Is it the fact that jspm-server is watching my whole repository and it's seeing files in the src directory change which it can't handle and falls back to refreshing (that's what the console warning suggests to me anyway)?

The gif should give some insight into my setup, file structure etc... but I'm not sure if that's the optimal way, it'd be interesting to know how you've got things set up in your dev env @geelen. Perhaps it's a workflow thing and I need to change the setup a bit to accomodate.

If you want to see the code, config, gulpfile I'm using you can see the repo here.

Publish jspm 0.16 compatibility fixes to npm

Is there a reason why the jspm 0.16 compatibility fixes haven't been tagged and published to npm?

Thanks!

How to set root folder and mount options

--root:"public"
--mount=ROUTE:PATH

Can we do this.

I think live server already have this.
https://www.npmjs.com/package/jspm-server

HTTP2 and SSL certificate support

HTTP2/SPDY support 👍

• SSL keys/certificates

generated html file not causing reload

Hello,

I have a package which generates an html file, after running unit tests. The jspm-server recognizes the change, but doesn't reload the page.

Change detected: karma\Chrome_43.0.2357_(Windows_7_0.0.0)\index.html
Change detected: karma\Chrome_43.0.2357_(Windows_7_0.0.0)\index.html

consider adding "main" field to package.json

Hi, this is no big deal, but it might be nice to add a main field to package.json.

That way people using the server programmatically can have

require('jspm-server')

instead of

require('jspm-server/index.js')

have a config module as a possible way of specifying the options for jspm-server

ideally, it's config options would match at least partially those in browser-sync so people coming over don't have to rewrite their configs that much.

Paths not being detected correctly while using proxy server

Updated file paths aren't matching the paths that the Module map in the changeHandler has. It's causing issues with hot reloading while using a proxy. The paths get mutated and it's not very clear what exactly is happening. This issue is more of a way of saying I'm aware of the issue, and I'll be looking into it over the next day or two.