The how and why of using the --create-application flag with Angular CLI to create a Workspace without the initial application

A nice addition to Angular CLI 7.0.0 was the --create-application flag. In this article I will discuss how and when to use this new feature. It will be especially useful when creating Angular libraries.

NOTE: Angular CLI accepts both camelCase and kebab-case for this option. So, anywhere you see --create-application, you can also use --createApplication. For more details see my article:
Angular CLI: camelCase or kebab-case

Before the flag: --create-application

By now you have created some or even many Angular applications using Angular CLI. Typically, we do something like this:

ng new foo

When we do this, Angular CLI creates the initial application that we all know and love in src/app directory in our Angular Workspace.

Usually, this is exactly what we want. However, this initial application can cause problems when we want to generate an Angular Library.

You probably remember from my article Creating a Library with Angular CLI how I recommended creating a Workspace and then renaming it. We did this so the initial generated application wouldn’t conflict with our library’s name. Well, I have good news: we don’t need to use this convoluted strategy anymore.

Using --create-application

The --create-application flag is used with the ng new command. Setting this to false tells ng new not to create the initial Angular application in the Workspace. By default this flag is set to true to match the behavior of the previous versions of Angular CLI.

Here is how it is documented on angular.io:

Notice the documentation uses camelCase.

To create an Angular Workspace with no initial application we use:

ng new foo --create-application=false

Doing this creates an Angular Workspace that seems rather empty compared to what we have been used to in the past. Although, it does have some important things:

  • package.json
    Includes all the usual dependencies we need for Angular
  • angular.json
    The Angular config file but with no projects
  • As for README.md, tsconfig.json, tslint.json, and node_modules, it’s basically the same as it ever was.

You will notice that there is no src directory. Later, a projects directory will be added when we generate a library or application.

Since we set the --create-application flag to false, there is no initial application. And hence, if we try to do something like ng build or ng serve, we get an error:
Could not determine a single project for the ‘build’ target.

When would I use this?#

OK, that’s a valid question. After all, the initial application created by Angular CLI is a great starting point. I mean hey! It even has Unit Tests!

One great reason to set --create-application=false is so we can use ng generate to create an Angular Library.

For example, typically when creating an Angular Library you want the following:

  • An Angular Library in your projects directory
  • An Angular Workspace with the same name as your Angular Library
  • A test application that provides example uses of our Angular Library

As I mentioned at the beginning of this article: previously creating a Workspace with the name of our library resulted in the initial application being created with the same name. This prevented us from using that name for our Angular Library, which was the main reason we created the Workspace in the first place.

An example#

Let’s create an example Angular Workspace that fits the criteria we outlined above. Assume that we want to create an Angular Library named foo-lib.

The Workspace#

So first we will create an Angular Workspace with the same name as our intended library. Remember to use the --create-application=false flag:

ng new foo-lib --create-application=false

When you get asked about the Router and CSS just choose the defaults.

The Library Project#

Now that we have our Angular Workspace, we can add the library project to it. If you read my article about creating Angular Libraries, you know that I recommend always using a prefix:

cd foo-lib
ng generate library foo-lib --prefix=foo

This adds a projects directory containing a foo-lib directory for our newly generated foo-lib Angular Library.

The Test Application#

Finally, we want an application that we can use to call our Angular Library. We can use this application for testing and maybe even for documenting examples of using our Angular Library.

ng generate application foo-tester

This adds a foo-tester directory in the projects directory for our newly generated test application. Additionally, Angular CLI adds a foo-tester-e2e project for end to end testing.

Building, Serving, and Testing#

Now that we have our projects in place, we can use Angular CLI to build, serve, and test.

You will want to always specify the project that is your target.

Build#

To build our foo-lib Angular Library we use:

ng build foo-lib

Note that, since version 6.1, Angular CLI always builds libraries in production mode so we don’t use the --prod flag.

To build our test application we use:

ng build foo-tester --prod

Unlike a library, when building an application we do use the --prod flag.

Serve#

We don’t serve our library. But, we can serve our application like this:

ng serve foo-tester

Test#

We can run Unit Tests for both our Angular Library and our test application.

To run the library tests:

ng test foo-lib

And, to run the application tests:

ng test foo-tester