Proposals on how to structure 'standalone' modules in angular. Please read it and leave your opinions for a better angularjs world!

proposal.md

Angular module structure (proposal)

Everyone who's reading this, please leave your opinion/ideas/proposals as a comment for a better world!

Background

Most of you guys read Josh' proposals to make components more reusable, I think. Now, reading through this proposals definitely gives a feeling that this is the right way. Anyways, If you haven't read it yet, you should.

So Josh shows us, how angular apps can be structured in a better and more reusable way. Reusability is a very important thing when it comes to software development. Actually the whole angularjs library follows a philosophy of reusability. Which is why you able to make things like:

// Defining a module
angular.module('myModule', ['dep1', 'dep2']);

// Fill it with components
angular.module('myModule').controller();
angular.module('myModule').factory();

// ... and so on

That whole module thing can now be put into another app, or module, or whatever since it's a module and it knows it's own dependencies. So, turned out that structuring angular apps by feature rather then by layer is the better way of structuring angular apps. It's more reusable!

You might know this already after reading Josh' great proposal. I would like to take a step in a similar direction when it comes to developing kinda 'standalone', installable angular modules, which are app independent.

But what about standalone modules?

Now, what do I actually mean with 'standalone' angular modules? So, with angular, you not only can build awesome apps, you can also build awesome modules which can be reused by others. The AngularUI Project for example, is also just a big angular module with several components and submodules (with its own dependencies) you can use to build your angular apps.

A few weeks ago, I published ngTranslate, an angular module which provides a set of components (services, directives, filters) to translate your app's content at runtime in multiple languages. First of all, it wasn't even planned to make a whole module out of it, but it has grown with the times.

So, ngTranslate is just one of those 'standalone' modules. You can inject it as a dependency into your app and use it's provided components (for more information read the docs.

When developing this module, there were a lot of questions in my brain I hadn't really the perfect answers for. With this gist I'd like to discuss with you guys, how we handle 'standalone' module development.

Nowadays we have great tools like grunt, bower or that Yeoman guy (who just uses the mentioned tools), to make our development process as easy and fast as possible. There are already great packages you can simply install with a

$ bower install <package-name>

The same goes for angular packages you can find on GitHub with a bower- prefix.

We need more of them!

In my little dream world, there'll be someday a BIIIG bunch of reusable angular modules for specific use cases on the interwebs, just like you know from npm.

So if you're interested in making the angular world as easy to use as npm, leave a comment right here and discuss this topic with the community.

The questions that came up

When thinking about a clean structure while developing ngTranslate, the following questions came up:

• How to name the module (Conventions?)
• How to name the repository on GitHub?
• Is the repository name the same name which stands in package.json, component.json?
• How to name the bower repository?
• How to name the registered bower package?
• How should the generated (development and production) file be named?
• How to structure the module itself?
• How to structure test environment regarding to the module structure?

These questions can be break down into several things I'd like to discuss with you. I'll go through them one by one.

How to name the module (Conventions?)?

Naming a module can be very easy, but it can also be a mess. When developing an angular module, a module has to be named in camel-case. This is pretty straight forward, but it gets a bit harder when thinking about, what the actual name should be when there has to be a prefix.

Angular's built-in modules are all prefixed with ng, which totally makes sense since ng is actually just a shortcut for angular. That's why we have modules like ngResource, ngCookies and so on and so far.

In my opinion, the ng-prefix looks pretty nice but I think it's actually kinda reserved for angular's own modules. At AngularUI the modules are prefixed with ui which also makes totally sense, but they arent' camel-cased. We use a dot-notation there and name the specific components in camel-case.

I think it'd be great if each module out there follows the same convention and structure. So what do you guys think? Module names always camel-case? What should the prefix look like? Can we go with ng or should everybody has it's own little 'namespace'?

Please leave a comment.

How to name the repository on GitHub?

I think this one comes pretty much hand-in-hand with 'How to name the module?'. After deciding to name the module ngTranslate I wonder under which name to publish the module on GitHub. The following things influence the repository name:

• The name should be short, so it's easier to type
• It should have the module name in it
• It should have the prefix in it (or not?)

Easier to type means for me: no camel-case, we go dash-case. So I had something like

***-translate

But what about the prefix? ng-? angular-? I choosed ng- because it's

• a) Easier to type
• b) angular- is already used by angular itself

So I came up with ng-translate. But again. This goes hand-in-hand in how to name a module propery. Also, maybe we want -angular- in the repository names, so we that we know: this is an angular module. I don't know.

What do you guys say?

Is the repository name the same name which stands in package.json, component.json?

