Can you please improve Configuring Packages for jspm article a bit?

[adriatic]

Tried to install Bootstrap from npm registry: note the failure

Main entry point not found for npm:bootstrap@3.3.5

I read the Configuring Packages for jspm article a few times, but could not make a bet that I understood the details I would need to resolve my issues (see below). In particular it seems strange that jspm wold seek for the main entry point in npm:bootstrap@3.3.5 ?? I used bootstrap thousands of times before jspm became available and was never asked to set "main" to false.

I am not at all implying how this is an unnecessary setting - I would just love a reference to an existing article that explains the need for it.

It would also be nice to see the explanation on why fetching the bootstrap package from Github (github:twbs/bootstrap) does not result with this issue I am dealing with :-)

jspm install npm:bootstrap

 warn Running jspm globally, it is advisable to locally install jspm via npm install jspm --save-dev.
      Looking up npm:bootstrap
      Updating registry cache...
      Downloading npm:bootstrap@3.3.5
      Looking up github:jspm/nodelibs-fs
      Looking up github:jspm/nodelibs-process
      Looking up github:jspm/nodelibs-path

 warn Main entry point not found for npm:bootstrap@3.3.5.
      Adjust this property in the package.json or with an override, setting "main": false if this is the intention.

      Looking up npm:process
 ok   Installed github:jspm/nodelibs-path@^0.1.0 (0.1.0)
      Looking up npm:path-browserify
 ok   Installed npm:path-browserify@0.0.0 (0.0.0)
 ok   Installed bootstrap as npm:bootstrap@^3.3.5 (3.3.5)
      Installed Forks

                                 npm:core-js 0.9.18 1.1.1

      To inspect individual package constraints, use jspm inspect registry:name.

 ok   Install complete.

[guybedford]

It's advisable to use the jspm-configured bootstrap at jspm install bootstrap, which will use the github:twbs/bootstrap repo.

This warning is mainly shown to indicate that the package isn't already configured for jspm, and that things will likely not work correctly. Generally as a user you want to stick to packages that are jspm-compatible, which don't show warnings like this.

Whether we should use the github or npm version of bootstrap as our main suggested source is a discussion that is also important to have as well.

[adriatic]

Clearly I need to reach at least level of understanding this whole complex animal that is 50% of yours - in order to be able to converse with you.

For example: what has the warning Main entry point not found for npm:bootstrap@3.3.5 to do with the assessment that this package is not ready for jspm? When if ever is it expected that "libaries" have main entry point?

I believe that you are doing something very valuable that I need in my role as Application Developer a lot. I also see that jspm issues are on the top of the list of questions in the Aurelia World, so I am interested to help you as much as you can provided that you can teach me how to fish.

By using the fishing metaphor, I am mean this:

1. I will comb with the fine tooth everything that is exposed at http://jspm.io/ and report to you all situations that seem confusing
2. You will do your best to comments / explain my reports, so I do not get stuck waiting for your guidance.

Interested?

[guybedford]

@adriatic thanks for this offer, it is very much a need to have better information available as you can tell, but it is not something I can personally prioritise beyond the bare minimum currently as I need to keep my own maintenance overheads down to focus on ensuring project convergence and stability.

So efforts to improve the learning curve and approachability of the project are incredibly welcome. I will always consider documentation PRs, provided they align with the goal of keeping documentation maintenance to a minimum.

I'm more than happy to discuss details of the project that are unclear, and ensure I will respond promptly, but can't guarantee I will be able to personally fix every documentation issue given a report.

For the Bootstrap overrides issue, it might help to go a step back a bit first. A really important principle of package installations with jspm is that each package should have a single primary source that is used by others (github:twbs/bootstrap for example). github:twbs/bootstrap and npm:bootstrap are two separate packages as seen by jspm, not the same package. This is the problem of many registries. When dealing with many registries, the idea here is to give a choice to the publisher to choose who they trust to distribute their code, not to the consumer who they want to install from, just like picking a website host is the domain of the content provider. Packages can switch to a different registry if they like, with redirects being possible to leave behind.

Because of this principle of a primary registry, we use the jspm registry itself to store simple aliasings of packages to their location in registries. The registry file is just the JSON object at https://github.com/jspm/registry/blob/master/registry.json. So when I type jspm install bootstrap it will look this up there and point me to the same install as if I'd written jspm install github:twbs/bootstrap.

