DEV Community: Lars Willemsens

A quick introduction into Vite.AspNetCore

Lars Willemsens — Mon, 02 Mar 2026 08:35:29 +0000

If you want to build an MPA (Multi-Page Application) in ASP.NET Core with Vite then Vite.AspNetCore provides you with just the tools you need. The project is well-documented on its GitHub page and there are some very complete samples to base your project off of.

While testing out my setup, I gained some insights into how the library works and I made this little retrospective to document them.

Here's my project: AspNetVite

First steps

I started off by creating an ASP.NET Core MVC application.

mkdir AspNetVite
cd AspNetVite
dotnet new mvc
dotnet new gitignore

Next, I added the NuGet package and updated my Program.cs by following the project's setup instructions.

Then I copied some config files from one of the sample projects to my own project. These were: package.json, tsconfig.json, tsconfig.node.json, and (probably the most important one) vite.config.ts.

I customized package.json (name, author, version, ...) and ran my first npm i. You can see all changes I made in my commit log. These four Node-related files can be found in this commit or you can grab them from the sample project linked earlier.

A big difference with the traditional ASP.NET MVC template is that Vite.AspNetCore uses an Assets folder. In vite.config.ts, you can see that Vite refers to Assets/main.ts and that it will wipe your wwwroot. ☠️

All TypeScript, Styling, and even the precious favicon had to make the move to Assets. I created an Assets/main.ts with a simple log statement and chose to do my styling with Sass so I created an Assets/main.scss that I imported from the TypeScript file.

A TypeScript file can be imported in a view using the vite-src tag-helper so I updated _Layout.cshtml by adding this line:

<script type="module" vite-src="~/main.ts"></script>

... and updated _ViewImports.cshtml to enable the tag-helper:

@addTagHelper *, Vite.AspNetCore

(I also moved the Scripts section to the head element because we no longer live in the 2000s 😉.)
Check out the changes here.

There was still some code in wwwroot that had to be moved over:

I moved styling from site.css (and also from _Layout.cshtml.css!) to main.scss.
I moved favicon.ico to the Assets directory.
I removed the entire wwwroot from my git repository.

The code depends on Bootstrap and JQuery so instead of having them in the wwwroot, I needed to download them through npm instead. In package.json, I added these dependencies:

"dependencies": {
    "@popperjs/core": "^2.11.8",
    "jquery": "^3.7.1",
    "jquery-validation": "^1.21.0",
    "jquery-validation-unobtrusive": "^4.0.0",
    "bootstrap": "^5.3.8",
    "bootstrap-icons": "^1.13.1"
},

Assets/main.scss was then updated to import Bootstrap styles:

+@use "bootstrap/dist/css/bootstrap.css";
+@use "bootstrap-icons/font/bootstrap-icons.css";

 h1.display-4 {
     background-color: #0f5132;
 }

... and Assets/main.ts, was updated to import Bootstrap's JavaScript code, JQuery, and other dependencies:

+import '@popperjs/core';
+import 'bootstrap';
+import 'jquery';
+// Using the next two lines is like including partial view _ValidationScriptsPartial.cshtml
+import 'jquery-validation';
+import 'jquery-validation-unobtrusive';

 import './main.scss';

 console.log('Hello, world!');

_Layout.cshtml still referred to the old Bootstrap and JQuery, so it needed fixing:

-<script type="importmap"></script>
-<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
-<link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />
-<link rel="stylesheet" href="~/AspNetVite.styles.css" asp-append-version="true" />

 <script type="module" vite-src="~/main.ts"></script>
 @await RenderSectionAsync("Scripts", required: false)
+<link rel="stylesheet" vite-href="~/main.scss" asp-append-version="true" />

 ...

-<script src="~/lib/jquery/dist/jquery.min.js"></script>
-<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
-<script src="~/js/site.js" asp-append-version="true"></script>

This was probably the biggest breaking change of the entire process. The full list of changes can be seen here.

Thankfully, I was rewarded with a first working version. (Hurray!)

Time to start cooking! 👨‍🍳

Here you can see me try out Bootstrap Icons.
This was easy:

<p>There should appear an 'archive' icon here: <i class="bi bi-archive"></i></p>

(note that I imported Bootstrap Icons from Assets/main.scss earlier)

I also tested a Bootstrap popover as can be seen here.

I had to add some HTML:

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover"
        data-bs-title="Popover title"
        data-bs-content="And here’s some amazing content. It’s very engaging. Right?"
    >Click to toggle popover</button>

... and a bit of TypeScript:

 import '@popperjs/core';
-import 'bootstrap';
+import * as bootstrap from 'bootstrap';
 import 'jquery';
 // Using the next two lines is like including partial view _ValidationScriptsPartial.cshtml
 import 'jquery-validation';
 import 'jquery-validation-unobtrusive';

 import './main.scss';

 console.log('Hello, world!');

+/**
+ * https://getbootstrap.com/docs/5.3/components/popovers/#enable-popovers
+ */
+function enablePopovers() {
+    const popoverTriggerList = document.querySelectorAll('[data-bs-+toggle="popover"]');
+    Array.from(popoverTriggerList).map(popoverTriggerEl => new +bootstrap.Popover(popoverTriggerEl));
+}
+
+enablePopovers();

To validate the complete setup, I tested client-side validation. Since client-side validation is needed on certain views but not on others, this was the perfect time to split up the front-end logic. I created Assets/validation.ts with this content:

// Importing this file is like including partial view _ValidationScriptsPartial.cshtml
import 'jquery-validation';
import 'jquery-validation-unobtrusive';

console.log('Loaded validation.ts');

And removed the validation code from main.ts:

 import '@popperjs/core';
 import * as bootstrap from 'bootstrap';
 import 'jquery';
-// Using the next two lines is like including partial view _ValidationScriptsPartial.cshtml
-import 'jquery-validation';
-import 'jquery-validation-unobtrusive';

 import './main.scss';

-console.log('Hello, world!');
+console.log('Loaded main.ts');

...

I created a contact form, an action method in HomeController (the whole nine yards), and imported the client-side validation code from my view:

@section Scripts
{
    <script type="module" vite-src="~/validation.ts"></script>
}

Not only does this provide confirmation that everything works, but it's also a first step towards building a well-structured multi-page application.

In a multi-page application we want to have multiple bundles. Each bundle can then be imported only on those pages that need it. A production application can quickly expand into dozens of bundles, many of which will be specific to a single page. Through the use of ECMAScript modules, common code (such as utility functions or helper classes) can still be shared across bundles.

Moving to production

Everything worked as long I was in "Development" mode, but "Production" was actually broken.

Three things needed fixing:

Vite config had to be fixed so that it creates multiple bundles, not just for main.ts.
In _Layout.cshtml a different kind of import was needed for "Production" as opposed to "Development".
From csproj, I had to invoke npm commands and specify which files are needed in the published wwwroot.

To fix the bundles for production, I updated vite.config.ts:

 import { UserConfig, defineConfig } from 'vite';
