Why specs in source?

[lifehackett]

I'm curious about your decision to embed your .spec files in the /src directory. I haven't used (or seen) this setup before. IMO it pollutes the source files. It is easy to change the config for a different setup, but I'd be curious as to why you prefer this approach.

[dvdzkwsk]

Honestly it's just personal preference and I've seen it go both ways. My team follows the in-src test files, and I'm a fan of it just because it helps me keep them organized without duplicating folder structure. It has the additional benefit of making requires a bit more natural as well (imo).

I could try to add some configuration so that karma also looks for tests in a spec/test folder, that way people get the best of both worlds, but I really don't want to completely remove the ability to include them from inside the src folder.

[lifehackett]

Interesting. Perhaps I'll try it on a project to see how I like it. I always like learning how other teams operate and I think the pain points you noted are well taken.

I don't think you need to make those changes as it is easy for someone to make those customizations if they prefer. Your docs mention this convention, although a bit passively. If you do anything, perhaps just adding a top level section like "Personal Conventions" or whatever in the README that more explicitly calls this out and which files to mod if someone prefers a different structure. (Same for styles).

Again, I think it is fine as is.

[dvdzkwsk]

Yeah definitely, there's benefits to either system - I should probably do more experimenting with the other side of things because I've never given it much of a chance.

As far as the documentation, that's a good idea. I've really been wanting to flesh out the README for a while now so that people can find their way around customizing the kit. My problem with a lot of the other boilerplates out there is how opinionated they are, something I've been trying to avoid, and better documentation would definitely help alleviate that with this repo.

Thanks for the thoughts/advice!

[jonaswindey]

Another question I was wondering about. What's the reason for calling everything index.js (or index.jsx if it's a component)?

In my IDE (Webstorm) I use "goto file" all the time. In my apps I use for instance userstore.js, user.jsx etc, so I just start typing "user" and I see all the files. Here it's a bit trickier since I have to type the path instead of the filename.

In my humble opinion I prefer (as much as possible) unique files, so you know in your team if you're talking about a file which one it is exactly.

[lifehackett]

@jonaswindey I had the same initial reaction. I think the purpose is for index.js to import each of the files within the directory and then export them all packaged together, like you might see for .less or .scss files, and then you can import that entire feature elsewhere with a single import. The individual components then become properties.

I also prefer your approach and so am renaming them, but I'd be curious to hear the author's perspective in case there are other benefits.

[dvdzkwsk]

@jonaswindey this is a comment I've heard a few times now, and it's completely valid. In fact, I will probably be updating the starter kit to follow that sort of naming convention - or I'm at least leaning heavily towards it.

It stems from how my team develops, where we build all of our components as isolated npm packages. As a result, it's easy to keep track of files since the scope of a package is pretty small. Contrast this with an all-local starter kit such as this one, it can get a bit cumbersome to have a bunch of index.js files open in your editor. And searching is another problem like you pointed out. What @lifehackett pointed out is also a large part of the decision.

One benefit of keeping the index.js naming convention is that it reduces duplication if you want to nest your files in sub-folders. For example, I like to keep my tests right next to their component, so you have a structure that looks like:

- components
  - my-component
    - index.jsx
    - index.spec.js

So importing this component can simply be:

import MyComponent from 'components/my-component';

If you were to keep this structure but adopt a unique file naming convention, those imports would instead look like this:

import MyComponent from 'components/my-component/my-component';

So you basically have 3 options:

a. keep the current structure with index.js(x) files
b. keep the current structure but rename files to be unique
c. make filenames unique and don't nest them within subdirectories

The latter option gets rid of the redundant import statements, but ends up cluttering up your project once components start to accumulate additional files. For the sake of the starter kit, I'd probably pick option b and just deal with the redundancy. What are your thoughts on this @lifehackett and @jonaswindey?

Also, now that the starter kit has been reduced to no longer include a bunch of example components, the effects of this style are far less noticeable, so I'm not sure whether or not it warrants a change.

[lifehackett]

Now that you mention that you develop each component as its own npm package the structure makes more sense.

So the approach I typically do is probably a derivative of c. I create subdirectories for a feature instead of a component.

components/user/profile.jsx
components/user/name.jsx
components/user/address.jsx

Now perhaps profile as a container/frame should go somewhere else, and perhaps you wouldn't have name.jsx but instead textInput.jsx somewhere in components/common/ and pass in some props to make it a name input, but those distinctions aren't really the point I'm trying to make.

The main difference is that I don't typically have the spec and style files in the same directory as the component and including those might start to get messy with my structure. I guess you could go another layer down

components/user/name/index.js
components/user/name/index.spec.js

This is roughly equivalent to your hierarchy now.

I think option a is the least desirable when developing as entire project (as opposed to individual packages) for the reasons @jonaswindey described. Options b and c each have their own smells as @davezuko pointed out; I think I slightly prefer b as well, unless you can think of a way to make the feature approach work in conjunction with the specs and styles in the same folder.

[dvdzkwsk]

The feature-focused structure makes sense, I've just never worked on a project that's laid out in that way so it honestly never crossed my mind. Now that you describe that folder structure, separating tests out from the src directory seems more meaningful and solves some of the clutter problems that option c presents.

I think for now switching to something close to option b is the best course of action, and hopefully the project remains configurable enough that if people want to take it a different direction they can.

I'll look into making the relevant changes tonight or tomorrow.

[dvdzkwsk]

I just committed a branch to update the directory structure and naming conventions within src. I ended up following something a bit closer to option c simply because, with the todo example gone, there just aren't that many files.

[dvdzkwsk]

Merged structural changes with 238e9be