express-package

Express Package

Prepares an ExpressJS project for deployment using webpack

• Package your express application into a single and minified file. It will provide you with a suggested configuration, which you can use on webpack config

• You will need to configure webpack separately, but we suggest using the websdk

• Packaging can allow usage of ES2105 even on old environments (aka 0.10.x) which is now be some what common due to dependencies, company policies for updating, risk of upgrading, etc. It does it through transpilation, using babel.

• Perform installation of the minimum dependencies (the ones that use binaries or dynamic requires)

• Copy files over to the deploy directory (configurable)

• Builds whichever is your ExpressJS server you can exlude some dependencies if needed

[Suggestion] Express GUI

Before you start packaging you server. You should consider also using express-gui samples to setup your server, it demonstrates how to use conf-stack and delay-debug

How to install

Install through npm

npm install express-package
npm install websdk // For sample purposes, you could use standard webpack

Basic sample using websdk

By default it will try to create a directory deploy next to the script that runs that triggers directly/indirectly the build. You can override this.

• Sample is building the public code and server on different scopes (command flag --scope)
• Sample assumes you have a structure
  • deploy // This will automatically be created after server build
  • tools
    • build.js
  • server.js // Your ExpressJS server

Create build.js file

./tools/build.js

var
  expressPackage = require('express-package')
  ,buildFactory  = require('websdk/build')
  ,build         = buildFactory( __dirname, function(){
    console.log('Built..') 
  })
;

// =========== It is possible to modify the way the build works, we will get the defaults for now
// // Set where we are serving the artifacts from
build.config.output.publicPath = '/';
delete build.config.entry.start; // Remove the start for now

// Disable the clean
build.config.websdk.disableClean = true;
// ============

var
  buildPublic       = !!(~build.scope.indexOf('all')||~build.scope.indexOf('public'))
  ,buildServer      = !!(~build.scope.indexOf('server'))
;

// Set the entry point (you could have multiple, depending on how many segments
// you have on your app, they can be only libraries that attach themselved ot the running app)
if(buildPublic) build.config.entry['public-app']  = __dirname + '/../app_modules/public-app/public-app.js';

// When the scope is to build the server
if(buildServer) {

  // The directories to use for server build
  var 
    baseDir = __dirname + '/..'
    ,options = {
      dirs: {
        deploy : baseDir + '/deploy' // Diretory to dump the build into
        ,copy  : [] // The directories to copy, suggested ['conf','db','gui']
          .map(function(it){return baseDir + '/'  + it;})
      }
      ,dependencies : null // If [], would override expressPackage.dependencies
      ,externals    : null // In [], would override expressPackage.externals
    }
  ;

  // Alter the build for a server build, which will also create the deploy directory
  expressPackage(build, options, function(suggested){
    // If all went well we will build the server
    build.config.entry['server'] = __dirname + '/../server.js';

    // Use the suggested config
    // If you see errors when building like:
    // -- SyntaxError: Unexpected token m
    // -- Critical Dependency
    // Just add the dependency causing it to to externals build.config.externals.push('blah-dep')
    // You might also need to add it to options.dependencies
    build.config.output.path          = suggested.output.path
    build.config.output.libraryTarget = suggested.output.libraryTarget
    build.config.target               = suggested.target
    build.config.externals            = suggested.externals

    build.run();
  });
}

// Run the build
if(!buildServer) build.run();

Create server.js file

./server.js

var express = require('express');
var app = express();

app.get('/', function (req, res) {
  res.send('Hello World!');
});

app.listen(3000, function () {
  console.log('Example app listening on port 3000!');
});

Trigger the build

Run node tools/build.js --od ./deploy --scope server,others,possible

Suggestions

Use the express-gui samples to setup your server:

Add to your package.json

  "scripts" : {
    ...

    "build:server"        : "node tools/build.js --scope server"
    ,"build:watch:server" : "node tools/build.js --w --scope server"
    ,"build:dist:server"  : "node tools/build.js --scope server --env prod"
    ,"build:raw:server"   : "node tools/build.js --scope server --devtool="

    ...
  }

FAQs

• What is expressPackage.dependencies? Dependencies to install into deploy directory, and they should be added to expressPackage.externals

• What is expressPackage.externals? Dependencies which when require('depblah') they can be ignored, either because they will actually be found (expressPackage.dependencies installed them) or because that scenario of require will never happen

• I use mongo/sequelize, how do I work with them? You might not be able to bundle them, you can add them to expressPackage.dependencies, and to expressPackage.dependencies in order to ignore them. expressPackage.dependencies.push('sequelize@3.23.0'), expressPackage.dependencies.push('sqlite3@3.1.3'), and you might want to add them to expressPackage.externals

• Why is it installing "X"? Its kinda common, you can remove it with expressPackage.dependencies = expressPackage.dependencies.filter(function(it){ return !it.match(/X/) }), where X is a dependency you don't need installed

• **Why is it excluding ./db? Sorry, opnionated on this one. The ./db configurations usually are dynamic in terms of loading the models, remove it with expressPackage.externals.pop()

• Can I override all externals/dependencies? Yes. Pass them as properties of options, look at sample code above.

• Can I add more dependencies? Yes. expressPackage.dependencies.push('blah@x.x.x')

• Can I add more externals? Yes. expressPackage.externals.push('blah@x.x.x')

• What are externals? Read the webpack documentation regarding externals https://webpack.github.io/docs/library-and-externals.html

• Can you make the deployment a single binary? Maybe in the future, but this seems intresting: http://www.jedi.be/blog/2013/05/14/Compiling%20-%20packaging%20a%20nodejs%20project%20as%20a%20single%20binary/