+import fs from 'fs';
+import path from 'path';

 export default defineConfig(async () => {
+    const files = fs.readdirSync('./Assets');
+    const inputEntries = files
+        .filter(file => file.endsWith('.ts'))
+        .reduce((acc, file) => {
+            const fileName = path.parse(file).name;
+            acc[fileName] = path.join('./Assets', file);
+            return acc;
+        }, {} as Record<string, string>);
+
     const config: UserConfig = {
         appType: 'custom',
         root: 'Assets',
         publicDir: 'public',
         build: {
             emptyOutDir: true,
             manifest: true,
             outDir: '../wwwroot',
             assetsDir: '',
             rollupOptions: {
-                input: 'Assets/main.ts'
+                input: inputEntries
             },
         },

 ...

It's important to note that this configuration will treat all .ts files directly under Assets as "entries" (= files that trigger the creation of a new bundle). Code that shouldn't result in an additional bundle should be placed in a subdirectory.

For example:

└── Assets
    ├── entry1.ts
    ├── entry2.ts
    ├── main.scss
    ├── main.ts
    ├── util
    │   ├── utility1.ts
    │   └── utility2.ts
    ├── presentation
    │   ├── presentation-logic1.ts
    │   └── presentation-logic1.ts
    └── services
        ├── service1.ts
        └── service2.ts

Due to the way Vite.AspNetCore works, I also had to change the way styles are picked up in production. In _Layout.cshtml:

-    <link rel="stylesheet" vite-href="~/main.scss" asp-append-version="true" />
+    <environment include="Development">
+        <link rel="stylesheet" vite-href="~/main.scss" asp-append-version="true" />
+    </environment>
+    <environment include="Production">
+        <link rel="stylesheet" vite-href="~/main.ts" asp-append-version="true" />
+    </environment>

Yes, you read that right... in production, styles are includes through .ts files.

Finally, I updated my .csproj file and specified which files should be copied to wwwroot and which (npm) commands are needed to build the application, both in development and in production.
The changes to .csproj can be seen here.

Conclusion

Overall the experience was quite smooth, thanks to the existing sample applications. Once the project structure is migrated, everything "Just Worked™". I found the updates to .csproj and the different way of importing styles in production to be the trickiest. In my opinion, these things weren't very clear from the documentation, but maybe I missed something. 😀

I hope my findings can be of use to someone. Do let me know if that's the case. Just drop a comment below. Happy coding!

Building a multitenant web application with Spring Boot

Lars Willemsens — Mon, 20 Mar 2023 19:54:27 +0000

Let's create a web application to serve multiple different clients or to host a range of sub-sites and platforms.

Spring Boot will be our companion on this trip with JPA/Hibernate taking care of storage and persistence.

Tenants must be disconnected from each other, and users should be able to register to and contribute to the different tenants' websites transparently. In short, users should be oblivious to the fact that the tenants' web applications are part of the one single Spring application.

What this article will be focusing on:

The web application experience. We want to ensure a maintainable application across different tenants' URLs, and security must be kept in check. Each tenant should have their own (sub)domain.
We're using a single database and shared schema. It allows us to reason about tenants on a design level and simplifies data source access. There are many articles and online sources that tackle the challenge of handling multiple data sources.

Our POC will use subdomains of localhost such as tenant1.localhost and tenant2.localhost to mimic the actual experience.
When I register an account at tenant1.localhost, I won't (yet) have an account at tenant2.localhost. In fact, as a user, I should have no clue that both tenants are even served by the same Spring application. I should be able to create an account at tenant2 using the same email address as for tenant1.

The application itself will have "posts" on it. For example, you can think of them as blog posts or news posts.

Unauthenticated users should be able to see all posts.
Authenticated users should be able to contribute by adding new posts.
Tenant administrators should be able to both add and delete posts.

There will be a global administrator role as well. There are no plans to implement anything meaningful for the global administrator in this POC. It could be expanded by adding features to create new tenants or upgrading users to tenant administrators.

Technically, we'll use Spring Web with MVC/Thymeleaf and a REST API. I've set up the project using Gradle, Spring Boot 3 (Spring 6), and PostgreSQL.

The end result of this journey can be found here.

Spring Security

Spring Security will provide a foundation for authentication and authorization. Let's tag a @Configuration class with @EnableWebSecurity and provide a bean of type SecurityFilterChain:



@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

Static assets should fall outside of our security requirements, so we'll add matcher rules such as :



antMatcher(HttpMethod.GET, "/js/**")).permitAll()

I'm assuming a basic knowledge of Spring Security. So far, nothing special yet.

Tenant?... what tenant?

All HTTP traffic to tenant1.localhost, tenant2.localhost, and localhost will arrive at our Spring application (assuming port 8080). We need a way to distinguish between them and OncePerRequestFilter will be our tool of choice. I'll create one and call it TenantFilter. This request filter will grab the tenant from the URL and store it so that we can check it later when further processing the request (i.e., in a controller).
Each web request will be handled by a separate thread, so an excellent place to store this little piece of data is Java's ThreadLocal. (In the future, this should even be compatible with Project Loom's virtual threads.)

One of only a few places in a Spring application where static can be used meaningfully:



public class TenantContext {
    private static final ThreadLocal<String> currentTenant = new ThreadLocal<>();
    private static final ThreadLocal<Long> currentTenantId = new ThreadLocal<>();

    public static String getCurrentTenant() {
        return currentTenant.get();
    }

    public static void setCurrentTenant(String tenant) {
        currentTenant.set(tenant);
    }

    // More getters/setters
}

The filter will use the context class by calling its setters:



public class TenantFilter extends OncePerRequestFilter {
    private final TenantRepository tenantRepository;

    public TenantFilter(TenantRepository tenantRepository) {
        this.tenantRepository = tenantRepository;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        var tenant = getTenant(request);
        var tenantId = tenantRepository.findBySlug(tenant).map(Tenant::getId).orElse(null);
        if (tenant != null && tenantId == null) {
            response.setStatus(NOT_FOUND.value()); // Attempted access to non-existing tenant
            return;
        }
        TenantContext.setCurrentTenant(tenant);
        TenantContext.setCurrentTenantId(tenantId);
        chain.doFilter(request, response);
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        return request.getRequestURI().startsWith("/webjars/")
                || request.getRequestURI().startsWith("/css/")
                || request.getRequestURI().startsWith("/js/")
                || request.getRequestURI().endsWith(".ico");
    }

    private String getTenant(HttpServletRequest request) {
        var domain = request.getServerName();
        var dotIndex = domain.indexOf(".");

        String tenant = null;
        if (dotIndex != -1) {
            tenant = domain.substring(0, dotIndex);
        }

        return tenant;
    }
}

We must override two methods:

doFilterInternal: This method's first -essential- responsibility is to determine if we want to continue processing this request. If the answer is yes, then we call chain.doFilter. Not calling the chain means the end of the road for this request. The other task is to get the tenant's code (slug) from the request URL and to store it for later use. A repository is used to retrieve the ID of the tenant (handy for later!).
shouldNotFilter: tells Spring when this filter is relevant.

We only want to support tenants that exist in our database as well as null (=no tenant). That's why we've added a 404 check.

UserDetailsService

The first place where we will read this ThreadLocal information is from a custom UserDetailsService. The method to override here is loadUserByUsername:



@Service
public class CustomUserDetailsService implements UserDetailsService {
    private final UserRepository userRepository;

    public CustomUserDetailsService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Override
    public UserDetails loadUserByUsername(String email) throws UsernameNotFoundException {
        var tenant = TenantContext.getCurrentTenant();

        if (tenant != null) {
            return loadUser(email, tenant);
        } else {
            return loadGeneralAdmin(email);
        }
    }

    private UserDetails loadUser(String email, String tenant) {
        var user =
                userRepository.findUser(email, tenant)
                        .orElseThrow(
                                () -> new UsernameNotFoundException(
                                        "'" + email + "' / '" + tenant +
                                                "' was not found."));

        var auths = new ArrayList<GrantedAuthority>();
        auths.add(new SimpleGrantedAuthority(user.getRole().getRoleName()));
        return new CustomUserDetails(user.getEmail(), user.getPassword(), user.getId(),
                user.getTenant().getId(), auths);
    }

    private UserDetails loadGeneralAdmin(String email) {
        var admin = userRepository.findGeneralAdmin(email).orElseThrow(
                () -> new UsernameNotFoundException(
                        "'" + email + "' was not found as a general admin."));
        var auths = new ArrayList<GrantedAuthority>();
        auths.add(new SimpleGrantedAuthority(ADMINISTRATOR.getRoleName()));
        return new CustomUserDetails(admin.getEmail(), admin.getPassword(), admin.getId(), null,
                auths);
    }
}

If the tenant is null, we know the user is accessing localhost without a subdomain. This part of our application will be used to host global administration pages.
If the tenant is not null, then we must select a user filtering on both email and tenant.
FYI, userRepository.findGeneralAdmin filters by email and tenant equal to null.
I've created a CustomUserDetails class to extend Spring's User. It contains the user ID and tenant ID as well. This will come in handy later.

Enabling the filter

We can activate the request filter from within WebSecurityConfig:



@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
            // More config here...
            .addFilterBefore(new TenantFilter(tenantRepository), UsernamePasswordAuthenticationFilter.class)

The before-part is essential here. UserDetailsService will read from TenantContext, so the filter must kick in before authentication is done.

A controller Example

Whenever someone creates a new post, the application needs to know two things:

Who is the user (author) of this new post? Easy: we use @AuthenticationPrincipal CustomUserDetails user.
Which tenant is this new post supposed to be a part of? Also easy: we call TenantContext.getCurrentTenantId().

Like so:



@PostMapping("add_post")
@PreAuthorize("isAuthenticated() && !hasRole('ADMINISTRATOR')")
public String addPost(@AuthenticationPrincipal CustomUserDetails user,
                      @Valid NewPostViewModel postVm) {
    var tenantId = TenantContext.getCurrentTenantId();
    postService.addPost(user.getUserId(), tenantId, postVm.getText());
    return "redirect:/posts";
}

(@PreAuthorize is part of Spring Method Security)

However, TenantContext.getCurrentTenantId is way too much typing, and I'm way too lazy so...
We create a custom annotation:



@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface TenantId {
}

... a resolver:



public class TenantResolver implements HandlerMethodArgumentResolver {
    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.getParameterAnnotation(TenantId.class) != null &&
                        parameter.getParameterType().getTypeName().equals("long");
    }

    @Override
    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
                                  NativeWebRequest webRequest, WebDataBinderFactory binderFactory) {
        return TenantContext.getCurrentTenantId();
    }
}

