Aurelia CLI with a new command and templates

Best Practices
1

Continuing the discussion from MVC core webpack template:

This information is presented as the starting point for discussion. The code is not intended for ‘live’ use.

I have a fork of Aurelia CLI.

As a result of previous thoughts and posts, I have added a new command to the cli called ‘dot-new’. This facilitates the installation of ‘dotnet new’ templates that are hosted externally to the CLI. As I mentioned in my previous posts, I thought that it would be better if templates were external to the CLI and not generated conditionally in code. This could make the addition of extra templates and the maintainability of existing templates much easier (as simple as adding a new entry into a .json file).

If anyone would like to test it, simply clone and install the ‘external-template-cli-projects’ branch.
First ensure that aurelia-cli is not installed. Open a shell to a folder of your choice and clone the repo and install. I use Windows 10 and VS 2017. This is how I do it:

git clone -b external-template-cli-projects https://github.com/constructor/aurelia-cli-fixes.git
cd aurelia-cli-fixes
npm install -g

This version of aurelia-cli should now be installed.
(Note: To remove it use npm uninstall aurelia-cli -g. Install the official aurelia-cli as usual.)

Now, to test the templates:

Create a project from a template in a similar to usual but using the command au dot-new as such:

au dot-new -n {project-name}
or…
au dot-new -n {project-name} -o {output-directory}
or…
au dot-new -here

…and follow the cli installer. First of all you will be presented with this set of options:

What template type do you require?

  1. Web App (Default)
    A selection of templates for web based apps
  2. Mobile App
    A selection of templates for hybrid mobile and progressive web apps
  3. Plugin
    A starting point for Aurelia plugin development.

Select option 1 as there are only 2 different test templates at the moment. Adding more is as simple as editing a .json file.

After selection option 1 you will get:

What web template do you require?

  1. MVC Webpack (Default)
    ASP.net core 2.0 MVC with webpack.
  2. Aurelia Materialize Bridge
    ASP.net core 2.0 MVC with Webpack and Aurelia Materialize Bridge.
  3. MVC Webpack again…
    ASP.net core 2.0 MVC with webpack.
  4. Aurelia Materialize Bridge and again…
    ASP.net core 2.0 MVC with Webpack and Aurelia Materialize Bridge.

Here, option 1 and option 2 have templates that you can test. Options 3 and 4 are simply different links to the same templates in options 1 and 2 for demo purposes. Make a selection between 1 or 2.

After a selection you will get:

Confirm selection and proceed or select a different template?

  1. Proceed with selection (Default)
  2. Select a new template

Hopefully this is self explanatory. Select 1 to proceed. The template is generated. You then get the options to install the project dependencies as usual.

I use a Windows 10 and VS 2017 setup. I install the dependencies and open the .csproj in VS and press F5 and the project runs. But it is also just as simple to cd into the new project folder and au run and au build as usual.

These templates are served to the cli via Nuget using . I am looking now at achieving the same but pulling the templates from a git repo and therefore not using Nuget or ‘dotnet new’ command. Is this approach worth while pursuing? Pulling a list of available templates into the cli from a registry of some kind over a network is also something I like the idea of.

Updates:

  1. Templates directly from GitHub repo (no ‘dotnet’ templating requirement)
  2. Template processing of content and filenames from command options.
2 Likes
2

I have now got this working directly from github. The benefit of this is that there is no ‘dotnet new’ templating being invoked. The downside is that there is no template processing of project name or command line options.

Now I simply:

au template or…
au template -o {folder-name} or…
au template -output {folder-name}

Follow the CLI options wizard.

The two available test templates are hosted and pulled from GitHub. An MVC Webpack template and another that has Aurelia Materialize Bridge. Maintaining and updating templates could be much easier this way?

3

If I am allowed to extrapolate from your explanations, can I assume that you envision a “super cli” which would be able to generate (and hopefully maintain) full stack application skeleton? This is of particular interest to me since the day when our team created the first Monterey prototype (see this as an example)

4

I think of it this way. I believe the CLI should be able to reach out and access templates, rather than only having the templates generated inside the CLI itself (in code) which poses maintainability and extensibility challenges.

I started to look at the CLI project source as I had a below average experience a few weeks ago when I revisited Aurelia. My expectation of tooling is that when I install and run the commands it should ‘just work’. This was not my experience. On looking into it, and a few fixes later, I saw that the templates are actually generated conditionally and thought maybe it would make sense to have the template code external to the CLI. This led to these experiments. So my aim was not a “super CLI” rather than having a more maintainable and possibly extensible way of handling Aurelia CLI templates.

3 Likes
5

I love the idea of additional templates hosted externally! I think the base templates should still be contained as they are as the standards. I hope the external templates would be required to include some sort of future-proofing (along the lines of version checks & requirements) to avoid causing more grief when an older template doesn’t build due to updates of various things.

1 Like
6

@ajoslin103 A selection of good, maintainable templates can really help with getting up and running quickly. The initial experience of a user is powerful and can determine if someone continues to use Aurelia or walks away in frustration. They also make learning much quicker.
I have now added a template processing stage in the ‘au template’ command. This performs
a series of transformations on the template source, at install time, based upon the command options input by the user. These are in the form of string interpolation and file renaming. This makes thinks a lot more flexible.

7

One of the limitation of using static files as the basis for templates (as opposed to dotnet templates for instance) is that there is no template processing, of content or filenames, when generating a new project. I have now added rudimentary template processing to the au template command I added earlier. It is used like this:

au template -n App -o Src -ns Designs.Digital.App

Here:
-n App would set the name of the project file to App.csproj
-o Src would set the output folder to be named Src
-ns Designs.Digital.App would set the base namespace of all the classes in the project to Designs.Digital.App. This is throughout the project.

Values entered at the command line when invoking the au template command can be mapped to a template using an aurelia.template file at the root of the template. So any values entered can be used in the processing of the template during project generation. The template processing consists of file content string replacement and file renaming.

So now it should be possible to create templates of any project type and have some basic customisation based on user input.

As @ajoslin103 mentioned, versioning the templates with metadata in the aurelia.template file would be required, and maybe template specific install process and instructions via individual WorkflowEngine definitions?

8

You may consider the ‘degit’ project: https://github.com/Rich-Harris/degit

1 Like