//tiagogm

Notes on Structuring aurelia apps

28 Apr, 2016

Over the past few weeks I've working with the Aurelia framework, and I've been liking it quite a lot.
The framework is quite stable and has RC release quickly approaching!

If you're trying to use aurelia for something more serious you will most likely be wondering about best pratices and project structure and etc.

This is an area I still find aurelia lacking, as the docs are very slim and there is not a lot of documentation out there. There is a skeleton you can get started with, but it's not very complete. it's a skeleton after all.

Fortunately there is more and more community activity around topics like this.
Aurelia is also a very well designed framework, which makes it very flexible.

Since in you can define everything in your app as a component, it's easy to break you app in multiple components or modules, depending on your needs.

As of now, you can use start using Aurelia in a few different ways. I am using aurelia with wepack and ES6.
Naturally, I started with aurelia's webpack+es6 skeleton.

This is how I ended up structuring my aurelia app:

Code Structure

This is the code structure based on the current Aurelia best pratices and our own needs.

  • /docs - docs generated by esdoc - see esdoc
  • /locale - List of translation files - see i18next
    • /[en|pt|etc]/translation.json
  • /src
    • /configs - configs files for app, plugin, etc
      • /dev
      • /prod
    • /img
    • /styles
    • /components
      • /elements - reusable components
      • /value-converters
      • /attributes
    • /features - contains 'aurelia features'
    • /lib - 3rd party code not coming from node_modules for w/e reason
    • /pages - all pages of the app that match a route
    • /services - app domains logic lives inside a service
    • /shells - app shells/entry points
    • main.js - entry point of the app. bootstraps aurelia
    • /styleguide
      • /lint - linting rules
    • /tests

As you can see the structure is quite similiar to aurelia's peer freameworks. There just a few extra directories for types of components aurelia offers "out-of-box".

NPM Tasks

These are some of the npm tasks I have defined for my workflow:

    "dev": "webpack-dev-server --config webpack.config.js --hot --inline --progress --devtool eval",
    "build": "webpack --config webpack.config.js --progress --profile",
    "dist": "webpack -p --config webpack.prod.config.js --progress --devtool source-map",
    "cplang": "cp -R locale dist/",
    "deploy": "npm run dist && npm run cplang",
    "test": "karma start",
    "esdocs": "esdoc -c esdoc.json"

Webpack config

These are the most relevant parts of the the webpack config I am using:


//...
    new AureliaWebpackPlugin({
      includeSubModules: [
        { moduleId: 'aurelia-auth' },
        { moduleId: 'aurelia-i18n' }
        //..etc
      ]
    }),
    //...
    new DefinePlugin({
      __VERSION__: JSON.stringify(pkg.version),
      __ENV__: JSON.stringify('DEV')
    })
  ],
//...
  resolve: {
    alias: {
      components: srcPath + '/components/',
      services: srcPath + '/services/',
      features: srcPath + '/features/',
      utils: srcPath + '/utils/',
      images: srcPath + '/assets/img',
      styles: srcPath + '/assets/styles',
      lib: srcPath + '/lib',
      langs: srcPath + '/langs',
      configs: srcPath + '/configs',
      envconfigs: srcPath + '/configs/dev'
    }
  },

The prod is pretty much similar except for prod specific path/etc.

It's the best looking webpack cfg file, but I'm not an expert on Webpack, in fact I try to keep it a simple as possible, unlike a lot of config I see in the wild that get way to obtuse for my tastes.

It's a config file after all, a little repetition for the sake of clarity is not the end of the world.

I find that with this struture I pretty much cover all the stuff I need.

It's a mix of the skeleton code, with some blog posts I read and my own preference.

\> goto /notes