conventions

Feature-centric

Webpack allows source files to be directly imported, regardless of type.

This means that you do not need an assets directory. Your javascript, SASS, images, and other assets (even your favicon) may be co-located with their feature.

Resist naming directories by their content-type.

Compositions

The /app directory is reserved for one or more compositions.

file structure

A composition is defined by an index.html file. It may additionally have any number of .js and/or .scss files. These files are the entry point for each application to be built.

There may be a composition in the root of the /app directory and/or any number of compositions in subdirectories.

For example, a root composition, plus compositions foo and bar:

/app
    index.html
    index.js
    [index.scss]
    /foo
        index.html
        index.js
        [index.scss]
    /bar
        index.html
        index.js
        [index.scss]

composition root pattern

The composition root is a superior pattern for applications composed with dependency injection. It is the convention for Angularity and is strongly recommended.

The entry-point files inside the \app directory import source files from outside the wider library and compose the Angular application.

For small applications, there should be no reference to angular.module() outside of the composition root.

Larger applications may pull in modules from within the library. However the overall module count is much lower than in a typical angular application.

Using the single composition root (or a small number of them) allows you to easily to find the concrete implementation of a given component. It also allows you to build multiple applications to help your development, without duplicating your code.

Source files

You do not need a /src directory. Files can live anywhere outside the composition /app directory.

These files may contribute to the compositions, or may be referenced directly should this project become a library. In which case you will want a pure file path.

For example, where some-library uses a /src directory it leads to inelegant imports.

require('some-library/src/modal/foo');  // src directory
require('some-library/modal/foo');      // without src directory

That said, many people adopt a /main or /src directory. Establish a convention in your team.

Built files

The app mode will build composition(s) to the /app-build directory.

The release mode will build composition(s) to the /app-release directory.

The test mode will build all unit tests as a single test suite to the /app-test directory.

.gitignore

The following ignore configuration is suggested:

/node_modules
/bower_components
/app-*
npm-debug.log