insertRequire=main should be sync or should have a sync option

[kosta]

Hi!

I want to create a public library that uses require.js and exposes a public API (for those non-require.js users).

Currently, I have to use those ugly start.frag and end.frag options, in which all I do is require('main'). However, those are not jslint'able and weird to read.

I would love to use insertRequire=main, but that would do require(['main']), which is async (and which doesn't make any sense for almond.js).

So my proposal:

• Either a) make insertRequire=main insert a require('main')
• or b) provide a forceSync that makes all insertRequire options sync
• or c) provide a insertSyncRequire=main option

As this change would actually be in require.js and I'm not sure how and where insertRequire is used by different people, option b) or c) is probably the safest.

If you would consider merging it, I would try to create a patch for require.js to accept a forceSync or insertSyncRequire option. Just say what you think is best :)

Thanks in advance for your time and efforts!

Cheers,
Kosta

[jrburke]

The way to do this is with the wrap options. By naming them with .frag then hopefully they would not need to pass through your js linter. Also, normally for these kinds of libraries that expose a different API after building, more work needs to be done than just a sync require() for it with almond -- normally a browser global needs to be set up too. So the wrap options are a good place to put those.

So closing as wrap is the place for this. Feel free to continue discussion here though.

[kosta]

Hi!

Yes, that fragment stuff works but I consider it kind of ugly and hard to follow: You basically need to read two files simultaneously and "know" what going into the middle. I know these fragments are easily exluded from jslinting/jshinting, but maybe I want to to hint and lint it, just to be on the safe side? :)

Furthermore, I want to export multiple libraries from the same code base: One "complete" one and one that only exposes a small subset. For that, two sets of fragments would be needed.

I think I found a better solution that works well and does not need any code changes, neither in almond nor require.js:

Instead of these fragments you simply define a "public export" module that depends on almond.js (and whatever you want to export). You can do your if (typeof define === 'function' && define.amd) magic there if you want to (you don't even need to do namespaces, see below). The important part: After you "public export" module definition, you do one sync require of the "public export" module definition. (If you use namespacing, use the namespaced version here).

Example for a module that exposes the "blink" library:

blink-exporter.js:

define(['almond', 'blink'], function (almond, blink) {
    "use strict";

    //expose to global window object only if there's no requirejs
    //reference window.define here so that optimizer doesn't namespace it
    if (typeof window.define === 'function' && window.define.amd) {
        //there is a require.js outside of this namespace, re-export blink module to it
        window.define('blink', function() { return blink; });
    } else {
        window.blink = blink;
    }
});
require('blink');

This works using e.g.

node r.js -o baseUrl=. name=blink out=blink.min.js wrap=true

If you use namespacing (which is not necessary), the sync require('blink') would need be changed for namespace.require('blink');

Maybe it's just me, but I find this much more require.js-y than the fragment files. I must say I really like it.

If you like this approach, too, I can prepare a pull-request to document this in the readme.md.

Thanks in advance for your time & efforts!

Cheers,
Kosta

[kosta]

Sorry, the last line of code above should have been

require('blink-exporter');

[jrburke]

If that works for you, great, but it is still a separate file to consult. I also feel a bit uncomfortable treating almond as a dependency. i suppose you could dump the name arg and do include=almond,blink-exporter and that may be enough. And you will want to change the window.define usage to just define so that you get the local almond define and not a different, global one.

[kosta]

Hi!

Thanks for your reply!

Yes of course the exporting needs to be a separate file - I don't think there's a good way around that. But at least it's just one file and it's just plain normal JavaScript and not just "fragments". I think this makes the "export logic" much more obvious and you don't need to understand require internals to grasp it.

Whether you name almond as a dependency in the js file or use include=almond,main=blink-exporter or use main=almond,include=blink-exporter is mainly a question of style. The only real difference I see is: if you want to export multiple libraries, the "in-file" approach and include=almond have the advantage of being able to specify multiple main files to optimize, so you only need one invocation in your build system.

About window.define vs plain define:
The whole point of blink-exporter is to export the blink module so that it can be used outside of the wrapped IEFE (we have wrap=true so we don't pollute the outside namespace). define and require relate to the local almond functions. window.define and window.require relate the the global namespace where we want to expose the blink library (either using the global require.js if it exists, or the plain window global namespace otherwise). That's what the if (typeof window.define === ...) is all about :) Does this make any sense?

Again, if you think this approach is worth being exposed to more users, I'd be happy to write up some documentation for the "Exporting a public API" section in the readme.md.

Thanks for your time and efforts!

Cheers,
Kosta

[jrburke]

The window.define use means the r.js optimizer will not find that define definition, and will attempt to insert a new one if that file is then used inside a project that just uses that built file as a dependency. It also means that this file cannot be nested in a wrapped build of that project -- the window.define breaks out of that nesting. So I still prefer the use of a UMD pattern injected via the wrap args to give it the most flexibility as far as subsequent embeddings.