About The Updated SPA Templates From ASP.NET Core

Install the new spa templates by running the following dotnet cli command,

dotnet new --install Microsoft.DotNet.Web.Spa.ProjectTemplates::2.0.0-preview1-final

More or less everyone working with ASP.NET Core, tried out the following SPA templates shipped with the framework,

These templates are configured to use Angular/React/ReactRedux (based on your choice) on the client side and ASP.NET Core as back-end. Behind the scene a package Microsoft.AspNetCore.SpaServices is used as a middleware to provide different configurable options for your application such as HMR (Hot Module Replacement), Routing Helper, SSR (Server Side Rendering) etc. . Main problem with this approach is that the client frameworks are strictly coupled with the back-end. So even though if you want, you can't actually run them in a decoupled way.

However, if you worked with the @angular/cli and create-react-app; you already know how to create apps with these command line interfaces. Also you are familiar with the semantics and idioms of these CLIs. Coming from that realm to this feels like a totally new learning curve over again.

Moreover, these spa templates are updated/managed by the MSFT team and the community members. So, if you think further, you may understand that the organization who pushes updates to their respective client side framework doesn't really care whether the changes will break the spa templates or not. Because the spa templates aren't their own products.

That's why the existing configuration from these templates may or may not be able to make your application work when you try to update your client libraries. For example, the existing angular spa template won't work if you update your angular version to the most recent one i.e. Angular 5.

On the other hand, what the framework people do is that when they update their frameworks, they also update the CLIs. So, developers find it easy to work with the newly updated framework instantly. But in case of these templates, you have to wait for configuration changes, if needed; to start working with the updated clients.

In simple words, the CLIs make it easy to start working in a hassle free development environment. With that thing in mind the MSFT team came up with the idea that from now on they will use the CLIs for the front-end and make appropriate changes in the back-end only to make them work with ASP.NET Core.

So, a new extension to the Microsoft.AspNetCore.SpaServices has been introduced, Microsoft.AspNetCore.SpaServices.Extensions. The extension will let you spin up any framework respective CLI based development servers from an ASP.NET Core back-end. The following code snippet shows how to configure app.UseSpa() middleware to start spinning up an Angular CLI based development server while in development mode,

app.UseSpa(spa =>
    spa.Options.SourcePath = "ClientApp";

    if (env.IsDevelopment())
        spa.UseAngularCliServer(npmScript: "start");

Similarly if you are working with React, you will use the development server created using create-react-app and the configuration changes that is needed to run that development server is the following,

spa.UseReactDevelopmentServer(npmScript: "start"); 

Of course the ClientApp folder contains all the files generated from the respective CLIs hence the spa.Options.SourcePath = "ClientApp";

In production mode, you no longer need the development server rather you need the vendor and application scripts/files/images, bundled and minified for easy deployment. That's why we need the following configuration,

services.AddSpaStaticFiles(configuration =>
    configuration.RootPath = "ClientApp/dist";

The published scripts/files/images will be in the dist folder under the ClientApp hence configuration.RootPath = "ClientApp/dist";. The folder will be automatically get generated when in production mode.

The newly updated preview templates can be installed using the dotnet CLI. Run the following command and you are good to go,

dotnet new --install Microsoft.DotNet.Web.Spa.ProjectTemplates::2.0.0-preview1-final

Once installed, use dotnet new angular/dotnet new react/dotnet new reactredux to create angular/react/reactredux app using the new templates.

In the new templates the package.json file is now in the ClientApp folder. So any third party package installation requires running npm command in the ClientApp folder.

cd ClientApp
npm install --save @angular/material

Remember the development servers are not strictly coupled with the back-end. So if you want, you can run ng serve (for Angular) or npm start (for React) directly on the ClientApp folder and the applications will run without an ASP.NET Core back-end.

By default, both the development server and your ASP.NET Core back-end will run on a single configured port. But if you do want to run them separately, you can configure a proxy address for your development server. For that you have to replace the call to your app.UseAngularCliServer() or spa.UseReactDevelopmentServer with something like the following,


After you set up a proxy address for your development server, you can use the npm start command to spin up the development server separately from your back-end server.

In the previous templates we used to have a TagHelper, asp-prerender-module to enable Server Side Rendering support in our Angular apps. We no longer need this TagHelper and also we don't have any specific placeholder in some razor view where the whole client application is rendered. Instead the index.html under ClientApp/scr is the main entry point of our application. The official documentation talks at length about how to enable SSR in the following url,


And that is pretty much all you need to know about the updated spa templates from ASP.NET Core. The templates are still in preview mode and as the team mentioned, we are hoping to have a RTM release in January 2018.