StyleGuide 04-10 - Barrels

[bodiddlie]

Since SystemJS doesn't use node module resolution, but angular2 (or rather the ts config we use) does, the barrel import syntax requires either changes to the imports, or adding entries in systemjs.config.js.

If you have an app/shared/index.ts folder and do import { SharedComponent } from '../shared'; somewhere, the default SystemJS setup from the tutorials will end up throwing a 404 because it tries to load ../shared.js.

If you change the import to be from '../shared/index, or add app/shared to the packageNames in systemjs.config.js, then it works.

[linusbrolin]

I just found this out the hard way, after I went through all my code and added barrel imports everywhere, according to the Angular2 Style Guide.
Having to add every single folder with an index.ts file to system.config.js seems like such an unnecessary headache and a poor way to build apps.

I guess I'm going with the '../shared/index' approach for now, but it takes away a bit of the point of barrel imports (shorter, simpler import lines).

[jmcooper]

@johnpapa I'm curious if you've seen this behavior also. I'm adding the cookbook recipe for barrels and running into this same behavior. It seems that the only solution is to add /index to the end of the import (i.e. import { Hero } from ./heroes/index) or to add app/heroes to the list of packages in systemjs.config.js. Neither of those is mentioned in the style guide, so I'm curious if you found another solution.

[bodiddlie]

It looks like the angular-cli generators add the barrel file to the systemjs.config.js file, so maybe just including a bit of info that if you're using systemjs, this is necessary?

[linusbrolin]

Seems like a poor design decision honestly.
Having to manually map (almost) every component in systemjs.config.js seems like one big step backwards.
If this is the recommended way to structure Ng2 apps, then a better solution would be for Ng2 to extend SystemJs with a small shim to provide support for Node module resolution, so that no manual config has to be done.

[Foxandxss]

We are going to move this recommendation from Do to Consider.

The CLI adds the entries for yourself and Webpack support this out of the box.

[johnpapa]

Here is some reasoning here on the problem we are addressing. The number of times we import something is very large in an app. We write import { ... } from ... a lot. Those import statements add up and they can get long. There are a few things we do to make them both less numerous (creating arrays of modules) and to make them shorter (barrels). These add up significantly over time to reduce the code we write and make the app much more readable.

For example, here is how we would import these 4 services in a shared folder without any barrels. Notice spinner and toast are in their own nested folders under shared, too.

import { ExceptionService } from '../app/shared/exception.service';
import { MessageService } from '../app/shared/message.service';
import { SpinnerService } from '../app/shared/spinner/spinner.service';
import { ToastService } from '../app/shared/toast/toast.service';

This is fairly common and the larger an app gets, the more imports we have. Can we do better? If we add barrels with the index.ts file in each folder that exports the symbols, we can now do this:

import { ExceptionService, MessageService } from '../app/shared/index';
import { SpinnerService } from '../app/shared/spinner/index';
import { ToastService } from '../app/shared/toast/index';

That is shorter ... but what if we now use barrels to re-export form the nested folders' barrels too? Then we can make it a single line like this

vs

import { ExceptionService, MessageService, SpinnerService, ToastService } from '../app/shared/index';

And if we are willing to add a map for the folders in systemjs.config.js we can eliminate the need to say /index like this

vs

import { ExceptionService, MessageService, SpinnerService, ToastService } from '../app/shared';

And if we use the CLI it adds the map for us.

The only Do here is be consistent with whatever technique you want (which will be added to the guide).

In short:

1. The CLI adds the barrel mapping for us. So we do nothing and we get to say ./shared
2. If we don't use CLI, we map it once in systemjs config, then every import is shorter
3. If we don't like it, we don't do it and instead do ./shared/hero.service

[jmcooper]

I agree, John. It's too bad that SystemJs doesn't have an option recognize /index by default (although there's probably a good reason that I'm not aware of). But even without that, adding the barrel to the config once seems better than the extra import statements everywhere. I like the idea of the style guide suggesting consistency and allowing developers to decide on whether to add the package or add /index to their imports. Having said that, I tend to think that creating barrels to consolidate multiple imports in a package should be a Do, not just a Consider and adding the package to the SystemJs config could be a Consider.

On a related note, when a folder only contains a single exportable item, perhaps making a package out of that folder should be a Consider since it really is just changing your import from something like ./hero-detail/hero-detail.component to ./hero-detail and not consolidating multiple imports. Or would you consider this inconsistent if you are doing this in addition to using barrels like ./shared? I admit I'm on the fence on this one, but not sure if it's worth adding a package to the SystemJs config in that case.

[Foxandxss]

I like all your points there @jmcooper.

One of the reasons of doing a barrel for a single export is for consistency as you said. It is better not to have some imports on folder and some imports on direct files.

[johnpapa]

The real issue here is to see if there is a way to easily omit /index. I propose we add something to the style guide to explain tht the CLI does this for us, but if you don;t use the CLI then you need to add this as a default or import from /index.

@Foxandxss do you agree? if so, can you make the change and we can close this?

[mgechev]

@bodiddlie there's an open issue related to this topic in the SystemJS issue tracker systemjs/systemjs#1164

[MrLoh]

just including a function that goes through the sub folders in app and adds them to the packages object in systemjs.config.js would also be a nice option.

[chapati23]

I have a big problem with barrels in its current form: The order seems to matter. There's an issue on stackoverflow as well.

For example, if I have a barrel like this:

export * from 'my.component' // using my.service via DI
export * from 'my.service'

Then I get an error EXCEPTION: Can't resolve all parameters for MyComponent: (?).
To fix it, I have to export the service before the component:

export * from 'my.service'
export * from 'my.component' // using my.service via DI

I see this as problematic because:

• It's not documented on angular.io in the barrels-section
• The error message doesn't give you any help in fixing the issue
• Implicit order rules are a code smell IMO (especially when undocumented)

[mgechev]

@chapati23 I suppose this issue is more related to forwardRef rather than barrels.

[chapati23]

thanks @mgechev, i've read the forwardRef docs as well as the respective DI cookbook paragraph.

I don't understand this 100% but I guess if my.component uses either a service via DI or another component via directives from the same barrel, then they have to be exported before my.component, is that correct?