gulp-server-io

Create a static server, live reload and a socket.io debugger for your SPA development with gulp Plus a standalone server with Express / json-server and http proxy for rapid deployment

This package is no longer actively under development. We have move on to another more generic solution server-io-core 2019

Introduction

This is a complete rewritten version of the gulp-webserver-io; with many features added, and improvements.

The goal is to create an one stop shop solution during development, as well as simple, and quick SPA deployment tool.

See CHANGELOG.md for complete list of different between the two version.

Installation

  $ npm install --save-dev gulp-server-io

Using yarn

  $ yarn add gulp-server-io --dev

During Development

Use with Gulp

There are several ways to use this package. First, during development and, use it with gulp:

1.5.0 final version will remove the gulp-server-io/gulp and gulp-server-io/export, because the new npm install dependencies in a flat structure. So if this package use it then it's available anyway.

// gulpfile.js  
// We have include the Gulp 4 with this package and you can just require it.
// But remember you do need to install gulp-cli globally, they are two different modules
const gulp = require('gulp');
const gulpServerIo = require('gulp-server-io');

gulp.task('serve', () => {
  return gulp.src(['./app', './.dev', './tmp'])
             .pipe(
               gulpServerIo()
             );
});

Socket.io Debugger

This is enable by default. To turn it off, pass debugger: false to the configuration.

Please note this will not be enable in the stand alone server version. It's only available for the gulp development version.

V.1.1.0 integrate with stacktrace.js to produce a much nicer output in the console.

V.1.4.0 add onunhandledrejection on the client side to catch those unresolved promises.

V.1.5.0 add a new option consoleDebug: true, this will overwrite the console.debug method, so you can use this in your code, and the result will be send to the server side instead of the console display.

The main use is when you need to run your app on your mobile, that allows you to quickly see if there is any error. Also the same method is expose globally, you can do something like this:

You can also use the stacktrace.js which is available globally via the StackTrace object.

Please remember to take this down once you are production ready, because the debugger and stacktrace.js only inject into the HTML dynamically during development.

Proxies

const server = require('gulp-server-io');
gulp.task('serve', () => {
  return gulp.src('./app')
    .pipe(
      server({
        proxies: [{
          source: '/api',
          target: 'http://otherhost.com',
          changeOrigin: true,
          logLevel: 'debug' // check http-proxy-middleware documentation
        }]
      })
    );
});

Its very important that you pass the config as an array

Please note when you call the /api resource, it will translate to http://otherhost.com/api.

For further configuration options, please check http-proxy-middleware

If you are using the deployment option. For example, you create a Restify service running on the localhost at port 8989.

const server = require('gulp-server-io/server');
server({
  proxies: [{
    source: '/api',
    target: 'http://localhost:8989'
  }]
});

Please, note if in your code are all using relative path, it will work out of the box when you deploy.

For example, during development your host is http://localhost:8000 and, your production domain name is http://example.com; hard coding the domain name in your AJAX call is not recommended. This is why we include the proxy server. Another upside is during your development, you don't have to do any setup for the CORS issue.

Mock data api

  gulp.src('./app')
      .pipe(
        server({
          mock: {
            json: '/path/to/api.json'
          }
        })
      )

Create an api.json according to json-server

{
  "users": [
    {"id": 1, "name": "John Doe"},
    {"id": 2, "name": "Jane Doe"}
  ]
}

In your UI code, you can fetch data from your fake rest endpoint:

  fetch('/users').then( res => {
    if (res.ok) {
       return res.json();
    }
    throw new Error('Not OK');
  })
  .then( json => {
    // do your thing
  })
  .catch( err => {
    // deal with your error
  })

Once you use the mock option, all your proxies definition will be overwritten by the mock JSON path.

NEW @ 1.4.0 I have added a watcher to your JSON file, so whenever you edit your mock JSON data file, the mock server will automatically restart. 1.4.0-beta.4 has an error regarding the non-directory option, it's been fixed in the later release

serverReload

This is a new option in V1.4.0.

gulp.src(paths)
  .pipe(
    gulpServerIo({
      serverReload: {
        dir: '/path/to/where/your/server/side/files',
        config: {verbose: true, debounce: 1000},
        callback: files => {
          // perform your server side restart
        }
      }
    })
  )

This is a separate watcher module expose to allow you to watch your server side files changed (or anything you want to watch). Internally this is execute in a different process. the minimum config is provide the dir and callback option. Where dir is where the path to your directory you want to watch. And callback is what you want to do when files change, it will also pass you an array of the files that changed.

CLI

You can also use it as a cli tool if you install this globally. Please note we switch to meow instead of yargs from 1.3 so the option will be different.

  $ npm install gulp-server-io --global
  $ gulp-server-io /path/to/your/app

This will quickly serve up the folder you point to and use gulp as engine. So you get all the default setup just like you did with gulpfile.js. You can also pass multiple folders

  $ gulp-server-io /path/to/your/app,node_modules,dev

There are several options you can pass as well

• host (h) default localhost, if you need to broadcast then use 0.0.0.0
• port (p) default 8000, change it to the port you need
• config (c) default undefined, this allow you to point to an JSON file with the same configuration parameter available for the gulp-server-io

If you need to see all the options an examples

  $ gulp-server-io --help

If you need more option then you should set it up as a regular gulpfile.js

Deployment

Using the server as a quick deploy server option

By default using this standalone server will disable the following:

• open: false
• reload: false
• debugger: false

Unless you pass development:true as option.

const server = require('gulp-server-io/server');
// by default when you use this `server` it will set the development flag to false
// And it will disable `open`,`reload`,`debugger`
// the folder is <YOUR_APP_ROOT>/dest
server();

More elaborate setup:

const server = require('gulp-server-io/server');
const { join } = require('path');

server({
  webroot: join(__dirname, 'build'),
  port: 8800,
  indexes: ['amp.html'],
  proxies: [{
    source: '/api',
    target: 'http://localhost:3456'
  }]
});

Full configuration properties

| Property name | Description | Default | Type | | --- | --- | --- | --- | | development | A toggle flag | true | Boolean | | host | Host name or ip address without the http:// | localhost | String | | path | tailing | / | String | | webroot | Where your files need to serve up | ./app | Array or String | | fallback | when 404 where to fallback to | false | Boolean or String | | https | Use secure or not @TODO | false | Object | | open | automatically open browser | true | Boolean or String | | callback | A function to execute after the server start | () => {} | Function | | headers | extra headers to pass | {} | Object | | proxies | Array of proxies { source , target } | [] | Array | | mock | Create mock REST API using json-server | false | Boolean or String | | debugger | Socket.io debugger | true | Boolean or Object | | inject | inject file to the html you want | false | Object | | reload | detect files change and restart server | verbose:true,interval:1000| Object | | serverReload | A seperate watcher module to watch your server side files | TBC | Object |

Please see wiki for more information about all the available options.

You can combine with our generator-nodex to create a nginx and systemd files.

License

MIT © Joel Chu [email protected]