Build tool extensions

[josh]

Basically, an alternative and more extensible format to the "moduleType" property proposed in #10.

{ "name": "jquery",
  "main": "jquery.js",
  "amd": {
    "main": "jquery-amd.js"
  },
  "es6-module": {
    "main": "jquery-es6.js"
  },
  "imports": {
    "main": ["jquery.html", "jquery.js", "jquery.css"]
  }
}

Instead of simply just declaring a moduleType, packages can declare a nested set of overrides. If the build tool is intended for AMD, it will prefer an amd.main value, otherwise fallback to the top level main.

Right now main is the only interesting property to build tools. Others could be introduced in the future and this format would support them.

I feel like the spec should list out a set of suggested "extension types" based on the use cases we've already seen.

• amd
• cjs or commonjs (probably the latter)
• es6-modules
• imports HTML import / web component style

/cc @robdodson @rpflorence @joliss @briandipalma @wibblymat @paulirish @benschwarz

[briandipalma]

This looks like an excellent idea to me, I guess main is global script by default? Pity that it might be a hassle in future when more and more packages are purely ES6 modules and they will all have to specify the es6-module key...and I guess the main key will be empty?

[josh]

Pity that it might be a hassle in future when more and more packages are purely ES6 modules and they will all have to specify the es6-module key...and I guess the main key will be empty?

I don't think root main should strictly imply global script. If the package is AMD only or ES6 only, you should just declare root main. This would mean initially packages should use root main for global scripts and add an override for ES6 modules if they want to add transitional support. When the day comes they don't care about global exports, just drop that file and move ES6 main into root main.

I think that approach always gracefully to some script the build tool can work with.

Also, given that AMD and global exports can safely coexist, you might just need one root main. But it gives package maintainers 2 options. Just have one file like:

if (typeof define === 'function') { ... } else { window.Foo = {} }

{
  "main": "foo.js"
}

or

// foo.js
window.Foo = {}

// foo-amd.js
define(Foo)

{
  "main": "foo.js",
  "amd": {
    "main": "foo-amd.js"
  }
}

[benschwarz]

I don't think root main should strictly imply global script. If the package is AMD only or ES6 only, you should just declare root main. This would mean initially packages should use root main for global scripts and add an override for ES6 modules if they want to add transitional support. When the day comes they don't care about global exports, just drop that file and move ES6 main into root main.

Agree.

I'm not sure how likely / realistic it is to think that one package will support multiple module types — Does anyone have a few handy examples up their sleeves for us to learn from?

[josh]

one package will support multiple module types

I've already mentioned AMD. I'm personally interested in use this for the ES6 module case since at the moment, ES6 modules can only be used with the ES6 syntax. Theres no way to make a pure ES3 .js file that supports global exports and module exports. Honestly, I'd love to see ES6 modules expose some ES3 runtime define hooks, but thats a different discussion.

With this, I'd probably development more of my packages ES6 style, and use a transpiler and check in the global export and AMD versions of the module. Its a little more work on my (the package maintainers part) but makes it more pleasant to users and whatever build tools they are trying to use.

Alot of this does feel transitional to me, but at the same time pretty important to ES6 modules being adopted in the first place.

HTML imports are another case. Its still unclear if they will converge with ES6 modules or not.

[joliss]

In general, it seems that having a single main file is not enough (and it's also not clear what name it should be referenced by). A more general implementation would probably be a lib directory ("mainDir"?) that contains multiple files (see rsvp's lib directory for an example of this).

I haven't looked at the original proposal enough to have an opinion, just wanted to throw this in. :)

[MajorBreakfast]

Thanks @josh for starting this discussion!

Basically a build tool differentiates between three file types:

• files that need to be copied 1:1 (e.g. fonts, images)
• files that are imported through other files and are then concatenated (es6 javascript, css, scss)
• files that can be ignored

I'd like to see a separation between the copied and imported files. If we do it just by file type we can't specify a JavaScript that gets copied. This kind of information is important for a build tool like ember-cli.

My proposal:

{
  "main": "deprecated",
  "imports": {
    "js": "script.es6.js",
    "js-amd": "script.amd.js",
    "js-common-js": "script.common-js.js",
    "js-global": "script.global.js",
    "css": "style.css",
    "scss": "style.scss"
  },
  "files": {
    "fonts": ["..."],
    "images": ["..."],
    "...": ["..."]
  }
}

Reasons for a structure like this:

• deprecation of main key and introduction of new keys for backwards compatibility
• "js" instead of "js-6" signals that that's eventually the way to go. Also there won't be a problem if ES7 comes along :)
• "files" is also a hash. If you specify assets/pictures/ for the images in your build tool, then the items specified in the "images" array of the package some-package get copied to assets/pictures/some-package/. We should standardize some keys otherwise this becomes a mess.

Also I'd like to mention the paths problem for copied files. The bower_components/ folder is often named differently. Relative paths take us a long way but not quite far enough. We could standardize a way in which a build tool replaces paths so that we can know where other parts like images can be found. (text replace, mustache syntax?) Of course this is just a related problem.

I made this all up just now. But I wonder whether you like the ideas I propose.

[sheerun]

@guybedford What do you think?

Afaik https://github.com/systemjs/systemjs is able to:

1. Recognize type of javascript main file (amd, commonjs, etc.)
2. Wrap it with code that integrates with other build systems (so amd can use commonjs etc.)

That means one main javascript file and optional type annotation as in #10 is just enough. Right?

[josh]

Theres no way to make a pure ES3 .js file that supports global exports and module exports. Honestly, I'd love to see ES6 modules expose some ES3 runtime define hooks, but thats a different discussion.

I need to retract part of my statement, since @guybedford's System.register can help accomplish this.

[guybedford]

@sheerun SystemJS still allows for format hints, because format detection can never be 100% accurate. For example in UMD patterns, we prioritise ES6, AMD, CommonJS and then globals in that order. To enforce something as a global can still be useful despite it being detected as AMD.

In this scenario, jspm provides a package.json format property, just like the Bower moduleType.

There is only one format per package though, because typically you want to read all of the modules of a package in just one way for jspm.

But for Bower, which is consumption format agnostic, I suppose the question is simply how deeply to attempt to solve these problems. One the one hand one can argue for simplicity, and keeping what Bower does to a minimum. On the other hand one can argue for fine-grained control like this proposal, which will certainly be useful to tool authors. Perhaps it is a good idea to explore these spaces some more.

I really don't know though!

@josh I hadn't actually considered it, but I suppose System.register can allow the extension of UMD patterns to ES6!

[josh]

@guybedford I really love the direction you are taking jspm. We should totally get stuff standardized (or at least a community convention) for the extra metadata you need for jspm to load bower.json packages.

[guybedford]

@josh many thanks, still a lot of hard work to go on it. The ability to know which module format / formats a package is written for would be the most immediately useful meta information (amd / cjs / global / es6). Perhaps we should also consider using es instead of es6 so we're not versioning the module system!