Getting Started with ASP.NET Core JavaScript Services

In February I wrote a quick post titled Angular + ASP.NET Core Quick Start with .NET Core CLI. Within that post, I introduced ASP.NET Core JavaScript Services and demonstrated how to create a new Angular + ASP.NET Core application. Within this post, I will take a closer look at JavaScript Services by exploring the supported client-side frameworks and its many features such as server-side prerendering and webpack dev middleware.

Background

Microsoft ASP.NET Core JavaScript Services is part of ASP.NET Core and it enables developers to easily build Single Page Applications (SPA) with ASP.NET Core. Currently, it includes support for the following client-side frameworks – Angular, Aurelia, Knockout.js, React, React + Redux, and Vue.js.

There are many advantages to using this approach, such as:

• It’s cross-platform, develop on Windows, Mac, or Linux
• Use any source code editor, develop with Visual Studio 2017, Visual Studio Code, Eclipse
• Supports many client-side frameworks, such as Angular, Aurelia, React
• Use the .NET Core CLI, if you are already using .NET Core, you won’t need additional tools
• Provides a streamlined development experience, everything is already configured and optimised so you can focus on building your app
• It’s open-source, you can review the source code and contribute, updates occur frequently

Getting started is easy, just run:

dotnet new angular | aurelia | knockout | react | reactredux | vue

A new project will be created that will use ASP.NET Core and C# for cross-platform server-side code, TypeScript for client-side code, webpack for building and bundling client-side resources, and Bootstrap for layout and styling. Within the new project, developers will benefit from the following capabilities:

If your favourite client-side framework or feature is missing, fear not – this project is open-source and contributions are welcome! Click here to review the contribution guidelines and get started.

Getting started

You will need to set up your development environment. First, ensure that you meet the following prerequisites before continuing:

• Node.js, version 6 or later
• .NET Core, version 1.1 or later

Next, install the ASP.NET Core SPA templates:

dotnet new --install Microsoft.AspNetCore.SpaTemplates::*

Note: The use of ::* in the above command requests the latest version.

That’s it, we are now ready to create a new project.

Creating a new project

In this section I’ll create an Angular project, however, please note that you can go ahead and use your preferred client-side framework such as Aurelia, Knockout.js, React, or Vue.js.

Using the command prompt, execute the following commands:

mkdir AngularSpa
cd AngularSpa
dotnet new angular

This will generate the project for you, preconfigured with ASP.NET Core, Angular, Webpack, TypeScript, C#, ASP.NET Core, and so on. Next, we can restore the server-side dependencies:

dotnet restore

Followed by the client-side dependencies:

npm install

Finally, we can run the project using the following command:

dotnet run

Launch your web browser and navigate to http://localhost:5000/ to view the newly created project.

Important: If you are running entirely from the command line, make sure you’re running in development mode.

In the following sections, I’ll provide an overview of server-side prerendering, webpack dev middleware, hot module replacement, and managing client-side dependencies.

Server-side prerendering

Server-side prerendering allows you to prerender the initial state of your application. This results in faster initial load times, improved search engine optimisation (SEO), and support for site preview (social media apps correctly display a preview image).

You can get an idea of how prerendering works by following these steps (using Chrome):

1. Launch your application, e.g. dotnet run
2. Navigate to http://localhost:5000
3. Press F12 to launch the Developer Tools
4. Select the Network tab and check Disable cache
5. Press F5 to reload the page

Review the results to see the load time, the number of requests, and the amount of data transferred. In my case, it was 1.22 seconds, 6 requests, and 5 MB. This is quite large as it includes all of the client-side dependencies required by your application.

If we disable JavaScript, we can get a rough idea of the difference that server-side prerendering can make:

1. Within the Developer Tools, press F1 to access Settings. Configure as follows:
   
2. Switch back to the Network tab and press F5

This time it took 396 milliseconds, 3 requests, and only 314 KB. A major improvement!

Note: Server-side prerendering is not designed to run your application without JavaScript. It simply delays loading the client-side dependencies to improve initial load times, SEO, and so on.

Server-side prerendering is configured within /Views/Home/Index.cshtml:

Loading...

If you need to disable pre-rending, change the above line to:

Loading...

You can further improve the performance of prerendering by leveraging ASP.NET Core caching:

<br />Loading...

Server-side pre-rending results in a very fast initial load time and an improved user experience.

Webpack dev middleware

Webpack is used to build and bundle client-side resources. Normally you would need to run webpack at the command-line to kick this off, however, with webpack dev middleware this has been automated. To see this in action, follow these steps:

1. Launch your application, e.g. dotnet run
2. Navigate to http://localhost:5000
3. Open /ClientApp/app/components/home/home.component.html
4. Change the following line:

<h1>Hello, world!</h1>

To:

<h1>My Angular SPA</h1>

1. Save your changes
2. Refresh your browser

Your changes will be visible, and that is because webpack is running in the background via the webpack dev middleware.

Webpack dev middleware is added inside the Startup.cs file within the Configure method:

app.UseWebpackDevMiddleware();

With webpack dev middleware enabled and your application running in the Development environment, you can change any client-side file (e.g. TypeScript, HTML, CSS) and the updated version will be available (almost instantly) to the browser. You do not need to run any build commands manually, so you can focus creating new features.

Hot module replacement (HMR)

Hot module replacement is a feature of webpack that improves upon webpack dev middleware. It injects updated modules into the active runtime so that if you add, update, or delete client-side files while the application is running, these changes will be immediately available without the need to refresh the browser. To see it in action, follow these steps:

1. Launch your application, e.g. dotnet run
2. Navigate to http://localhost:5000
3. Press F12 to launch the Developer Tools and confirm that HMR is active with the presence of this console message:
   [HMR] connected
4. Open /ClientApp/app/components/home/home.component.html and change the following line:

<h1>My Angular SPA</h1>

To:

<h1>My Awesome SPA</h1>

1. Save your changes
2. Switch to the browser and view the updated changes (available almost instantly)

HMR is enabled inside the Startup.cs file within the Configure method:

app.UseWebpackDevMiddleware(new WebpackDevMiddlewareOptions {
HotModuleReplacement = true
});

Figure: HMR in action using Visual Studio Code

Using webpack dev middleware with hot module replacement provides the most productive and streamlined development experience available.

Managing client-side dependencies

Client-side dependencies (e.g. Angular and Bootstrap) are managed separately to other files in order to make builds much faster. When you need to add, update, or remove client-side dependencies (e.g. upgrading to the latest version of Angular) you will need to follow these steps:

1. Update package.json
2. Run npm install
3. Update webpack.config.vendor.js
4. Run webpack --config webpack.config.vendor.js

Additional Resources

I hope you’ve found this guide useful. I’ve demonstrated many of the great features with ASP.NET JavaScript Services, however, I did not cover them all. The following resources will help you learn more:

• Microsoft ASP.NET Core JavaScript Services
• Building Single Page Applications on ASP.NET Core with JavaScriptServices
• Building Single-Page Applications with ASP.NET Core

I feel that ASP.NET Core JavaScript Services is an awesome tool for creating single page applications and I am very excited to see how it evolves in the future. Personally, I’d like to see some integration between server-side and client-side validation. Thanks for reading, please feel free to post any questions or comments below.