JS organization

[kamsar]

Let's face it, the stock JS organization in Phoenix right now is suboptimal. Libraries are haphazardly thrown about, old and ghetto internal tools abound, etc.

I happen to be a big fan of the way Jeremiah and Justin have been organizing the JS for Meadows:

• js (root contains only Browserify root dependency files, like _all for scss)
  • lib (libraries, third party or isite, designed to be consumed but not customized except perhaps a CJS shim)
  • modules (project specific code related to cross-cutting concerns such as analytics or forms)
  • sections (scripts that power specific pieces of the site e.g. photo gallery or product list)

Thoughts?

[ajmueller]

Check the latest commit in the JSBuildImprovement branch. I'm on it already ;)

On Aug 7, 2014, at 9:35 PM, Kam Figy notifications@github.com wrote:

Let's face it, the stock JS organization in Phoenix right now is suboptimal. Libraries are haphazardly thrown about, old and ghetto internal tools abound, etc.

I happen to be a big fan of the way Jeremiah and Justin have been organizing the JS for Meadows:

js (root contains only Browserify root dependency files, like _all for scss) lib (libraries, third party or isite, designed to be consumed but not customized except perhaps a CJS shim) modules (project specific code related to cross-cutting concerns such as analytics or forms) sections (scripts that power specific pieces of the site e.g. photo gallery or product list) Thoughts?

— Reply to this email directly or view it on GitHub.

[ajmueller]

As we discussed via IM, this structure is a little different than the one I'm working on in #27. I'm definitely open to changes, though. I do like the combination of lib and vendor into a single lib directory. What do you think @justinskolnick?

Also as discussed, I can't think of a use-case where the sections directory is necessary and can't be handled by a module. If you guys have one I'm all ears. I'm not saying it's not necessary, I just can't think of a reason for it at the moment.

[kamsar]

My thought was that 'modules' are almost like little libraries written for this project that are used all over, whereas 'sections' are modules that apply to a very specific portion of the site (like a single form)

[jbascue]

Precisely this.

On Aug 8, 2014, at 11:16 AM, Kam Figy notifications@github.com wrote:

My thought was that 'modules' are almost like little libraries written for this project that are used all over, whereas 'sections' are modules that apply to a very specific portion of the site (like a single form)

— Reply to this email directly or view it on GitHub.

[justinskolnick]

Ditto. @kamsar's distinction is solid. Section files map to site sections and, for this reason, are a reliably Good Thing when the project 1) routes users to majorly different sections based on their role (like a public/admin split) and/or 2) has a whole lot of JavaScript. You can concat different section groups into different JS files. Modules are custom utilities shared across sections.

As for lib vs. lib+vendor, I prefer throwing the big-brand libraries (jQuery, Modernizr) in vendor and the downloaded bits and pieces that depend on them (i.e., jQuery plugins) in lib. A question of pickiness, I think.

[kamsar]

We could render the vendor/lib distinction moot by using bower, then 'bower_components' it is! ;)

[kamsar]

That said I don't know if we really have enough dependencies to normally warrant using bower, and we'd lose the ability to hand-curate what files we want like we do now.

[ajmueller]

Ah, okay, I see what you mean by the sections directory. Excellent, I'll add it with my next commit on the JSBuildImprovement branch. Unless one of y'all would like to; make sure to add a README file so it's not empty. Plus one of you will probably be able to contribute better verbiage in the README file.

We're starting to use npm for some major vendors like jQuery, but they're not all available. I do like the distinction of lib vs. vendor as Justin mentioned. It just feels like a very clean separation. Perhaps the "lib" name is somewhat misleading, however, since jQuery and Modernizr are "libraries." Perhaps "plugins" or something else would make more sense instead of lib?

[kamsar]

I dunno about you but vendor isn't very descriptive to me.

What about lib (in lieu of vendor) and lib/plugins? Or just lib and plugins?

That said are we drawing the distinction as "depends on nothing else" vs "depends on jquery/angular/underscore/etc"? I guess I'm not as sure why it matters of a library is from Google or from Joe Smith, still a lib to me.

[justinskolnick]

All these labels are meaningless aside from conventions. What we call it doesn't matter to me.

What does matter to me is knowing at a glance that I'm looking at an official googlething.js library vs. the thing Joe Smith wrote to extend the Google library that he called googlething.automagic.js and posted to his Github account. The distinction I'm looking for is more: institutionally supported libraries managed by somewhat dedicated staff using semi-meaningful versioning schemes vs. user-generated extensions of those libraries.

For instance, I wouldn't put WordPress plugins in the same directory as WordPress, and neither would WordPress. Personally, I wouldn't put WordPress anywhere. But that, my friends, is another matter.

[ajmueller]

Perhaps we should simply follow a standard convention for file names then? I always follow the convention of jquery.pluginname.js anyway, so everything could live in a single lib directory. I think @stoff would like to avoid another conversation in our FED meeting regarding directory names, so if we can come up with a solid convention, let's just enforce that. Simplicity and clarity are what I think we should aim for.

[justinskolnick]

Man, I get the willies at even the suggestion of renaming a third-party file. At other places, I've had to scour a whole mess of minified dependencies for uniquely googleable bits, on the hope of tracking down documentation or (God willing) a patch.

As I said, I don't care what we name the folders. I care that they exist for us to name. At worst, somebody drafts a pull request with a rename, and we follow that with a version bump.

[kamsar]

If we're talking about someone throwing jquery.yourmom.js directly into a file called jquery.js, then yeah screw that noise.

Seems like most projects have at most 10-15 dependent libs/plugins (though I guess that could grow with increased modularity allowed by CJS) to the point that multiple directories just make it harder to find stuff.

That said it might make sense to say paste the source URL of random jQuery plugins, etc at the top of their source. For posterity.

[ajmueller]

Based on the comments and the reality of our current project sizes, is anyone opposed to a single directory lib where we keep libraries (e.g. jQuery, Modernizr, Respond) as well as their associated plugins? I can add the sections directory as well. Of course this will all be just the basis and can be customized per project, but setting up a structure that makes sense for scalability is what we should aim for.

[kamsar]

:thumbsup:

Guidelines, not rails ftw.

[ajmueller]

I think we have a good handle on this and it's being incorporated into #38. Close this?

[ajmueller]

@kamsar are you good with closing this?