62

When installing the Aurelia navigation skeleton app it is far to overwhelming with all the 3rd party modules and ready-made scripts it uses. For me who have a good picture of what most of it is in theory, have a hard time learning when I can't do it one step at a time. For this reason I would like to set up a minimal Aurelia project by myself and then add complexity to it as I go along.

Main question: Which steps are necessary to set up a simple Aurelia project?

Assumptions:

  • I already have a Node server backend that can serve files.
  • I want to use ES6/7 (Babel).
  • I want to use system.js for module loading.
  • No unit or e2e tests, no styles, no docs.
  • As few node and jspm modules as possible.

Please do also explain a little on each step and describe what the necessary Aurelia files is and does.

I would be very thankful for any help :)

Jeremy Danyow
  • 26,470
  • 12
  • 87
  • 133
micnil
  • 4,705
  • 2
  • 28
  • 39

6 Answers6

80

Install the jspm command line interface. jspm is a package manager for client-side dependencies. Read up on it... it's great.

npm install jspm -g

Create a folder for the project.

mkdir minimal
cd minimal

Initialize jspm client package management... Accept all the defaults EXCEPT use the Babel transpiler option (vs Traceur)

jspm init

Enable all the fancy cutting edge babel goodness by adding the following line to the babelOptions in your config.js (jspm init created the config.js file):