Now we I had a conflict. The repository name was ng-translate. The module name was ngTranslate. What should be the name in the package files? What are the consequences when not naming the package properly (regarding searching etc.)? I went with ng-translate again, since the repository is called the same.

Again, I'm not sure if it's the right way.

How to name the bower repository?

In my opinion, there should be always two repositories.

1. The repository to develop the module (e.g. https://github.com/PascalPrecht/ng-translate
2. A bower repository, which just includes the files you need (for easy installation. e.g. https://github.com/PascalPrecht/bower-angular-translate

But how to name these bower repos? This also goes hand in hand with the other questions. I think, what's definitely clear, is that it should have a bower--prefix in the name. The Angular team also uses this convention for their own modules.

As you can see, I named the bower repo for ngTranslate bower-angular-translate. So why not bower-ng-translate?

Actually, I just used the conventions of the existing angular module packages there's no real reason why I didn't use bower-ng-translate, but maybe you say I should have done so.

How to name the registered bower package?

Just like the repository name but without the bower--prefix. What do you say?

How should the generated files be named?

First: every angular module out there should have a grunt file which provides a task to build a bower package

But how should the generated files be named? We know things like modulename-x.x.x.js and modulename-x-x-x.min.js. I think this convention is okay for files that get generated by a grunt task.

The bower package shouldn't have the version number in the name, since it's already in the component.json file. But if the generated files from the grunt task are actually the files which also get deployed as bower package, shouldn't they also just have the module name without the version number? This makes the process easier.

Leave a commment.

How to structure the module itself?

As you can see, ngTranslate currently has the following file structure:

|-- ngTranslate
|   |-- directive
|   |   |-- translate.js
|   |-- filter
|   |   |-- translate.js
|   |-- provider
|   |   |-- translate.js
|   |-- translate.js
|-- test
|   |-- unit
|   |   |-- translateSpec.js
|-- .gitignore
|-- .travis.yml
|-- CHANGELOG.md
|-- CONTRIBUTUNG.md
|-- Gruntfile.js
|-- LICENSE
|-- README.md
|-- component.json
|-- karma.conf.js
|-- package.json

Now this is actually pretty straight forward, but there are still some things I'm not really sure about. First, I've extracted the provider code into a seperate file in an extra provider folder. Is this actually needed? The angular project just uses provider definitions as service definitions, which actually don't have to be in an own folder.

So maybe we can rid of that. Otherwise, there are folders like directive and filter, which are also in the angular modules. So these should be there, but shouldn't there a provider folder too?

The next thing I'm not sure about is the name of the actual source folder. It's called ngTranslate. I did this because the modules in the angular project are also named this way. But this is probably done because there are several modules in one folder, where a 'standalone' module would never have another module in it. So this could be called src instead of ngTranslate. The AngularUI components are currently also splitted up into many little modules. And per module there's also a folder called src.

Shouldn't all angular modules out there follow these conventions?

How to structure test environment regarding to the module structure?

The translateSpec.js file in the test folder is grown with the times. I'm thinking about splitting it up into one file per component, just like the module itself is currently structured. Does this make sense? Of couse, totally depends on how we decide how angular modules should be structured.

Discuss and get the best out of it

It'd be so freakin' awesome if you guys leave your opinions on that here. We could then develop a specification which describes how a generic angular module boilerplate could/should look like. In addition to that, there could also be a generator-angular-module beside the existing generator-angular for Yeoman.

That's all. Please help out making my little dream come true.

/pp

Thanks for the thoughtful writeup, Pascal. I'm actually in the middle of writing a blog post on "How to write AngularJS Bower Components," and I think some discourse here would be great.

I think Grunt, Bower, and Yeoman are still far from perfect. There are still a lot of things in flux, and a lot of changes and improvements coming to these tools in the near future.

In my little dream world, there'll be someday a BIIIG bunch of reusable angular modules for specific use cases on the interwebs, just like you know from npm.

This is exactly what I'd like to see too. :)

Responses to Pascal's Questions

None of these should be taken as definitive, or even representative of the "official AngularJS core team" stance. I'm sure @IgorMinar would have at least a few suggestions for improvements upon my answer. And also there's still a lot in flux, especially with Bower. If anyone's reading this in six months, they should be aware that while some of these ideas will hold true, some of them will change. Hopefully there will be better documentation by then. :)

Just for reference, here are some of the Bower components that I've created:

• Dragon Drop
• PhoneGap Notification
• Markdown Directive
• Socket.IO Service

Again, I wouldn't call these perfect or idyllic, but they work for me.

Names

These are the loose conventions I've been using.

• Module name: <author>.<optional-namespace>.<thing-name>-<optional-thing-type>
• Service/Directive name: Choose a (short) namespace. I've using "btf," my initials. See my dragon-drop directive for an example.
• Bower registered name: angular-<optional-namespace>-<optional-thing-type>
• Github repo(s)
  • source repo: angular-<thing name>
  • optional build/release repo: bower-angular-<thing name>-<optional-thing-type>

I've been using dasherized names, and periods to separate parts. That's a purely aesthetic/mnemonic preference (if I use camelCase, I sometimes forget how I decided to name things with acronyms (ex: myHTMLThing, myHtmlThing) and all options look ugly to me). I don't feel strongly about this at all, so if someone decides that camelCase is the One True Way (tm) (and has some compelling reason), that's fine by me. I'll gladly switch all my stuff.

For <author> I like to use my Github handle, but twitter or whatever is fine. The reason that I prefix the module name with an author is to make it easier to fork without introducing confusion. Another developer can fork my module, and as long as they change the <author> of the module name, users can use either of my module or the forked one without confusion of which implementation they are using.

I like giving an <optional-thing-type> for directives and filters when it's not immediately obvious from the <thing name>. For instance, "drag and drop," "date picker," "color picker," are pretty obviously going to be directives. "markdown" might be a service, directive, or filter, so it's good to clarify.

I like giving an <optional-namespace> when I have a group of similar components, as when writing wrappers for PhoneGap.

I wouldn't bother creating a separate "build repo" for most projects. If the build step is "ngmin + uglify," Users can have their project's build system take care of it. If you have something more involved, then I think the bower-<thing-name> build repo is a fine approach.

How should the generated files be named?

I like module-name.js and module-name.min.js. You already know the version of the module via component.json, so there's no need to put it in the file as well.

Again, I wouldn't bother with a module-name.min.js unless you have a more involved build.

How to structure the module itself?

Not sure. I've only ever written small components that look like this:

λ angular-socket-io → git master → tree                     
.
├── component.json
├── README.md
└── socket.js

I plan to add a tests directory and a karma.conf.js, but aside from that have no specific advice on structure.

Other Thoughts and Concerns

One of the goals of AngularJS is to improve the situation for developing web apps in a broad sense, and not just for developers with <script src="angular.js"></script> in their apps.

Bower Package Stewardship

While I agree sharing stuff is great, there's no need to publish everything to Bower. Bower lets you install from Github like this:

bower install btford/angular-dragon-drop

Which resolves to the repo at [email protected]:btford/angular-socket-io.git.

Bower also lets you install from arbitrary git repos, so if I didn't want to publicly publish on Github. You can do the following:

bower install [email protected]:btford/angular-socket-io.git

This is handy if, for instance, you have some company-specific code you're sharing between projects. You can put this code on a private repo, but still install via Bower.

My point is to share things that make sense, but not publish a package for absolutely everything. If you're not going to be watching Github and responding to issues, don't publish it, just advice users to bower install my-name/my-component (or fork it and do bower install your-name/whatever-component ).

Don't claim a name in the Bower registry unless you're going to follow up and help maintain and improve it (or are willing to hand it off to someone else to do so). When in doubt, just use the bower install user/repo pattern. You can always register it later.

Sharing is Caring

A lot of utility libraries written and wrapped for AngularJS would be useful for users of Backbone, Ember, or who aren't using any framework at all. I really don't want to encourage developers to wrap up the cool stuff they do so it's only available to developers using AngularJS. My vague guideline is that for something <1000 LOC that isn't doing something Angular-Specific, make a new project, then write an AngularJS adapter (if needed).

On the other hand, there's no need to share things outside of AngularJS that are are by nature tightly coupled to AngularJS APIs. A couple hundred lines of JS that relies on $location and $http isn't worth the effort. A couple thousand lines for a new routing system for AngularJS also probably doesn't need to be shared with the greater web community.

Kitchen Sink Widgets

As an experiment, I spent some time trying to port jQuery/jQueryUI plugins to AngularJS to avoid the jQuery dependency. A lot of these plugins provide a million different options, and the code becomes a behemoth. The situation is much worse with Angular, because any of these sort of options might be something you want to data-bind to at runtime. So you've introduced a bunch of additional watches that many users won't care about, but might start to tax the performance of this widget. For this reason, I want components to be lightweight and focused. If you want something similar, fork and make your own (see above).

I think AngularUI is doing alright as far as balancing between configurable versus focused. If I were redoing the project myself from scratch, I'd probably write more widgets that each do less, but I wouldn't say that their approach is "wrong."

I also think we should avoid "Collections of X" components. One component should do one thing well. It's fine for a bower component to have multiple directives or services, but that should only be the cases where you need (or almost always use) both together. This goes for utility components as well. I love the utilities in underscore.js, but I really don't like the "all or nothing" approach to bundling them when most only use a handful of the many provided.

I like that AngularUI is now splitting directives each into it's own repo.

Wrapper Modules

I want to avoid having a million AngularJS apps that just wrap other libs. For instance, I'd like to avoid having angular-d3, angulae-lodash, angular-underscore, etc. The reason for this is that it creates a lot of maintenance overhead. Take d3 for instance. Here are just a few cases that illustrate the problems:

1. Whenever a new version of d3 is released, angular-d3 must be updated.
2. Issues might be filed on angular-d3 that are actually bugs/feature requests for d3.
3. The developer of angular-d3 makes improvements to angular-d3 that should/could be back-ported to d3. Then they release a new version of angular-d3.
4. After 3, the developer for d3 releases a new version of d3 with the same version number as 3's effective fork of d3, creating confusion for users of angular-d3 and d3.

tl;dr, please don't create wrapper modules for components that expose their APIs on window.whatever. Just use the API off window for now. If Angular needs $apply for some foo-lib library, feel free to write an adapter, but the adapter should depend on foo-lib, not include the files for it.

The ideal solution to this problem to be standardized ES6/ES7/ESEventually modules and Web Components, but we still don't know when something like that will land.

Angular module structure (proposal)

How to name the module (Conventions?)?

I have been building a collection of components and I have been using the convention of module.componentName so for example I have nag.grid and nag.siteOverlay. Something like module.component-name would work just as well too and either one would be good with me. My namespacing convention is something that just carried over from my C# programming days.

How to name the repository on GitHub?

I don't feel to strongly about this however I do believe putting angular in the name (no matter where it is) does make it apparent the it is an angular based project.

How to name the bower repository?

I think that whatever you name your main github repository, the one that is put into bower should be prefixed with bower-. So if my project was named my-project-name, the bower repository should be named bower-my-project-name.

How to name the registered bower package?

I think the bower packages should be named just the the bower repository minus the beginning bower-. So if my bower repository was named bower-my-project-name, the bower package should be named my-project-name.

How should the generated files be named?

I personally don't think that there is any really need for a build process specifically for a component (unless like Brian said, you have a complex process). Anyone using angular should really have a build process for there own application whether it is yeoman, grunt, custom process, whatever. The authors of these packages should just make sure that the files there are writing can properly be minified and concatenated.

This goes for plain javascript files, stuff like SASS, LESS, CoffeeScript, etc... should have a build process that outputs the respective assets however the naming of those I don't think matters much.

How to structure the module itself?

I have started to use the structure that is detailed here : yeoman/generator-angular#109. Not only do I put my javascript files, test files, and template files in there, I also put my css (sass) files in there.

How to structure test environment regarding to the module structure?

I have been using *.spec.js for my tests and the files live in the same location as the actual code.

I would diffidently be interested in hearing what anyone else thinks and I am going through the process of doing some major refactoring of the components I have been build (like breaking each component into it own repository and what not).

Thanks @yahyaKacem, @ProLoser, @btford and @ryanzec for your answers! Looks like everyone in here would use nearly the same conventions (which is great).

@yahyaKavem I totally agree with your opinion on sticking with angular's conventions to just use camel-cased names, but as @ProLoser pointed to, angular overwrites injectables. I also kinda like @btford 's approach on using the author name in the module name, to have and use different forks of the same module without confusion. @ryanzec approach is pretty much like a mix of @ProLoser 's and @btford 's answer.

Putting 'angular' in the name of a GitHub repo and the registered bower package also is fine to me.

So can we say, these points could land in a spec?:

• Module name: [author].[optional-namespace].[thing-name]-[optional-thing-type], where the use of camel-cased or dash-cased names is up to the developer.
• do not use angular prefix ng
• Name the GitHub repository however you want, have a least an 'angular' in it, and don't use ng-
• A bower package repository (if there is any) should have the same name as the source repository, just with a bower- prefix
• The registered name should be the same as the bower-repo just without the bower- prefix.
• Leave version numbers off in generated files names

@ProLoser Why'd you prefer ng-*whatever in the bower package name?

@PascalPrecht thnx for starting this discussion. I'm also happy to see other posters comments.

A disclaimer, to start with: I'm looking at it from the http://angular-ui.github.io/bootstrap/ angle, which is quite different from the little, self contained ngTranslate and little directives described by @bford. But I guess this is good since the proposal should work for many cases.

I need to read through it carefully and comment but there is one thing that I would like to share ASAP. So, I think that this proposal tries to have standards for 2 distinct things:

1. How modules are named and consumed by application developers. The
   questions here are:

• How to name the module (Conventions?)
• How to name the registered bower package?
• How should the generated (development and production) file be named?
• (IMO missing) How to name directives, services etc. registered inside one module (I don't think we should be saying that one AngularJS module = one service or one directive)

2. How modules should be developed

• How to name the repository on GitHub?
• Is the repository name the same name which stands in package.json, component.json?
• How to name the bower repository?
• How to structure the module itself?
• How to structure test environment regarding to the module structure?

While I see some value in creating standard development environment I think that we should care mainly about (1) so application developers can consume "standard" modules.

I think that mix-up between development and deployment practices steams from the fact that Bower is mixing up those two! It looks like it is going to be addressed by hosting packages / components on Bower side (bower/bower#405).

So, what I would like to propose here is to split recommendations into 2 distinct part (in other words, have 2 recommendations):

• for components deployment
• for components development

Those 2 concerns are linked but not identical. This is especially visible when we start to discuss "Kitchen Sink Widgets" - I guess that the http://angular-ui.github.io/bootstrap/ - as it currently stands - could fall into this category. I would love to have an individual Bower component for each directive. But with the current Bower model where one git repo should equal one module / component it is simply not manageable from the project point of view. Happy to see - based on bower/bower#405 - that this is going to change in the future.

I believe that the "Kitchen Sink Widgets" criticism is very valid when it comes to deployed packages. Developers should be free to organize they code as they feel.

Deployment concerns

How to name the module (Conventions?)

In the http://angular-ui.github.io/bootstrap/ we are using, ex.: ui.bootstrap.accordion. So I guess it could be translated to a more general [author].[optional-namespace].[thing-name]-[optional-thing-type] if say that author can be seen as organization as well.

How to name the registered bower package

I guess I'm (almost) with @bford here. Firstly we should derive this name from module's name and convert dots to dashes so angular-[optional-namespace]-[thing-name]-[optional-thing-type] sounds good.

I like the angular- prefix, it will make searching for angular-specific modules easier.

How should we name directives / services inside a module (new, important question IMO)

Since those names will be used in code we should it short. But contrary to @bford I would derive it from [optional-namespace] rather that from [author].

So for the http://angular-ui.github.io/bootstrap/ I would rather write <bs-tabs></bs-tabs> as opposed to <ui-tabs> or pk-tabs (my initials).

I understand that there is a greater chance for names collision here but I think this is good. If there are 2 bootstrap tabs directives from 2 different authors there is not much sense in using both in the same project. They are competing and there should be only one winner, right?

How should the generated (development and production) file be named?

Same as Bower component? Or same as Bower component minus the angular- prefix?

So, assuming that the bower component is named as angular-[optional-namespace]-[thing-name]-[optional-thing-type] it would give us 2 possibilities in the scope of the bootstrap project:

• angular-ui-bootstrap-accordion.js
• ui-bootstrap-accordion.js

OK, I like the angular-ui-bootstrap-accordion.js better. Minified version would become:
angular-ui-bootstrap-accordion.min.js

Then, I think that there is one specificity of AngularJS directives - those can have associated templates. A directive should bundle default templates but also publish a version without bundled templates in case people want to override / provide they own. I would propose to add the tpls indicator to directives that bundle templates, which would give us:

• angular-ui-bootstrap-accordion.js
• angular-ui-bootstrap-accordion.tpls.js
• angular-ui-bootstrap-accordion.min.js
• angular-ui-bootstrap-accordion.tpls.min.js

Thanks to all of you guys for leaving your opinions here. Since we started working on a specification, this discussion is moved to this (https://github.com/PascalPrecht/angular-component-spec/tree/proposal) PR.

Please left comments there if you want to.

Conventional wisdom suggests throwing out Bower and replacing it with a more genuine package manager: npm. We did that and only had to add a couple of missing packages to an npm repository: ngTranslate and d3. We never used Grunt as Gulp (the new de facto standard, with good reason) has long been available. I don't see much value in Yeoman (even if most generators depend on Bower and Grunt) and instead do our generation with Swagger. We maintain our own basic seed application (never encountered a seed that was suitable for new development at the time we needed the seed, they get very stale very quickly).

The suggestion to use Bower based components is disqualifying as far as this being a practical proposal.

Needed to compose you a very little word to thank you yet again
regarding the nice suggestions you’ve contributed here.

AngularJs Traning in chennai