That is, twbs/bootstrap is seen as the primary jspm install location for Bootstrap.

The question then is how do you know if you're using the right install location for a package? This is where the warnings come in. If I'm getting warnings about package configuration from jspm, that probably means this isn't the best package to use. If it was, one would hope that others would have already silenced these warnings for you by adding an override to the jspm registry that ensured the configuration was all correct in jspm for that package. Seeing warnings is an indication that no one before you has taken the effort to configure this package properly for jspm.

This is where overrides as a public service comes in - the registry only converges and packages only work if users share their package configurations to make things work, which then get checked into the registry as well, or ideally even the package.json of the original package.

This entire overrides process is about adding configuration to existing packages that were never designed to run in jspm, so need extra metadata for jspm to understand them. Sharing this metadata is crucial to making jspm run smoothly. That is the ideal, but most users don't do this - and making this process easier and more intuitive is one of the biggest known flaws in jspm currently.

As for the meaning of the main property itself that just means that import 'bootstrap' will become import 'bootstrap/main-entry-point-name.js'. It's usually advisable to have that so users can import packages by their name, without having to know a file subpath within the package to use.

Hope that provides some insights. Apologies if it's still too vast, but there are limits to how carefully I can afford to stop and explain this stuff.

[adriatic]

This specific issue that you so eloquently explained as

As for the meaning of the main property itself that just means that import 'bootstrap' will become import 'bootstrap/main-entry-point-name.js'. It's usually advisable to have that so users can import packages by their name, without having to know a file subpath within the package to use.

is now crystal clear - and the confusion in my mind was caused by the use of the word main - had you used the word primary instead I would not think that the main entry point into my whole application is missing and feel like I am going crazy :-)

I have proposal for you (and I would be happy to help with the whole pedestrian work around this idea): instead of jpms issuing terse warnings in the console output (read: source of all confusion for me) why don't you emit links to the jspm help application that would use these links to explain the situation as verbose as the situation requires.

I am really not looking for more work to do (yesterday I rejected a very respectable job at Facebook for example) - my desire is to help make Aurelia a success, so by transitivity I care to make jspm a success. If I was a king, I would give you the sufficient funding for a staff of 15 - but since I am not (yet), I try to help with resources I control.

[guybedford]

@adriatic this is a great suggestion. I've created both https://github.com/systemjs/systemjs/issues/757 and https://github.com/jspm/jspm-cli/issues/1095 to track such a thing. Any input there is welcome.

And do get back to me when you can arrange that staff of 15 :)

[kylecordes]

Earlier above, @guybedford wrote "Whether we should use the github or npm version of bootstrap as our main suggested source is a discussion that is also important to have as well"

I'm not deeply involved enough to weigh in on the philosophical question here. But here's a practical reason to prefer NPM.

When I help someone get up and running using JSPM, all of the NPM dependencies "just work", but a good portion of the time we stumble over the Github rate limiter and they need to login to Github to move past that. I think that is less than ideal. Consider the Java world - would Maven have become popular if each user had to log in to Maven's repository before downloading or than a small number of packages? I believe it is wise to not create such a stumbling block with JSPM more than absolutely necessary, and for the moment the obvious way to achieve that is to prefer pulling packages from sources that don't require login such as NPM, Bower, Webjars (!), etc.

[guybedford]

@kylecordes thanks, yes this is a known problem users have. Ideally it shouldn't (in general) be an argument for using npm over GitHub though. We're looking at ways to alter the GitHub API in a breaking change. I've created https://github.com/jspm/github/issues/70 to track that idea.

[kylecordes]

Is not clear to me whether Github intends for its API and file hosting services to be used behind something like this. On one hand it seems that the existence of Github Pages is a strong sign that they are happy to host lots and lots of files. On the other hand, the existence of the rate limits (even if the change you mentioned pushes out farther the point at which that problem strikes) hints in the other direction.

[guybedford]

@kylecordes the linked change may be able to avoid rate limits altogether with some luck. GitHub tarballs don't seem to have limits, and the lookup command we use is not limited either for now. Ideally GitHub as a registry should only be used for the packages where source code and published code are the same.