System.config({
  defaultJSExtensions: true,
  transpiler: "babel",
  babelOptions: {
    "stage": 0,      <------ add this to turn on the hotness
    "optional": [
      "runtime"
    ]
  },
  ...

Install Aurelia

jspm install aurelia-framework
jspm install aurelia-bootstrapper

Create an index.html that uses the SystemJS loader (jspm's module loader counter-part) to bootstrap Aurelia.

<!doctype html>
<html>
  <head>
    <title>Aurelia</title>
  </head>
  <body aurelia-app>
    <h1>Loading...</h1>

    <script src="jspm_packages/system.js"></script>
    <script src="config.js"></script>
    <script>
      System.import('aurelia-bootstrapper');
    </script>
  </body>
</html>

When Aurelia bootstraps it's going to look for a default view and view-model... create them:

app.js

export class App {
  message = 'hello world';
}

app.html

<template>
  ${message}
</template>

Install gulp and browser-sync to serve the files:

npm install gulp
npm install --save-dev browser-sync

Add a gulpfile.js

var gulp = require('gulp');
var browserSync = require('browser-sync');

// this task utilizes the browsersync plugin
// to create a dev server instance
// at http://localhost:9000
gulp.task('serve', function(done) {
  browserSync({
    open: false,
    port: 9000,
    server: {
      baseDir: ['.'],
      middleware: function (req, res, next) {
        res.setHeader('Access-Control-Allow-Origin', '*');
        next();
      }
    }
  }, done);
});

Start the webserver.

gulp serve

Browse to the app:

http://localhost:9000

Done.

Here's what your project structure will look like when you're finished:

project

Note: this is just a quick and dirty setup. It's not necessarily the recommended folder structure, and the loader is using babel to transpile the js files on the fly. You'll want to fine tune this to your needs. The intent here is to show you how to get up and running in the fewest steps possible.

Jeremy Danyow
  • 26,470
  • 12
  • 87
  • 133
  • How can I add another npm package to a project like aurelia? For example, I've been trying to integrate tumblr.js api but I can't seem to access it from any of my modules – Felipe Aug 29 '15 at 04:57
  • The new jspm release has jammed everything up- I'll update this guide once it's sorted out – Jeremy Danyow Feb 01 '16 at 05:26
  • has this been addressed by aurlelia devs? how is one supposed to start a new project with a simple setup? – northamerican Feb 01 '16 at 05:31
  • 2
    We're working with the jspm team to get it sorted out- the jspm build with the breaking changes was just released – Jeremy Danyow Feb 01 '16 at 05:32
  • Bonus question - how do I run such a minimal scenario in a ```plnkr``` *(or any other place)* so I could ask better questions on SO? – Mars Robertson Jul 01 '16 at 19:05
  • 1
    @MichalStefanow we use https://gist.run/?id=7542e061bc940cde506b (it's built with Aurelia) – Jeremy Danyow Jul 02 '16 at 11:15
  • The only thing I would do different from the answer is to use `lite-server` which is a wrapper on browser sync that John Papa made for working with SPAs. The other is I would use npm scripts such as `npm start` to expand upon the existing package.json instead of adding another moving part by using gulp. – LostBalloon Sep 05 '16 at 22:34
  • 10
    Anyone else remember when development was simple? – Alan B Sep 27 '16 at 07:28
  • This was a great little walkthrough for setting up a node project in general, I learned a lot from it since I normally work in visual studio. Thank you – James Cootware Oct 04 '16 at 17:42
  • Hi @JeremyDanyow. Great guide. It's nice to have Aurelia in a minimal version. I just used the guide, but i had to do a small change to the app.js file to make things work. I've moved the "message" to a constructor. `constructor(){ this.message = "hello world" } ` And now it's working perfectly, thanks. – Thylle Nov 14 '16 at 09:12
  • 1
    As of this comment, you will also need to do 'jspm install aurelia-pal-browser' (known issue: https://github.com/aurelia/skeleton-navigation/issues/281). And I installed node.js v7.7 instead of v6.10. – smoore4 Mar 22 '17 at 21:01
5

Check the article https://github.com/aurelia-guides/aurelia-guides.md-articles/blob/master/Building-Skeleton-Navigation-From-Scratch.md written specifically to ease the introduction to Aurelia.

nikivancic
  • 188
  • 1
  • 1
  • 8
2

The Aurelia documentation has a really nice chapter that explains what each part of a simple application does, one step at a time. It is probably a good start that do not overwhelm you with dependencies like Bootstrap and similar.

Also note that there is now a CLI interface to Aurelia that simplifies setting up a project from scratch.

martin
  • 825
  • 10
  • 15
2

I created a repo (up to date as of April 2017) that includes the absolute barebones necessary items to run Aurelia at https://github.com/nathanchase/super-minimal-aurelia

It's an ES6-based Aurelia implementation (rather than Typescript), it incorporates code-splitting by routes (using the latest syntax in Aurelia's router to designate chunk creation according to files under a route), and it works in all evergreen browsers AND Internet Explorer 11, 10, and 9 thanks to a few necessary included polyfills.

Nathan Chase
  • 2,071
  • 2
  • 18
  • 15
1

I would definitely use the aurelia-cli for this.

Do the following: npm install -g aurelia-cli

Then to start a new project do: au new project-name

to run your project do: au run --watch

I really feel the aurelia-cli "is the future" for aurelia!

Johan O
  • 402
  • 5
  • 7
  • What does this generate? is it a minimal example? This question is mainly for the smallest working solution, not the quickest working solution. – micnil Apr 06 '17 at 08:32
0

I'm working with a Java Play project and still want to use the scala conversion of HTML file. Thus, I did the following

  1. Download aurelia-core available via the basic aurelia project, which is linked from the quickstart tutorial
  2. Fetch SystemJS using WebJars: "org.webjars.npm" % "systemjs" % "0.19.38"
  3. Since systemjs-plugin-babel is currently unavailable as webjar, I ran npm install systemjs-plugin-babel and copied the fetched files to the assets directroy

The HTML code is like this:

<div aurelia-app="/assets/aurelia/main">
  ...loading data...
</div>
<script src="@routes.Assets.versioned("lib/systemjs/dist/system.js")" type="text/javascript"></script>
<script src="@routes.Assets.versioned("javascripts/aurelia-core.min.js")" type="text/javascript"></script>
<script>
  System.config({
    map: {
      'plugin-babel': '@routes.Assets.versioned("javascripts/systemjs-plugin-babel/plugin-babel.js")',
      'systemjs-babel-build': '@routes.Assets.versioned("javascripts/systemjs-plugin-babel/systemjs-babel-browser.js")'
    },
    transpiler: 'plugin-babel',
    packages: {
      '/assets/aurelia': {
        defaultExtension: 'js'
      }
    }
  });
  System.import('aurelia-bootstrapper');
</script>

Use main.js etc. from the quickstart tutorial

koppor
  • 19,079
  • 15
  • 119
  • 161