Expose as ES6 Module and as separate files

[tunnckoCore]

... and use unpkg.com for browsers. Most simple thing can be to use Rollup to provide ES6, CJS and UMD bundle.

Mostly, the changes need to be done is:

1. add pkg.module pointing to dist/awaiting.es.js
2. add pkg.main pointing to dist/awaiting.common.js
3. add dist/ (with the slash!) to files field in package.json
4. DON'T add browser field, because Webpack(2) will use it instead of the pkg.module and pkg.main
5. browser users will use that link https://unpkg.com/awaiting/dist/awaiting.umd.js

• add note in the readme that users SHOULD NOT use the https://unpkg.com/awaiting[@version] shortcut, because it will point to commonjs build

6. create lib/index.js file that just exposes the other files
7. not sure how Documentation.JS will handle this
8. Note that it's not required to convert the source to import/export (we'll use plugin for this)

To accomplish this use can use that rollup config

const gzip = require('rollup-plugin-gzip')
const uglify = require('rollup-plugin-uglify')
const resolve = require('rollup-plugin-node-resolve')
const commonjs = require('rollup-plugin-commonjs')

let config = {
  entry: 'lib/index.js'
}

// generate minified and gzipped browser bundle 
if (process.env.BROWSER) {
  config = Object.assign(config, {
    dest: 'dist/awaiting.umd.js',
    format: 'umd',
    moduleName: 'awaiting',
    sourceMap: true,
    plugins: [
      resolve(),
      commonjs(),
      uglify({ compress: { warnings: false } }),
      gzip()
    ]
  })
} else {
  // generate CJS and ES6 non-minified and non-gzipped bundles
  config = Object.assign(config, {
    plugins: [
      resolve(),
      commonjs()
    ],
    targets: [
      { dest: 'dist/awaiting.common.js', format: 'cjs' },
      { dest: 'dist/awaiting.es.js', format: 'es' }
    ]
  })
}

and script for package.json (include npm-run-all dep)

{
  "scripts": {
    "build": "npm-run-all -s build:*",
    "build:node": "rollup -c --environment NODE",
    "build:browser": "rollup -c --environment BROWSER"
  }
}

this will generate

• dist/awaiting.es.js which should be in pkg.module
• dist/awaiting.umd.js which should NOT BE pointed in package.json
• dist/awaiting.common.js which should be in pkg.main

---

As about the tests: 1) will just use the lib/index.js since it is just commonjs, 2) no need to run them in browser so we can remove browserify, it's just enough to ensure which versions of browser support ES6.

---

I can send a PR soon. :) Great job anyway! PromiseFun can be another inspiration :)

[hunterloftis]

Hey, thanks for the detailed issue! What's the end benefit of this change?

[tunnckoCore]

Users will be able to include only needed by better imorts/requires, just like lodash for example. import { callback } from 'awaiting';

[tunnckoCore]

also for cjs const callback = require('awaiting/callback');

[hunterloftis]

I'd just recommend folks do:

const { callback } = require('awaiting')

As ES6 modules are currently not supported by any browser, I haven't made them a high priority. I wouldn't mind supporting them, I'd just like to be sure I understand how end users benefit, & what the total maintenance cost is.

[backspaces]

I'd like to second es6 modules. I've converted my main repo to do the following:

• Convert to modules
• Use Rollup to convert to the many other module formats: iife, amd, cjs, umd.

The workflow for Rollup is near-trivial .. a one-liner for me, I'm mainly creating legacy iife's. And no, I don't use any workflow stunts like webpack, gulp, jspm, ... They are all gone. Only package.json scripts.

And with Safari Tech Preview, I do something we've all forgotten about: I edit a file and then immediately, with no "watch" or other silly workflow, USE the file! How great is That!

I'm sorry that modules are slow coming, but putting dependencies in the code that uses them is such an improvement over <script> tags, miles away from the code needing them seems just silly after experiencing modules.

And finally, do you really want code that starts with this?

(function(f){if(typeof exports==="object"&&typeof module!=="undefined"){module.exports=f()}else if(typeof define==="function"&&define.amd){define([],f)}else{var g;if(typeof window!=="undefined"){g=window}else if(typeof global!=="undefined"){g=global}else if(typeof self!=="undefined"){g=self}else{g=this}g.awaiting = f()}})(function(){var define,module,exports;return (function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);var f=new Error("Cannot find module '"+o+"'");throw f.code="MODULE_NOT_FOUND",f}var l=n[o]={exports:{}};t[o][0].call(l.exports,function(e){var n=t[o][1][e];return s(n?n:e)},l,l.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({1:[function(require,module,exports){

[hunterloftis]

@backspaces I'm 👍 on ES6 modules, I just want to be sure to balance that with maintenance requirements (so it doesn't slow down development on the lib). The top-level instructions here are very clear but also quite large ;)

That said:

1. convert to modules
2. use rollup to automate everything

...sounds simple enough. Is this something you'd be comfortable building a PR for?

[backspaces]

I'm doing something that may be better, maybe: Write about it! (Just had my 75th birthday and decided to write as an Elder Technologist!)

I've asked at least 8 projects to convert to modules. I get very interesting responses! All very honest and revealing, and only a few slightly hostile.

So I've decided to write a couple of articles on the subject using Medium. It will go into the details on how to do this, and gather up a list of projects who have converted or are converting now.

The first article will be on 1 & 2 (with details on creating the "exporter" module). The second will be more on The Legacy Problem for modularized projects .. how to be a module based project with non-module dependencies.

Then I'm going to look into "low hanging fruit" .. projects that are easily converted. Maybe write an article on that as well. I know from experience that the workflow of each project is often an issue .. and that often cloning a git repo and trying to get it working often fails.

[tunnckoCore]

As ES6 modules are currently not supported by any browser

there's no such need. the whole point is to be used as best as possible by the Webpack and Rollup users. it is just enough to convert to import/export and distribute 3 other formats - CJS, ES6, UMD - so all win.

I'd just recommend folks do:

it's totally possible, but idea is another - it's not just because some style preference. it's because users use rollup/wepack because the three shaking (not to mention that webpack's shaking isn't good enough for me)

As about the browser usage, it easily can be umd.

[hunterloftis]

Cool, I'll hook it up with ES6 shortly. Maybe this weekend.

[backspaces]

Don't forget: you can run raw es6 module source right now with Safari Technology Preview .. no flags etc. And Edge apparently but I haven't tried it, don't have a Windows environment. It really is magic to get back to edit/run with NO WORKFLOW! Like in the old days.

…

-- Owen

[tunnckoCore]

It really is magic to get back to edit/run with NO WORKFLOW! Like in the
old days.

Yep. I'm still edit/run and try to not use mega-super-giga latest thing from day one. :)

[backspaces]

I promised an article on converting to modules, and here it is:
https://medium.com/@backspaces/es6-modules-part-1-migration-strategy-a48de0b7f112

I'll try to get a few more stories going but this is the core of a dual build approach and even makes it easy to convert modules w/o browser dependencies into commonJS format so they can be "required" in node! Way nice.