HY-hugh / gulp-server-io

This is a complete rewrite from ground up version of gulp-webserver-io

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

Introduction

This is a complete rewrote of the gulp-webserver-io; there are many improvement over the previous version.

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

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:

// gulpfile.js  
// We have include the Gulp 4 with this package and expose it back as well
const { gulp } = require('gulp-server-io/gulp');
const gulpServerIo = require('gulp-server-io');

gulp.task('serve', () => {
  return gulp.src('./app')
             .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.

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:

  $gulpServerIo.debugger(msg);

You an pass just a full string to the method. Or you can pass an object which produce nicer output:

• from - you defined where that coming from
• msg - you can pass error object, array or whatever
• color - the color available in chalk

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: {
            enable: true,
            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 code:

  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.

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

const server = require('gulp-server-io/server');
// by default when you set development to false
// the folder is <YOUR_APP_ROOT>/dest
server({
  development: false
});

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	false	Boolean
open	automatically open browser	true	Boolean or String
indexes	Array of indexes to search	[index.html, index.htm]	Array
callback	A function to execute after the server start	() => {}	Function
staticOptions	Look at server-static	{}	Object
directoryListing	Look at server-index	false	Boolean
headers	extra headers to pass	{}	Object
proxies	Array of proxies { source , target }	[]	Array
devKeyPem	When you set https to true you can supply your own pem file	cert.pem	String
devCrtPem	Same as above, supply a crt file	cert.crt	String
mock	Create mock REST API using json-server	false	Boolean or String
debugger	Socket.io debugger	true	Boolean or 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 © NEWBRAN.CH & to1source