pluginBuilder doesn't carry through for wrapped plugins

[guybedford]

I have a requirejs plugin in the following folder structure -

js
-plugin
--plugin.js
--plugin.server.js

plugin.server.js is the pluginBuilder property in plugin.js.

I'm using a relative path to specify the pluginBuilder that looks like:

pluginBuilder: './plugin.server'

To allow for using the simpler syntax, 'plugin!...' in the project, I have a wrapper module in the base js folder of exactly the same name to allow the relative path to remap properly.

When I do a build, the pluginBuilder is not picked up, and instead the load function is taken from the plugin.js file instead of plugin.server.js file.

Should this work? Or am I doing this the wrong way?

The current fix I have for this is simply to define the pluginBuilder to be a global path of the form:

pluginBuilder: 'plugin/plugin.server'

I can then use a path mapping of the form:

paths: {
  plugin: 'plugin/plugin'
}

without having the breaking of relative paths.

I'd again appreciate advice re the best practice here.

My current feeling is that:
-global paths are preferable to relative paths
-with the above, a paths config is preferable to a wrapper module
-wrapper modules are mainly there as common-js module shims, which may be based on relative paths

My natural tendancy has been to want to think in terms of relative paths. Counter-intuitively it does seem that when performing rewrites, path mappings work far better with global paths than relative paths.

If there was some warning about relative paths somewhere in the docs, it would probably save much frustration all round.

[jrburke]

I think I see the problem:

Relative IDs are resolved relative to a reference module ID, not a reference path. So if you do a paths config for 'plugin': 'plugin/plugin', and the module with the ID of 'plugin' references a relative ID named './pluginBuilder', then the relative ID is resolved to 'plugin/./pluginBuilder' which is just 'pluginBuilder', so it will not match the paths mapping.

If you instead use the map config and specify:

{
    map: {
        '*': {
            'plugin': 'plugin/plugin'
        }
    }
}

then I believe it will work as expected.

I did not follow the part about 'wrapper modules', but hopefully the above sorts out the issue.

Also note that in r.js 2.0.2, there is a stubModules config that allows just writing out a simple empty stub module for the plugin if it inlines its resources completely and does not need to be used after a build. In that model, the plugin is used in runtime dev and in a build, but then just s simple shell after the build.

Of course if your use case is that the plugin does special things only in a build context then pluginBuilder is the way to go.

[guybedford]

Thanks. I haven't worked that much with file system intricacies in the past, but surely the path:

'plugin/./pluginBuilder'

should resolve to

'plugin/pluginBuilder'?

[jrburke]

oh sorry, bad explanation. I mean that './pluginBuilder' is resolved relative to the parent ID segment for 'plugin', which is just '', so it resolved to the absolute ID 'pluginBuilder'.

[guybedford]

Ahh ok.

If the plugin has a dependency to say './library' (a js file), then that path would be resolved relative to 'plugin/plugin' not 'plugin'.

I don't quite see why the pluginBuilder should then behave differently in this case?

[jrburke]

If your config looks like this:

paths: {
  plugin: 'plugin/plugin'
}

and plugin/plugin.js looks like this:

define(['./library'], function (lib) {});

and that module is loaded as require('plugin'), or as a dependency ID of 'plugin', then './library' is resolved relative to 'plugin', not the paths value of 'plugin/plugin'. Relative module IDs are resolved relative to other module IDs, not their paths.

The "map" config mentioned though should do what you are looking for.

If it does not work like I just mentioned, then maybe I misunderstood the example, or maybe there is a bug, but the above is how it should work.

[guybedford]

This issue is seen without the above paths config. Rather I'm using a "wrapper module" of the form:

plugin.js:

define(['plugin/plugin'], function(plugin) {
  return plugin;
});

[guybedford]

My sincere apologies for wasting your time, I've just realised this makes complete sense.

A wrapper module becomes the new module. So it is as if the full object is defined at 'plugin'. So obviously the pluginBuilder is relative to this folder.

To be honest, I'm just going to stick with global naming from now on to avoid this type of situation entirely.

Thanks as always for your prompt responses!

[jrburke]

The relative module ID thing is tricky to get a handle on, and it is something new for a bunch of people. In some ways I wish it was easier, because there are questions about it from others.

However, it exists for a good reason. Namely for build artifacts, where it would not make sense to base things on paths when modules are all in a combined file, it only makes sense to be about module IDs.

Maybe it is just a cost of a module system that has combined/built artifacts, which does not have an analog for other modules systems in other languages. I guess Java and zipped/jar files are somewhat analogous.

[guybedford]

Certainly the way relative moduleIds work takes some thought, but it definitely makes a lot of sense.

As I mentioned in the initial post - I'm entirely moving over to global paths to avoid these issues. The intuition is that relative paths should be more flexible and a better way of going about things. But it seems this is not the case. Advising others that global paths are the way forward would still save much frustration.

[jrburke]

Relative paths are more flexible, and more portable, so I do not want to suggest favoring globals. When using in this case, where you want to use a shorter name for the plugin, it would mean documenting to users how to set up the config to get the desired resolution. Some cases would use paths but this one would use map to get the desired behavior. But for projects that are just for your own consumption or where you know the use cases, absolute paths are certainly usable.

[guybedford]

Thanks so much for the update here.

I didn't realise map solved the problem with relative paths entirely. That makes for a very elegant, flexible setup!

[guybedford]

I'm reopening this as part of work on the amd-loader plugin helper (name change v2!).

My debugging took the following steps:

1. I have two files, cs.js and cs-builder.js both dependent on amd-loader. So I make a folder, cs and add them in there.
2. In order to just have a simple require require(['cs']); instead of require(['cs/cs']); I have the usual decision of using a map config or a wrapper module. I go with a wrapper module at cs.js which points to cs/cs.
3. I no longer have the pluginBuilder functionality!

So I:

1. Use a map config instead. But now my plugin builder relative path is double mapped to cs/cs/plugin-builder.js.

It's difficulties all around.

I'm currently really into wrapper modules because they allow configuration injection as well, providing a natural configuration modularity solution.

So I'd really love for this to work.

My suggestion would be to include a basic "wrapper module" check when using the pluginBuilder. That is, a regular expression that can spot a define of the form:

  define(['some/module'], function(module) { return module; });

If that is detected, then rather seek the plugin builder property in 'some/module'.

It would just be one regular expression check!

Please let me know if I can work on this myself, would really appreciate having this as many plugins need plugin builders, sit in folders, and shouldn't need to be configured with map configurations this is invaluable in decentralising configurations.