How to make elements reusable through Bower

[zenorocha]

When we stopped to use the CDN and started to use Bower we had this default bower_components folder commited (which is now called lib).

We made this decision because we want people to be able to demonstrate their elements right from the gh-pages and debug them easily.

However this causes reusability problems. They cannot be shared with Bower and used by other apps.

[robdodson]

This is something we've been discussing a lot internally and I still don't think there is a great solution.

If an element is going to be registered and shared with bower, then it must assume all dependencies will be siblings. So what my-element is doing here is actually incorrect. The correct path to polymer.html would be:

<link rel="import" href="../polymer/polymer.html">

Because if I run bower install my-element I'm going to get:

lib/
  polymer/
    polymer.html
  my-element/
    my-element.html

This means an element boilerplate needs to have two branches:
In the master branch, the element is written to always depend on its siblings. example from mark-down's master branch

In the gh-pages branch, you can have a bower_components folder (or libs folder) and import your element from that into an index.html to test. That's what I do in mark-down's gh-pages branch.

This is an annoying way to work but it's the only way that your element will be installable by bower. Take a look at the Polymer elements, they all follow this same technique.

There is another wrinkle to think about...

If someone does hardcode a path into their import:

<link rel="import" href="../other-stuff/polymer/polymer.html">

Then you'll have to create a folder in your project called other-stuff and put an html import in there which just contains another import to where you've actually stored polymer.html. Sorry if that was confusing to read (it's confusing to think about!) but the long and short of it is that you can't ever put a dirname into your element's imports. They will all have to be ../polymer/polymer.html in order to satisfy bower. I think that means, if you use git to install an element instead of bower, you'll have to put it in your bower components folder, and that feels weird. We're trying to see if we can evolve bower to make this not so weird.

[zenorocha]

Today @robdodson and I tried to put together some solution to fix this.

You can check the full prototypes here:

• https://github.com/zenorocha/x-test
• https://github.com/robdodson/x-foo

The basic idea is:

1. Set .bowerrc to:

   {
       "directory": "./"
   }

2. Git ignore polymer and platform on master branch, but commit them on gh-pages branch

3. Move the demo from root to src/

That way you can still develop on master branch and also have a live demo on gh-pages: http://zenorocha.github.io/x-test/src/demo.html

The only thing we need to automate in order to make it easier for people to publish live demos is the .gitignore removal on gh-pages branch: https://github.com/zenorocha/x-test/commit/d56c93b2e7b385c743233b57a9b9841564418bd8. Suggestions?

[addyosmani]

cc @wibblymat for his take on this approach, but it looks legit.

[robdodson]

@wibblymat pointed out that once you install the element it no longer works because it's in package_name/src but it's looking for ../polymer.

Sounds like we might need a build task instead...

[sindresorhus]

You also shouldn't change the name of the folder as it should be clear it's the folder Bower uses to store components.

[zenorocha]

No idea how to solve this one 😔

I wanted to avoid build steps, but I don't think it's possible...

[robdodson]

Because everyone must assume their element will be installed by bower, we have to use the "canonical path" (../package_name/package.html) for dependencies. This means you're either developing your element inside of your bower_components dir or you need a build step that strips out any paths to bower_components and turns them into canonical paths.

Another alternative is for bower to be cool with git repos and other things being dumped into the bower_components dir. At that point you wouldn't want to call it bower_components anymore, you'd want something more generic, like the original components (yes I know why we changed it) or, as Zeno is doing, lib. I realize this makes people freak out and I understand the importance of indicating that the stuff in the folder is managed by bower. It's a total can of worms but it's something we might consider. The alternative is to tie bower usage for Web Components to a build system like grunt, gulp, etc.

or, we move the build step to bower itself. Maybe have a comment string that bower can look for in our main html import file and it can swap the paths

<!-- on-bower-install -->
<!-- ../package_name/package.html -->
<link rel="import" href="bower_components/package_name/package.html>

(I realize this is stinky, just throwing out ideas)

[zenorocha]

I feel sad about having all those dependencies.

Instead of focusing on the element authoring itself, a beginner first needs to install NodeJS, install Grunt and Bower globally, then install local dependencies to fetch Polymer/Platform, then run some Grunt command to handle those paths.

For us who run those commands everyday it's not a problem. And I'm not saying that those tools are bad either. They are incredibly useful and important to distribute your element for example. But they are blockers for lots of developers who just wants to open their editors, edit two HTML files, and see the magic happen.

Unfortunately using a CDN isn't an option for bunch of reasons:

• The CDN does not host polymer.html which removes the ability for elements to import it.
• There are many elements which are not hosted on the CDN so it might be tricky to include all of * them in your project.
• You will not be able to Vulcanize your code.

That's why we end up having no alternative but use Bower + Grunt/Gulp. So let me focus in a solution.

I don't think Bower will make such changes [soon], and every single day there are people using this boilerplate to create stuff. They are building their projects on top of something that is not distributable at this current state.

I'm not familiar with this grunt-targethtml but it seems like it can be a solution.

[zenorocha]

Just changed the issue title since this discussion is more about how to make elements reusable through bower then how to name bower's custom install folder.

[sjmiles]

Polymer engineering perspective:

• We define a component as a shareable thing. This may (or may not) contain one or more elements. Canonical path and the concept of a components folder are both enablers for sharing.
• The notion that the flat dependency list has anything to do with Bower is a misunderstanding. Flat dependency list exists to enable the canonical path, which is a Good Thing, not some constraint.
• The notion that your components folder must only contain components from a specific source, e.g. Bower, is a non-starter. In my recent discussion with Mat Scales, my understanding was that he is completely on board with this notion. We say that your components folder should be able to contain components from any source (zip files, GIT checkouts, Bower, other).

Rob you said

This means an element boilerplate needs to have two branches:

But I can't understand what you refer to and I can't figure it out from the repos you pointed to. Can you be more explicit? No polymer material or elements ever need to twiddle paths, this is the point, it all Just Works (tm).