How To Structure An Aurelia Application
When it comes to building a web application, nothing causes more confusion than working out how to structure it (besides what to name things, of course).
In the beginning, it is easy enough to just throw all of your code into the root of the
src directory without a care in the world. But as the complexity of your application grows and subsequently its size, this approach fails.
I have been working on a large-scale Aurelia application for about 6 months now and have a structure that has allowed me to move quickly without worrying about clutter or where to put everything.
In the root directory we still have our; app.html, app.js (and if you one) the main.js file as well.
First up we have an
assets directory which contains sub-directories
images — you might also have a directory which contains fonts as well. This is where all styling and presentational stuff is kept (which is then handled by Gulp tasks).
Then we have a
components directory for storing common components that are applicable to the whole application on a global level. Such as a header include or navigation bar.
Followed by a
pages folder where all of our application specific logic lives. I create sub-folders inside of this folder to mirror my routes. For example if I have a route that is:
http://myapp.com/users then I would create a folder within
For the index page of a particular route I will create a
index.js View/ViewModel pair for this particular route. If users has sub routes, I will create more sub-folders to reflect the route. So if I have
http://myapp.com/users/account/123 — then I would have a folder structure that looks like this:
pages users index.html index.js account index.html index.js
Matching your application directory structure and naming conventions to that of your router makes finding particular routes a whole lot easier than guessing which part of the application is rendering the current page you are viewing.
We also have a
resources directory which contains all of your value converters and global resources. Inside of my
resources folder I have two subfolders:
custom-elements which you can probably guess what those contain.
And then a lesser-important
lib directory which contains non-page/route specific code. I put in things like classes with custom functions for doing basic utility-like things in the application and adaptors for third-party libraries.
Another optional directory you might have is the
services directory which contains singleton based services. In here I have my service singleton classes for keeping track of the current user state, working with an API and so on.
If you skipped ahead or just found it hard to follow along, lets recap and structure our Aurelia application.
- src = Root directory and contains; app.html, app.js and main.js
- assets = Where all assets of the app live (with separate sub-folders)
- components = Where common application components like headers, navigation, footer, etc live
- lib = Where generic non-app specific code lives. Utility classes and functions for doing utility-like tasks
- pages = Where our route matching page Views and ViewModels live. This matches the predefined routes
- resources = Where our custom elements and value converters live
- services = A folder for singleton service classes like keeping track of state or working with API’s
src/ app.html app.js main.js assets/ fonts/ images/ styles/ components/ lib/ pages/ page1/ index.html index.js page1Sub/ index.html index.js resources/ custom-elements/ value-converters/ services/