Define main as the entry-point files, one-per-filetype

[desandro]

To resolved bower/bower#935 once and for all.

I've added example file structure and explanation.

Feedback welcome! This is a difficult thing to explain to novices.

[sheerun]

Maybe we should also note that each entrypoint specifies both main file and loadpath.

e.g. dist/js/component.js specifies that dist/js/component.js is main asset and dist/js is load path.

It's similar to how require.js defines work. That's how I think about it at least.

[desandro]

Hmm, what does the load path do? It sounds like this is specific to module loaders.

[sheerun]

When I say load path I mean something like location of packages configuration from RequireJS.

For example "main": "src/index.js" for mout component specifies main manifest name as index.js and load path as src. This is more or less equivalent of configuring require.js in following way:

require.config({
    baseUrl: "/bower_components",
    packages: [
        {
            "name": "mout",
            "location": "mout/src",
            "main": "index.js"
        }
    ]
});

It means that:

• require(['mout'], ...) will require /bower_components/mout/src/index.js
• require(['mout/object'], ...) will require /bower_components/mout/src/object.js

The location is what I call "load path" of package, and main is what I call "manifest name".

This "load path" also exists in other module systems. For example load_path in SCSS.

Load path is core idea of many module systems, and bower probably should account for that.

[desandro]

Thanks for clarifying. I hear you that its an important concept, but I'm not sure if its worth documenting here. Load path might be treated differently for different module loaders.

[kim3er]

Per filetype would be amazing.

[cvrebert]

I would appreciate it if the example could also include font files and a compiled CSS file, for completeness.

[desandro]

@cvrebert Good call. I'll update shortly.

---

Making a note to reach out to tool builders

• Wiredep
• Brunch

[sheerun]

@cvrebert Font files and images can be referenced as relative paths in CSS files. There's no need for including fonts in main field. Especially there are like 6 formats of them.

[cvrebert]

@sheerun Yes, that's fine, I just want the example/spec to be extremely explicit about that. We had to do otherwise in Bootstrap (twbs/bootstrap#11296) due to lack of clarity about this.

[donaldpipowitch]

I already said it in other channels, but I'm not a big fan of "one entry-point per filetype". From all proposals I think this is the one which offers the least features and while it is often good to not have a lot of features for complexity reasons I think they are necessary here so Bower is beneficial enough to coexist and be maintained next to npm, because it is more specific to front end code and assets, instead of adding some front end specific logic to npm and package.json itself and drop Bower.

What do we get here?

More than one main file. In npm we typically declare one main file which is mostly a JavaScript file which is fine in server land. With Bower we can now declare more than one main file, because in front end land we often need more than just one JavaScript file for a component like an HTML file or a CSS file.

What do we don't get?

More than one main file of the same file type. I hoped Bower would become the package manager for all front end related code and assets, but this proposal focuses on code which can import its own dependencies if necessary: HTML, CSS and JavaScript (or one of the many languages compiling to one if those). What do I mean with that? We can declare a lib.js as a main file and this file can import other JavaScript files from the same package with ES6 modules, AMD or whatever. Similar a CSS file could @import another CSS file or it can load images and fonts with url(), just like the HTML could contain an <img>. But what is with other front end related assets? Say I would like to distribute a Bower package of several images or a bunch of SVG icons? I can't pass all SVG files to main.
Picking specific files/features. When allowing just one main file for one file type, we would get all animations in a package like http://daneden.github.io/animate.css/. It is not possible to pick just some specific animations.
Declare different release versions. Mostly used for optimized and non-optimized assets like images in different quality versions or minified and non-minified code. E.g. while development we include a regular non-minified angular.js. Thanks to https://github.com/yeoman/grunt-usemin this file will be concatenated and minified with our own scripts. However it would be nice, if usemin could be smart enough to not minify angular.js itself, which can be time consuming for many dependencies, because Angulars Bower package ships with a minified version, but there is no way to tell the bower.json about that.
Path templates for "alternative versions" of a package (e.g. for i18n). In server land this isn't a problem, but for front end land we often need a specific component in different similar versions, mostly for i18n. Say we have a <custom-select> component with labels like Please select... which could be translated to Bitte wählen.... It is often not desirable (for performance reasons or if JavaScript is disabled/throws an error) to dynamically choose the right translation at runtime (like this: <custom-select lang="de">). Maybe the translation files are really big and we don't want to release translations for 100 languages, if we just use one. For cases like this it would be great if the path to a main file could look like /dist/select-{countryCode}-{languageCode}.html and allow tools like wiredep to integrate mechanisms to resolve these paths. Sounds exotic? That's why https://github.com/angular/bower-angular-i18n/blob/master/bower.json doesn't have a 'main' file and we precompile our HTML like this:

  <!-- build:js app.js -->
  <!-- bower:js -->
  <script src="angular/angular.js"></script>
  <script src="angular-animate/angular-animate.js"></script>
  <script src="spin.js/spin.js"></script>
  <script src="angular-spinner/angular-spinner.js"></script>
  <!-- endbower -->
  <script src="angular-i18n/angular-locale_<%= locale %>.js"></script>
  <script src="app.js"></script>
  <!-- endbuild -->

[cvrebert]

Please also clarify whether globs are allowed (the answer presumably being "No" under this proposal).
(Refs #30)

[desandro]

@donaldpipowitch Thank you for this input. You raise several good issues. The larger issue that we're addressing here is how main is currently not well defined. This has lead to disarray and confusion across lots of projects. I'd like to fix main with this specification, then address the subsequent issues it may cause, like the ones you have mentioned. Adding a new property like files or dist may resolve these separately.

[donaldpipowitch]

Sounds good +1

[cvrebert]

This looks great now.

[cvrebert]

@desandro So, what's blocking this now? The brunch and wiredep responses in the above issues sound neutral to positive; no rejections.

[desandro]

Merged. I'd like to add a separate page on bower.io for bower.json spec. I've opened bower/bower.github.io#133 to track progress on that.

[ezraroi]

yes, this is what happened

[donaldpipowitch]

Sorry, I don't see why a CSS file violates the spec...? Maybe you don't want a CSS and Less file, but CSS should be okay...?

[cvrebert]

@donaldpipowitch Yes, the difficult case is distributing a precompiled CSS file alongside its Less/Sass source.

[cvrebert]

@ezraroi On the Bower side, I think the right way to address it is probably to spec something like #21.

[desandro]

To address recent issue with Wiredep, I've proposed a new field files in #47. Your thoughts appreciated so we can cure these hiccups 🐳

[calidion]

Maybe as a novice, I don't understand the necessity of one file per type for main entry in bower.
bower packages are not executable, one file per type rule doesn't seem necessary and breaks previous rules.