... and activate it:



@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers) {
        argumentResolvers.add(new TenantResolver());
    }
}

Now we can do this(!):



@PostMapping("add_post")
@PreAuthorize("isAuthenticated() && !hasRole('ADMINISTRATOR')")
public String addPost(@TenantId long tenantId,
                      @AuthenticationPrincipal CustomUserDetails user,
                      @Valid NewPostViewModel postVm) {
    postService.addPost(user.getUserId(), tenantId, postVm.getText());
    return "redirect:/posts";
}

I've added support for @Tenant String tenant parameters as well. Very convenient because @ControllerAdvice can be used to add the tenant to the MVC model for all controllers.



@ControllerAdvice
public class GlobalControllerAdvice {
    private static final Logger LOGGER = Logger.getLogger(GlobalControllerAdvice.class.getName());

    @ModelAttribute("tenant")
    public String populateTenantName(@Tenant String tenant) {
        return tenant;
    }
}

On any of my Thymeleaf pages, I can now show the tenant:



<span th:text="${tenant}"></span>

... or test on it:



<span th:if="${tenant != null}"></span>

Check the full source here.

Cross-tenant security breaches

The web application works fine at this stage, but unfortunately, it's not fully secure yet. Once a user authenticates, she'll be handed a cookie called "JSESSIONID" that could appear as if it's tenant-specific, but it isn't. When a request is made using this cookie, Spring Security will check the validity of this cookie without taking tenants into account. In fact, Spring Security doesn't know what a tenant is.

Let's imagine I've authenticated against tenant2, where I'm a tenant administrator. I've been given a cookie (yum!) that I will now use to make hand-crafted requests against tenant1:



DELETE http://tenant1.localhost:8080/api/posts/1
Cookie: JSESSIONID=DF07D6D7C7CB9652830ABB3E108F20C7

Without any additional checks, I'll be able to delete the posts of the other tenants. (CSRF has been left out of the equation in the example)

More filters

This TenantAuthorizationFilter compares the tenant of the request (taken from the URL) against the tenant of the user (taken from CustomUserDetails).



public class TenantAuthorizationFilter extends OncePerRequestFilter {
    private static final Logger LOGGER =
            Logger.getLogger(TenantAuthorizationFilter.class.getName());

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        var tenantId = TenantContext.getCurrentTenantId();
        var authentication = SecurityContextHolder.getContext().getAuthentication();
        var user = authentication == null ? null : (CustomUserDetails) authentication.getPrincipal();
        var userTenantId = user == null ? null : user.getTenantId();

        if (user == null || Objects.equals(tenantId, userTenantId)) {
            chain.doFilter(request, response);
        } else {
            LOGGER.warning("Attempted cross-tenant access.");
            response.setStatus(FORBIDDEN.value());
        }
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        return request.getRequestURI().startsWith("/webjars/")
                || request.getRequestURI().startsWith("/css/")
                || request.getRequestURI().startsWith("/js/")
                || request.getRequestURI().endsWith(".ico");
    }
}

When should this filter kick in?
Indeed, after authentication has happened (because CustomUserDetails must be created first):



@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
            // More config here...
            .addFilterBefore(new TenantFilter(tenantRepository), UsernamePasswordAuthenticationFilter.class)
            .addFilterAfter(new TenantAuthorizationFilter(), UsernamePasswordAuthenticationFilter.class)

Speaking of cookies, my favorites are dinosaur coo--
I mean, cookies are domain-specific inside of a browser. If you have a cookie for tenant1.localhost, the browser will not use it when making requests against tenant2.localhost. That's great because tenants' websites will feel separated and disconnected, as they should be.
That also means that the problem highlighted above only applies to hand-crafted HTTP requests (Postman, .http file, ...).

