better document main property + stricter rules

[fat]

discussed a bit here: components/jquery#1

I think if passing an array to the main property, it should only accept 1 file per ext type. thoughts about adding console.warn and providing stricter definition around this.

Also, does it make sense to create a more explicit "component.json" spec?

[sindresorhus]

I'm all for stricter rules 🤘

Only accepting 1 file per ext type sounds like a good idea, especially 1 js file, but are there any obvious downsides to this?

I think having a spec for component.json is essential if we want others to embrace it in the future. Maybe even do the same as npm and create a reusable module for loading the component.json?

[paulirish]

+1 on better defined main prop. I myself am a little confused on the best values for it right now. Also knowing how it will be used will certainly help me, and others, understand.

[adamalex]

How should a project similar to Twitter Bootstrap be configured for Bower? It has runtime requirements of two images and two css files in addition to the production js file. Should Bootstrap be split over multiple repos somehow? Or would some additional flexibility to allow more files for situations like these be warranted?

[desandro]

Here's a shot at the spec for main:

main contains a list of the required files for a package to function at its most basic level. These files are listed with bower list, so they can be easily managed and compressed for production together with other package's files.

Keep optional files that provide additional functionality or styling out of main. Bower will still include these files in your package, so users can manually add them to their applications if they so desire.

---

For now, my preference is to keep it lax main's strictness. You should be able to list multiple files of the same filetype. This encourages people to break up their packages source into more files which is a win for encapsulation.

I'm on the fence on whether or not you should have to list JS, CSS, and template files separately like you do in component

[josh]

I don't think allowing multiple files of the same type in main is a good idea.

For me, main implies a reference from the package name and a referenced. This mirrors npm's main intent that requiring that package pulls in that single referenced file.

I don't think bower should be in the business of trying to concatenate peoples scripts for them if they have multiple main files.

Examples

Importing QUnit main's css file - https://github.com/components/qunit

@import "qunit" // references components/qunit/qunit.css

Require.JS with jQuery - https://github.com/components/jquery

require(["jquery"], function($) {
  // references components/jquery/jquery.js
});

With yeoman, the main file is cp'd into your scripts directory, and you can reference it directly.

Multiple files

I think encouraging people to break up files is a good thing, but I think thats a separate concern from the main reference. And I don't think bower is doing a good job of this right now.

Using Modernizr as an example, modernizr.js clearly maps to the main file. But its not clear how all the other feature-detects/ fit in. How would copy installers like yeoman know the difference between that directory or the tests directory.

It also be nice if we could improve the reference logic paths for those file w/o forcing Modernizr into a specific directory structure.

Require.JS

require(["modernizr", "modernizr/canvas"], function() {
  // references components/modernizr/modernizr.js
  // references components/modernizr/feature-detects/canvas.js
});

Yeoman

script references

<script src="modernizr.js">
<script src="modernizr/canvas.js">

In order to have this work in my modernizr shim repo (https://github.com/josh/sprockets-modernizr), I had to put all the files at the root, which is kinda nasty.

Instead of a .bowerignore #88 file, we might want to consider a whitelisting file manifest approach.

{ "name": "modernizr",
  "main": "./modernizr.js",
  "paths": {
    "cors": "./feature-detects/cors.js",
    "css-boxsizing": "./feature-detects/css-boxsizing.js"
    ...
  }
}

[yatskevich]

Regarding "main" property and other ways to export stuff from a Bower package.

Consider Twitter Bootstrap library. One can use just pre-compiled ("main") version:

{
  ...
  "main": [
    "./docs/assets/js/bootstrap.js",
    "./docs/assets/css/bootstrap.css",
    "./img/glyphicons-halflings.png"
  ],
}

or a customized version of it. It'll be very beneficial to support both use-cases.

@josh already mentioned paths for JavaScript files. I wonder whether his solution can be extended to support other assets like LESS/SASS/CSS or images as follows:

{
  ...
  "paths": {
    "js": {
      "affix": "./js/bootstrap-affix.js",
      "modal": "./js/bootstrap-modal.js",
      ...
    },

    "sass": {
      "src": [ "./lib" ]
    },

    "img": {
      "src": [ "./img" ]
    }
  }
  ...
}

In this case it'll be very easy for Bower to distinguish between different asset types and provide accurate information to downstream tools like SASS compiler.

Thoughts?

[yatskevich]

Configs like

{
  "paths": {
    "cors": "./feature-detects/cors.js",
    "css-boxsizing": "./feature-detects/css-boxsizing.js"
    ...
  }
}

or

{
  "paths": {
    "affix": "./js/bootstrap-affix.js",
    "modal": "./js/bootstrap-modal.js",
      ...
  }
}

can be simplified if we add regex support:

{
  "paths": {
    "{module}": "./feature-detects/{module}.js"
  }
}

{
  "paths": {
    "{module}": "./js/bootstrap-{module}.js"
  }
}

[adamalex]

Additional consideration for Bootstrap: a site could easily use both glyphicons-halflings.png and glyphicons-halflings-white.png

Also, for official templates such as the one at http://twitter.github.com/bootstrap/examples/starter-template.html bootstrap.css and bootstrap-responsive.css are included separately with a style block between them to support the template layout. It may be difficult to replicate that if the css were combined.

[yatskevich]

Hi there,

I've implemented grunt plugin for Bower based on idea of bower-installer by @blittle.

The part which manipulates paths is abstracted from copying and other stuff. Hopefully, if Bower's core team decide to add a new section to component.json (bower.json) to describe different types of assets, then I can port the code and submit a PR quickly.

This section is called "exportsOverride" because it overrides imaginary "exports" in Bower's packages.

[robdodson]

To @adamalex 's point, I don't see how you could only have one file per type and still have bootstrap function. If you want to use bootstrap-responsive.css you'll need both css files. The same goes for the glyphicon pngs. Would you really want to split bootstrap into 4 repos just for 2 css files and 2 png files...?

Admittedly my experience with the main property is pretty limited so maybe I'm missing the point.

[mvolkmann]

I can understand limiting the files in the main property to one .js file and one .css file because the main .js file can use RequireJS to refer to others and the main .css file can use @import to refer to others. However, I don't understand that limitation on other file types such as images. This seems to force creation of a single sprite image that combines all of them. I have never created such a file, but I'm guessing that isn't easy to do for every image file type.

[paulirish]

Things are being documented over here:
https://docs.google.com/document/d/1APq7oA9tNao1UYWyOm8dKqlRP2blVkROYLZ2fLIjtWc/edit#heading=h.et2qzfg7dk01

On Thu, Mar 14, 2013 at 2:30 PM, Mark Volkmann notifications@git.luolix.topwrote:

I can understand limiting the files in the main property to one .js file
and one .css file because the main .js file can use RequireJS to refer to
others and the main .css file can use @import https://github.com/importto refer to others. However, I don't understand that limitation on other
file types such as images. This seems to force creation of a single sprite
image that combines all of them. I have never created such a file, but I'm
guessing that isn't easy to do for every image file type.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/46#issuecomment-14930479
.

[necolas]

Closing - all spec work is being done in #110 now. Please, comment on the spec and make longer suggestions in the issue thread over there :)