Schematically, the situation that we've got ourselves into now looks like this:

Styling and customization

A quick and easy way to give tenants their own customizable style would be to do something like this:



@RestController
@RequestMapping("/style")
public class StyleController {
    @GetMapping(value = "tenantStyle.css", produces = {"text/css"})
    public String getTenantStyle(@Tenant String tenant) {
        if (tenant == null) {
            return "body { background-color: #fcd2d2; }";
        } else if (tenant.equals("tenant1")) {
            return "body { background-color: #ebebfc; }";
        } else if (tenant.equals("tenant2")) {
            return "body { background-color: #edfceb; }";
        } else {
            return "";
        }
    }
}

Obviously, this is a very hard-coded approach. Configurable colors could be stored in the database and retrieved from a service here. A CssBuilder could be invented to do the heavy lifting, and caching could be added since the CSS won't change much.

Possible improvements and additions

The @Tenant parameter annotation could be made compatible with a custom TenantDetails interface (similar to Spring Security's UserDetails). This interface could have getTenant and getTenantId methods. The TenantDetails class could be extended with a tenant name, logo (file path), etc.
Error handling is quite basic right now. There's no form validation and error reporting. Redirecting after login success/failure has not been configured.
Thymeleaf code could be cleaned up by moving the general administration navbar and pages into separate fragments and/or include files.
For cleaner controller code, Method Security Meta-Annotations such as @AdminOnly and @TenantUserOnly can be created.
Spring Caching can be used to cache the lookup of the tenant ID (inside TenantFilter) and to cache calls to the StyleController because they trigger a lot! @Cacheable is incredible.

Summary

As you know, all source code is here.
All multitenant specifics are covered above, but I recommend pulling the repository for a more complete picture. Do make sure to read the README.md for instructions on setting up the database. All you need is docker and a JVM.

I hope this writeup has given you the information you were looking for! Any comments are appreciated! Definitely let me know if you have any suggestions or recommendations.

Managing ASP.NET Core MVC front-end dependencies with npm and webpack (part 1)

Lars Willemsens — Fri, 09 Apr 2021 12:23:37 +0000

.NET 8 provides a couple of great project templates to get you up and running quickly. However, the MPA (multiple-page application) is not getting much attention. Front-end packages are outdated, and you can’t add new JS libraries using modern practices (LibMan doesn't count 😉).
Starting out is easy though: either you choose the web template, which gives you an almost empty project, or you can opt for more boilerplate by choosing the mvc or webapp template.

Both have their (dis)advantages:

dotnet new web: this gives you… pretty much nothing. That’s not necessarily bad if you’re up for configuring everything from scratch.
dotnet new mvc (or webapp): gives you an MPA right off the bat, but the front-end libraries are outdated and bundled with the project, which doesn’t provide a lot of room for change. (webapp results in a page-based project while mvc produces a Model-View-Controller project)

Getting your front-end configured just the way you want can be challenging. There are no project templates that include a clean npm/webpack setup. If you want to use a SPA framework, you can choose between angular and react. But what if you use a different framework (such as Vue or Svelte!) or even no framework? Well, this guide can help you set that up!
(Note: In .NET 8, the react and angular templates were migrated from the .NET SDK to Visual Studio.)

What we’re about to do

We’re going to set up an ASP.NET Core MVC project with custom front-end dependencies. It’ll be a multi-page app that is tailored to our needs. More specifically…
We’ll be making sure Bootstrap is a dependency of the project instead of a part of the project. So, our project tree will no longer be cluttered with a bunch of minified JS and MAP files.
We’ll be kicking out JQuery like it’s 2014! It’ll only be referenced from ASP.NET’s form validation since it still depends on it.
Using this setup, we'll be able to use TypeScript! 🎉
The dependencies and build process will be set up using npm and webpack. Any code that we write will be processed by a build task. We’ll move all .js, .ts, and .css files into a separate src directory. Only the build artifacts will end up in wwwroot.

Why we’re doing it

First and foremost, the MVC template is much too firm and inflexible. Adding new front-end libraries to the project is a bit of an undertaking and that shouldn’t be the case.

Adding a NuGet package to the project (thankfully) doesn’t result in a bunch of DLLs in the project tree. Neither should be the case when adding a library for the front-end. We also want control over the exact version numbers that are used, just like with NuGet packages.

Along the way, we’ll get a better insight into how webpack can be used outside of a SPA!

Let’s get to it!

Creating the project

What you’ll need:

A .NET 8 SDK. Previous versions of .NET and .NET Core will work fine as well. I'm using 8.0.203 and have previously used .NET 5 and 6 as well as .NET Core for this setup.
NodeJS with bundled npm (or yarn), I’m using 21.4.0.
Optionally, an IDE. For now, all you need is a functional command line!

Let’s create a new MVC project. Navigate to a new empty directory and enter the following:

$ dotnet new mvc

If you’re using git then go ahead and create a .gitignore file. Thankfully, there's a separate .NET template to take care of this. Still from within your project directory, enter:

$ dotnet new gitignore

Launch the project with:

$ dotnet run

Check the output (or Properties/launchSettings.json) to see which port number has been generated for your project and navigate to localhost to have a look.

This startup project can be found on Gitlab as the first version of Net8NpmWebpack.

Front-end dependencies

Next up, create a new directory called ClientApp at the root of your MVC project. Inside this new directory, create a file called package.json. Give it the following content:

{
    "name": "net8npmwebpack",
    "description": "ASP.NET Core MVC project with npm and webpack front-end configuration.",
    "repository": "https://gitlab.com/kdg-ti/integratieproject-1/guides/net8npmwebpack",
    "license": "MIT",
    "version": "5.0.0",
    "dependencies": {
        "@popperjs/core": "^2.11.8",
        "jquery": "^3.7.1",
        "jquery-validation": "^1.20.0",
        "jquery-validation-unobtrusive": "^4.0.0",
        "bootstrap": "^5.3.3",
        "bootstrap-icons": "^1.11.3"
    },
    "devDependencies": {
        "webpack": "^5.91.0",
        "webpack-cli": "^5.1.4",
        "css-loader": "^6.10.0",
        "style-loader": "^3.3.4"
    },
    "scripts": {
        "build": "webpack"
    }
}

You’ll want to change the values of the first five fields if you apply these steps to an existing project.

Apart from the obvious fields, we’re specifying:

dependencies: includes Bootstrap 5, JQuery, and Popper (for popup placement, used by Bootstrap)
devDependencies: webpack and webpack-related loaders. We’ll need these to bundle our front-end code.
scripts: a single command that invokes the webpack bundling process

Go ahead and run the following command from inside the ClientApp directory:

$ npm install

A new node_modules directory will have popped up containing a massive amount of JS and CSS files. Consider this directory to be like the bin and obj directories (or, better yet, the NuGet package cache). Although it doesn’t contain any binaries, its content is still a load of dependencies we refer to from within our code.

… but we don’t have any code yet. Let’s add some by creating a src directory inside ClientApp and adding both a js and a css directory at that location. Create a new file called site.js in the js directory and move the contents of both wwwroot/css/site.css and Views/Shared/_Layout.cshtml.css to ClientApp/src/css. Like so:

ClientApp/
├── package-lock.json
├── package.json
└── src
    ├── css
    │   └── site.css  # contents of wwwroot/css/site.css and Views/Shared/_Layout.cshtml.css
    └── js
        └── site.js   # newly created

Cleanup is important so take your time remove directories wwwroot/css and wwwroot/js entirely and to remove Views/Shared/_Layout.cshtml.css as well.

In site.js we will write custom JavaScript code that’s relevant to the entire site. Additionally, we'll use this file to import all site-wide dependencies:

// JS Dependencies: Popper, Bootstrap & JQuery
import '@popperjs/core';
import 'bootstrap';
import 'jquery';
// Using the next two lines is like including partial view _ValidationScriptsPartial.cshtml
import 'jquery-validation';
import 'jquery-validation-unobtrusive';

// CSS Dependencies: Bootstrap & Bootstrap icons
import 'bootstrap-icons/font/bootstrap-icons.css';
import 'bootstrap/dist/css/bootstrap.css';

// Custom JS imports
// ... none at the moment

// Custom CSS imports
import '../css/site.css';

console.log('The \'site\' bundle has been loaded!');

Lines 2 to 9 will import code from within node_modules. We’re importing Bootstrap’s Javascript, Popper, and CSS as well as a couple of JQuery libaries that are used by ASP.NET Core’s validation scripts.
All of this is done using ECMAScript 6 modules, a modern approach to importing JS files from other JS files or even CSS files from JS files.

Now… how can we possibly get this code into a user’s browser? The file we just created contains only 17 lines of code, but it imports a small list of libraries and some custom CSS code. Do we just throw node_modules at our users? Of course not! This directory is so large that we need to carefully filter, bundle, and host only those parts that are needed at runtime.

… this is where webpack comes in!

Building the bundle

Create a new file called webpack.config.js and place it in the ClientApp directory. Give it the following content:

const path = require('path');

module.exports = {
    entry: {
        site: './src/js/site.js'
    },
    output: {
        filename: '[name].entry.js',
        path: path.resolve(__dirname, '..', 'wwwroot', 'dist'),
        clean: true
    },
    devtool: 'source-map',
    mode: 'development',
    module: {
        rules: [
            {
                test: /\.css$/,
                use: ['style-loader', 'css-loader']
            },
            {
                test: /\.(png|svg|jpg|jpeg|gif|webp)$/i, 
                type: 'asset'
            },
            {
                test: /\.(eot|woff(2)?|ttf|otf|svg)$/i,
                type: 'asset'
            }
        ]
    }
};

Without going into too much detail, we’re specifying that a bundle should be created based on src/js/site.js and that this bundle should be called site.entry.js (the [name] placeholder is replaced with “site”).

webpack is smart enough to figure out what should be included in the bundle and bases its decision-making on what we do in site.js. For example, if we import JQuery, then JQuery will be included in the bundle. Even CSS files such as those from Bootstrap will be included in the bundle if we choose to import them from within site.js. (In the rules section at the bottom, we specify how those non-JS files are handled.)

Ok, let’s build this using the following command from within the ClientApp directory:

$ npm run build

Basically, this executes the webpack command as can be seen in the scripts section of package.json above.

This build results in two new files:

wwwroot/dist/
├── site.entry.js
└── site.entry.js.map

Now we can include those from within our HTML. Open Views/Shared/_Layout.cshtml and replace all script and link tags (even those at the bottom!) with a single line:

 <!DOCTYPE HTML>
 <html lang="en">
 <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>@ViewData["Title"] - Net8NpmWebpack</title>
+    <script src="~/dist/site.entry.js" defer></script>
-    <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
-    <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />
-    <link rel="stylesheet" href="~/Net8NpmWebpack.styles.css" asp-append-version="true" />
 </head>
 <body>
     <header>
         <nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow mb-3">
             <div class="container-fluid">
                 <a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">Net8NpmWebpack</a>
                 <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target=".navbar-collapse" aria-controls="navbarSupportedContent"
                         aria-expanded="false" aria-label="Toggle navigation">
                     <span class="navbar-toggler-icon"></span>
                 </button>
                 <div class="navbar-collapse collapse d-sm-inline-flex justify-content-between">
                     <ul class="navbar-nav flex-grow-1">
                         <li class="nav-item">
                             <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Index">Home</a>
                         </li>
                         <li class="nav-item">
                             <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
                         </li>
                     </ul>
                 </div>
             </div>
         </nav>
     </header>
     <div class="container">
         <main role="main" class="pb-3">
             @RenderBody()
         </main>
     </div>

     <footer class="border-top footer text-muted">
         <div class="container">
             &copy; 2024 - Net8NpmWebpack - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
         </div>
     </footer>
-    <script src="~/lib/jquery/dist/jquery.min.js"></script>
-    <script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
-    <script src="~/js/site.js" asp-append-version="true"></script>
     @await RenderSectionAsync("Scripts", required: false)
 </body>
 </html>

defer indicates that execution of this file should be delayed until the page is fully loaded. That’s a modern alternative to putting all script tags at the bottom of a document to make sure that the document is fully downloaded before the scripts start scanning the DOM.

While we're at it, let's quickly throw in a Bootstrap Icon. In _Layout.cshtml, scroll down to the footer and change the following:

- &copy; 2024 - Net8NpmWebpack - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
+ <i class="bi bi-c-circle"></i> 2024 - Net8NpmWebpack - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>

Time to delete the last bit of clutter from our project tree:

$ rm -rf wwwroot/lib

If you’re as obsessed with useless comments as I am then now’s the time to remove the comment in site.css. Whatever minification reference is being made there, we’re not going down that path anyway.

And if you’re using git, add wwwroot/dist/ to your .gitignore.

Alright, time to check it out!

$ dotnet run

Open localhost (check that port again) in a browser and check the browser console (F12). You should see the message “The ‘site’ bundle has been loaded!”.

How cool is that? All of the front-end’s dependencies are now downloaded, built, and bundled dynamically. The build system is extensible and all dependencies are easily managed and replaceable if needed!

The project so far can be found on Gitlab as version 2 of Net8NpmWebpack.

TypeScript

Now that we've done the heavy lifting, the world is our oyster! Let's add TypeScript.

In package.json, add a couple of devDependencies:

     "devDependencies": {
+        "@tsconfig/recommended": "^1.0.5",
+        "@types/bootstrap": "^5.2.10",
+        "ts-loader": "^9.5.1",
+        "typescript": "^5.4.3",
         "webpack": "^5.91.0",

In ClientApp, add a tsconfig.json file with this content:

{
    "extends": "@tsconfig/recommended/tsconfig.json",
    "compilerOptions": {
        "module": "es6",
        "target": "es6",
        "allowJs": true,
        "moduleResolution": "node"
    }
}

Rename your js directory and .js files. You should end up with something like this:

ClientApp/
└── src
    └── ts
        └── site.ts

Now, only webpack needs to be configured to handle TypeScript. In webpack.config.js apply these changes:

     entry: {
-        site: './src/js/site.js'
+        site: './src/ts/site.ts'
     },
     output: {
         filename: '[name].entry.js',
         path: path.resolve(__dirname, '..', 'wwwroot', 'dist'),
         clean: true
     },
     devtool: 'source-map',
     mode: 'development',
+    resolve: {
+        extensions: [".ts", ".js"],
+        extensionAlias: {'.js': ['.js', '.ts']}
+    },
     module: {
         rules: [
+            {
+                test: /\.ts$/i,
+                use: ['ts-loader'],
+                exclude: /node_modules/
+            },
             {

Sass

We can add Sass to make our styling life easier. 🕶️

In package.json, we need two more devDependencies:

         "@types/bootstrap": "^5.2.10",
+        "sass": "^1.72.0",
+        "sass-loader": "^14.1.1",
         "ts-loader": "^9.5.1",

Let's go for this directory structure and file name:

ClientApp/
└── src
    └── scss
        └── site.scss

As a kind of smoke test, we can introduce a Sass variable in site.scss:

+ $button-bg-color: #1b6ec2;

 // More styling here

 .btn-primary {
   color: #fff;
-  background-color: #1b6ec2;
+  background-color: $button-bg-color;
   border-color: #1861ac;
 }

 .nav-pills .nav-link.active, .nav-pills .show > .nav-link {
   color: #fff;
-  background-color: #1b6ec2;
+  background-color: $button-bg-color;
   border-color: #1861ac;
 }

 // Even more styling follows

In site.ts, we must import the correct (renamed) style sheet:

  // Custom CSS imports
- import '../css/site.css';
+ import '../scss/site.scss';

And finally, in webpack.config.js we can enable Sass file processing:

             {
-                test: /\.css$/,
-                use: ['style-loader', 'css-loader']
+                test: /\.s?css$/,
+                use: ['style-loader', 'css-loader', 'sass-loader']
             },

Give the application another spin. From ClientApp, don't forget to install the new NPM dependencies and build a new bundle:

$ cd ClientApp
$ npm i
$ npm run build
$ cd ..
$ dotnet run

This concludes the first part of this guide. Here, you can find the third version of this project.

What’s next?

We’re not quite finished. There are two important things on our TODO list:

Performance! Try switching quickly between different pages in the SPA. You’ll see a delay before Bootstrap’s CSS gets applied. This is caused by a large amount of CSS getting plugged into the page at runtime. This is the most urgent thing to fix, user experience is just too important!
Building the project as a whole. At this point building the .NET project doesn’t trigger a rebuild for the front-end. How annoying! :)

In part 2 we’ll be tackling the performance issue and streamlining the build process.

Managing ASP.NET Core MVC front-end dependencies with npm and webpack (part 2)

Lars Willemsens — Fri, 09 Apr 2021 12:23:00 +0000

This post is the second part of a two-part article on managing Javascript and CSS dependencies within a multiple-page application written in ASP.NET Core MVC.
In the first part, we’ve specified our front-end dependencies, bumped the version numbers and set up a webpack build system.
In this part, we’ll tackle performance issues and make sure that the entire project (front-end and back-end) can be built using a single command.

Performance

While everything seems to be working okay, a few improvements must be made. When fast-clicking between pages (i.e., 'Home' and 'Privacy') you might notice that styles get applied after the browser renders the page. That’s because the npm package style-loader plugs the CSS into the page after it is loaded, causing the browser to re-render the page!
On top of that, the Javascript bundle — which contains the CSS — is very large. It contains the entire Bootstrap CSS, some Bootstrap Javascript functions, and all of JQuery!

Let’s take care of this. Our aim is the following:

Bundling CSS into a separate CSS file that can be statically referenced from an HTML link tag
Splitting up the JavaScript/TypeScript code into separate bundles. Many pages have code that is unique to them, and not every page needs JQuery

As mentioned in Part 1, we’re only keeping JQuery around because ASP.NET Core’s client-side form validation depends on it.

To make sure that the solution that I’m about to present here fits all use cases, let’s set up a simple prototype. These are the pages we’re going to use:

All the pages include the site’s SCSS and some code that is common to all pages. The individual pages are:

The Index page, which has a bit of custom TypeScript code running on it (index.ts).
The Privacy page has no custom code. We'll give it a Bootstrap component requiring specific Bootstrap code. This is similar to any other page since the navbar has a JS pull-down feature on small devices (the hamburger button). Like all pages, it needs Bootstrap’s styling to be rendered correctly.
The Contact page has a form backed by ASP.NET Core’s form validation. Validation can be done both server-side and client-side. We'll load client-side validation code from validation.ts.

With all of this in the pipeline you might be wondering why we went down this road in the first place. We will end up with individual CSS/JS files that are hard-referenced from the HTML pages… that’s what we started with! Well, sort of, but not quite. Here’s what’s different:

We’re referencing our libraries with a specific version number
The dependencies are not placed inside the project tree
We’ll end up with a performance gain (in the standard MVC template, all of JQuery is referenced from all pages)
Our build system is extensible: Need an obscure npm dependency? No problem! Want to use the very latest ECMAScript features? You got it! Need minification or obfuscation? No problemo!

Imagine what it would be like if this was already present in the standard MVC template. Then, you’d have all this modern front-end goodness without setting it up yourself. Ha!

OK, let’s go.

Splitting up the bundle

This is the current state of things:



$ ll wwwroot/dist/
total 3904
-rw-r--r-- 1 lars lars  176032 Apr  5 11:17 39795c0b4513de014cf8.woff
-rw-r--r-- 1 lars lars  130396 Apr  5 11:17 b7bcc075b395c14ce8c2.woff2
-rw-r--r-- 1 lars lars 1665226 Mar 31 12:21 site.entry.js
-rw-r--r-- 1 lars lars 2021658 Mar 31 12:21 site.entry.js.map

That’s over 1600K worth of Javascript and CSS code.

These are the separate blocks that we identified in the diagram above:

Sitewide styles (Bootstrap and custom SCSS)
Sitewide JavaScript and TypeScript (this includes Bootstrap’s JS code for fancy popup buttons, the navbar's hamburger, and so on)
Validation scripts (basically JQuery with some extras): for forms that use ASP.NET Core’s client-side form validation
A sample Javascript code block that is unique to a specific page (let’s take ‘Home’, so index.ts)

This is what our view files look like after we move all of the common parts into _Layout.cshtml:

To split things up, we’ll dive into ClientApp/src/ts/ and turn site.ts into three files:

site.ts: common code needed on each page (includes Bootstrap). This will result in separate JS and CSS files.
validation.ts: JQuery, including the validation scripts for our forms
index.ts: some dummy code that’s only applicable to ‘Home’

Here’s what they look like:

site.ts

This file lost a few lines when compared to the previous version. Styling is needed on every page of the application, so we’re including all of our (S)CSS here:



import '@popperjs/core';
import 'bootstrap';
import 'bootstrap-icons/font/bootstrap-icons.css';
import 'bootstrap/dist/css/bootstrap.css';

// Custom CSS imports
import '../scss/site.scss';

console.log('The \'site\' bundle has been loaded!');

validation.ts

These import lines were previously in site.ts. We’re putting them into their own file so that they can be included separately:



import 'jquery';
import 'jquery-validation';
import 'jquery-validation-unobtrusive';

console.log('The \'validation\' bundle has been loaded!');

index.ts

… some dummy code:



console.log('The \'index\' bundle has been loaded!');

Configuring the webpack build

Separate files means separate entries in webpack. Each entry is handled as a separate module, resulting in a separate Javascript file. The resulting file for each entry will be named after the entry followed by the .entry.js suffix.

While we’re at it, we’ll extract the CSS from the Javascript bundle. Instead of using the style-loader npm package, we’ll use mini-css-extract-plugin, which takes care of the extraction.

Brace yourself, webpack.config.js is coming…



 const path = require('path');
+const MiniCssExtractPlugin = require("mini-css-extract-plugin");

 module.exports = {
     entry: {
-        site: './src/js/site.js'
+        index: './src/ts/index.ts',
+        site: './src/ts/site.ts',
+        validation: './src/ts/validation.ts'
     },
     output: {
         filename: '[name].entry.js',
         path: path.resolve(__dirname, '..', 'wwwroot', 'dist'),
         clean: true
     },
     devtool: 'source-map',
     mode: 'development',
     resolve: {
         extensions: [".ts", ".js"],
         extensionAlias: {'.js': ['.js', '.ts']}
     },
     module: {
         rules: [
             {
                 test: /\.ts$/i,
                 use: ['ts-loader'],
                 exclude: /node_modules/
             },
             {
                 test: /\.s?css$/,
-                use: ['style-loader', 'css-loader', 'sass-loader']
+                use: [{ loader: MiniCssExtractPlugin.loader }, 'css-loader', 'sass-loader']
             },
             {
                 test: /\.(png|svg|jpg|jpeg|gif|webp)$/i, 
                 type: 'asset'
             },
             {
                 test: /\.(eot|woff(2)?|ttf|otf|svg)$/i,
                 type: 'asset'
             }
         ]
-    }
+    },
+    plugins: [
+        new MiniCssExtractPlugin({
+            filename: "[name].css"
+        })
+    ]
 };

At the very top and the very bottom you can see we’re importing an npm package and adding it as a plugin respectively. Most plugins have a wide range of configuration options, but we only need to specify which filename to use for CSS files ([name].css).

In the entry section the different entries are defined and near the center of the file we’ve replaced style-loader with the plugin.

So one npm package is being replaced by another. Update package.json accordingly:



     "devDependencies": {
         "@tsconfig/recommended": "^1.0.5",
         "@types/bootstrap": "^5.2.10",
         "sass": "^1.72.0",
         "sass-loader": "^14.1.1",
         "ts-loader": "^9.5.1",
         "typescript": "^5.4.3",
         "webpack": "^5.91.0",
         "webpack-cli": "^5.1.4",
         "css-loader": "^6.10.0",
-        "style-loader": "^3.3.4"
+        "mini-css-extract-plugin": "^2.8.1"
     },

Let’s generate those new bundles. From the ClientApp directory, enter:



$ npm install
$ npm run build

Which build artifacts were generated this time?



$ ll ../wwwroot/dist/
total 2540
-rw-r--r-- 1 lars lars 176032 Apr  5 11:52 39795c0b4513de014cf8.woff
-rw-r--r-- 1 lars lars 130396 Apr  5 11:52 b7bcc075b395c14ce8c2.woff2
-rw-r--r-- 1 lars lars    295 Apr  5 11:52 index.entry.js
-rw-r--r-- 1 lars lars    246 Apr  5 11:52 index.entry.js.map
-rw-r--r-- 1 lars lars 387938 Apr  5 11:52 site.css
-rw-r--r-- 1 lars lars 506712 Apr  5 11:52 site.css.map
-rw-r--r-- 1 lars lars 290672 Apr  5 11:52 site.entry.js
-rw-r--r-- 1 lars lars 259544 Apr  5 11:52 site.entry.js.map
-rw-r--r-- 1 lars lars 363314 Apr  5 11:52 validation.entry.js
-rw-r--r-- 1 lars lars 467211 Apr  5 11:52 validation.entry.js.map

The Views

After splitting the bundle into multiple smaller bundles, we now have to review our link and script tags.

With mini-css-extract-plugin in the picture, the CSS must be imported statically. CSS is used everywhere, so we jump into _Layout.cshtml:



     ...

     <title>@ViewData["Title"] - Net8NpmWebpack</title>
     <script src="~/dist/site.entry.js" defer></script>
+    <link rel="stylesheet" href="~/dist/site.css">
 </head>
 <body>
     <header>

     ...

The Home/Index.cshtml page has custom code:



 @{
     ViewData["Title"] = "Home Page";
 }

+@section Scripts
+{
+    <script src="~/dist/index.entry.js" defer></script>
+}
+
 <div class="text-center">

 ...

The Privacy.cshtml page gets a fancy Bootstrap component. Let’s pick
a dropdown menu button!



 @{
     ViewData["Title"] = "Privacy Policy";
 }
 <h1>@ViewData["Title"]</h1>

 <p>Use this page to detail your site's privacy policy.</p>
+
+<div class="dropdown">
+    <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
+        Dropdown button
+    </button>
+    <ul class="dropdown-menu">
+        <li><a class="dropdown-item" href="#">Action</a></li>
+        <li><a class="dropdown-item" href="#">Another action</a></li>
+        <li><a class="dropdown-item" href="#">Something else here</a></li>
+    </ul>
+</div>

… and then there’s the Contact page, a new page we’ll build from scratch to test form validation. We’ll need a view, a view-model, some new actions in the controller, and a link on the site’s navigation bar.

Let’s start with the form itself, a new view created as Home/Contact.cshtml:



@model ContactViewModel

@{
    ViewBag.Title = "Contact";
    Layout = "_Layout";
}

@section Scripts
{
    <script src="~/dist/validation.entry.js" defer></script>
}

<h1>@ViewBag.Title</h1>

<form asp-controller="Home" asp-action="Contact">
    <div class="mb-3">
        <label asp-for="Subject" class="form-label"></label>
        <input asp-for="Subject" class="form-control"/>
        <span asp-validation-for="Subject" class="small text-danger"></span>
    </div>

    <div class="mb-3">
        <label asp-for="Message" class="form-label"></label>
        <textarea asp-for="Message" class="form-control"></textarea>
        <span asp-validation-for="Message" class="small text-danger"></span>
    </div>

    <button class="btn btn-primary" type="submit">Submit</button>
</form>

Subject, Message, ContactViewModel, … what are you on about!?
Let’s move out of the Views directory and into Models…
ContactViewModel.cs:



using System.ComponentModel.DataAnnotations;

namespace Net8NpmWebpack.Models;

public class ContactViewModel
{
    [Required]
    [StringLength(30, MinimumLength = 3)]
    public string Subject { get; set; }

    [Required(ErrorMessage = "Please enter a message.")]
    public string Message { get; set; }
}

… but the form is GET-ing and POST-ing all over the place, how is that handled?
Time to edit HomeController:



         ...

+        [HttpGet]
+        public IActionResult Contact()
+        {
+            return View();
+        }
+
+        [HttpPost]
+        public IActionResult Contact(ContactViewModel contactVM)
+        {
+            if (ModelState.IsValid)
+            {
+                // Send an email or save the message in a table...
+                // Redirect to a page that says "Thanks for contacting us!"...
+
+                return RedirectToAction("Index");
+             }
+
+            return View();
+        }

        ...

… ok and the link?
Back to _Layout.cshtml:



 ...

                         <li class="nav-item">
                             <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
                         </li>
+                        <li class="nav-item">
+                            <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Contact">Contact</a>
+                        </li>
                     </ul>
                 </div>

 ...

Done! (almost)
We now have a full-blown webpack and NPM-powered front-end with excellent performance and modern Javascript goodness.

We don’t need _ValidationscriptsPartial.cshtml anymore, so be sure to remove that one from your repository:



$ rm Views/Shared/_ValidationScriptsPartial.cshtml

If you’re consistently adding defer to your script tags (and you should be! 🙂), you can go one step further and move the Scripts section inside _Layout to that page’s head section.



 <!DOCTYPE HTML>
 <html lang="en">
 <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>@ViewData["Title"] - Net8NpmWebpack</title>
     <script src="~/dist/site.entry.js" defer></script>
+    @await RenderSectionAsync("Scripts", required: false)
     <link rel="stylesheet" href="~/dist/site.css">
 </head>
 <body>

     ...

     <footer class="border-top footer text-muted">
         <div class="container">
             <i class="bi bi-c-circle"></i> 2024 - Net8NpmWebpack - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
         </div>
     </footer>
-    @await RenderSectionAsync("Scripts", required: false)
 </body>
 </html>

The project so far can be found on GitLab as version 4 of NetCoreNpmWebpack.

Give it a spin. You’ll notice that the performance is good.

Building the project

Running the project is perhaps easier said than done. Let’s recap:


 bash
$ npm install          # only after a modification to package.json
$ npm run build
$ dotnet build
$ dotnet run

That’s too much typing for anyone. Let’s automate that a bit.

The .csproj file can be extended with some extra build commands. Honestly, csproj-Hocus Pocus is a bit of uncharted territory for me (although it reminds me of the Ant build system), but this seems to work fine:



 <Project Sdk="Microsoft.NET.Sdk.Web">

     <PropertyGroup>
         <TargetFramework>net8.0</TargetFramework>
         <Nullable>disable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
+        <IsPackable>false</IsPackable>
+        <MpaRoot>ClientApp\</MpaRoot>
+        <WWWRoot>wwwroot\</WWWRoot>
+        <DefaultItemExcludes>$(DefaultItemExcludes);$(MpaRoot)node_modules\**</DefaultItemExcludes>
     </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="Microsoft.AspNetCore.SpaServices.Extensions" Version="6.0.3"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <!-- Don't publish the MPA source files, but do show them in the project files list -->
+        <Content Remove="$(MpaRoot)**"/>
+        <None Remove="$(MpaRoot)**"/>
+        <None Include="$(MpaRoot)**" Exclude="$(MpaRoot)node_modules\**"/>
+    </ItemGroup>
+
+    <Target Name="NpmInstall" BeforeTargets="Build" Condition=" !Exists('$(MpaRoot)node_modules') ">
+        <!-- Ensure Node.js is installed -->
+        <Exec Command="node --version" ContinueOnError="true">
+            <Output TaskParameter="ExitCode" PropertyName="ErrorCode"/>
+        </Exec>
+        <Error Condition="'$(ErrorCode)' != '0'" Text="Node.js is required to build and run this project. To continue, please install Node.js from https://nodejs.org/, and then restart your command prompt or IDE."/>
+        <Message Importance="high" Text="Restoring dependencies using 'npm'. This may take several minutes..."/>
+        <Exec WorkingDirectory="$(MpaRoot)" Command="npm install"/>
+    </Target>
+
+    <Target Name="NpmRunBuild" BeforeTargets="Build" DependsOnTargets="NpmInstall">
+        <Exec WorkingDirectory="$(MpaRoot)" Command="npm run build"/>
+    </Target>
+
+    <Target Name="PublishRunWebpack" AfterTargets="ComputeFilesToPublish">
+        <!-- As part of publishing, ensure the JS resources are freshly built in production mode -->
+        <Exec WorkingDirectory="$(MpaRoot)" Command="npm install"/>
+        <Exec WorkingDirectory="$(MpaRoot)" Command="npm run build"/>
+
+        <!-- Include the newly-built files in the publish output -->
+        <ItemGroup>
+            <DistFiles Include="$(WWWRoot)dist\**"/>
+            <ResolvedFileToPublish Include="@(DistFiles->'%(FullPath)')" Exclude="@(ResolvedFileToPublish)">
+                <RelativePath>%(DistFiles.Identity)</RelativePath>
+                <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
+                <ExcludeFromSingleFile>true</ExcludeFromSingleFile>
+            </ResolvedFileToPublish>
+        </ItemGroup>
+    </Target>
+
+    <Target Name="NpmClean" BeforeTargets="Clean">
+        <RemoveDir Directories="$(WWWRoot)dist"/>
+        <RemoveDir Directories="$(MpaRoot)node_modules"/>
+    </Target>

 </Project>

As you may have figured out from the diff above, the npm install command is only executed in case the node_modules directory is absent. That’s something to keep in mind in case you make modifications to package.json!

Now, we can build the project in its entirety using the dotnet build command. Excellent! (pressing the run or compile button from your IDE works just as well)

Auto-building the bundle

To make life even easier, we want to automagically rebuild the bundle whenever the front-end code changes. At the same time, we don’t want to restart ASP.NET Core’s HTTP server (Kestrel) when that happens.

To make this happen, we’ll add a webpack watcher for the front-end files to trigger a rebuild. In package.json:



 ...
     },
     "scripts": {
-        "build": "webpack"
+        "build": "webpack",
+        "watch": "webpack --watch"
     }
 }

While editing front-end code, our workflow will look like this:

npm run watch (executed from within the ClientApp directory)
dotnet run

(Note: I would advise against using dotnet watch since it seems to continuously detect changes to the bundle, causing an endless rebuild loop)

Version 5 of the sample project can be found here.

Wrapping up

We now have a flexible and extensible project that uses modern front-end technologies and has excellent performance.

We’ve had to cover quite a bit of ground since many of these techniques are absent in most tutorials. Bower, Grunt, and Gulp were dominant just a few years ago but are now on their decline. Many sources on the internet still refer to these kings of yesteryear. However, on Bower’s website, you can see that they are actively recommending alternatives.

This guide may have filled a gap by bringing npm and webpack into MVC and MPA applications, specifically .NET Core and .NET 8 apps.

What’s left?

There is no distinction yet between “Development” and “Production”. Minification of JavaScript code and CSS pruning are still to be added. I’m confident, though, that the flexibility of the build system won’t make that too challenging.

If you have any other suggestions, then please let me know in the comments below.

Good luck building your MVC application!