Getting Started

Introduction

Vite integrations work by providing both a development and a production mode. Vite.NET gives you tools to benefit from the way you'd like your application to work.

In development Vite.NET will run your Vite application in a specific port and use that to render your SPA inside your razor rendered page.

Setting up the front end

1) The first thing you need to do is create an ASP.NET Core project with either MVC or Razor Pages. You can add this to an existing API as well, but you also need to add the support for running razor views.

ASP.NET Core Template

2) Once you have your project you will need to create a Vite application inside your web project with the command npm create vite@latest

3) Make your selections for UI library as you may need, the only required step here is calling the folder of your Vite application "ClientApp" since that is what is used by default in ViteDotNet. Then proceed as their CLI prompts and run cd ClientApp and npm install.

For the remainder of the tutorial we will assume you chose React + Typescript, you might need to make minor adjustments if you chose a different template, but it should be very straightforward.

4) Run npm install vite-dotnet.

5) Go to your vite.config.ts file and make sure it looks like this:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import ViteDotNet from 'vite-dotnet'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(), 
    ViteDotNet("src/main.tsx") //This parameter is the entrypoint of your application
  ],
})

Vite.NET will override your config settings so that you will no longer need the index.html file, you can choose to delete it at this point if you so feel inclined. This is the reason why you need to specify the route of your application's entrypoint. Vite.NET currently does not support multiple entrypoints.

Setting up the backend

1) In your fresh ASP.NET Core project, install Vite.NET

Install-Package TechGems.ViteDotNet -Version 0.1.0-beta

2) Go to your _ViewImports.cshtml file and add the following line:

@addTagHelper *, ViteDotNet

3) Go to your program.cs file, it should look something like this:

using ViteDotNet;
using ViteDotNet.Middleware;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddViteIntegration(builder.Configuration); //Allow Vite.NET to read your configuration.

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.RunViteDevServer("./ClientApp"); //Middleware for running your Vite app alongside your ASP.NET Core app.

app.Run();

4) Now we will set up the config of the project.

Either in your appsettings.Development.json or your secrets file, add the following config:

"ViteDotNet": { 
  "Entrypoint": "src/main.tsx", //Required
  "IsReact": true, 		//Required
  "RootDirectory": "ClientApp", //Optional, if no value is provided "ClientApp" is assumed by convention. 
  "Port": 5178, 		//Optional, if no value is provided 5173 will be the port that your Vite SPA will run in during development.
  "ContainerElementId": "root" 	//Optional, if no value is provided "app" will be used as the default div id for containing your SPA.
}

5) Go to index.cshtml, it should look something like this:

@page
@model IndexModel
@{
    Layout = null; //This isn't necessary, but the default Vite application has CSS that conflicts with the default layout of an ASP.NET Core
}

<dev-vite-scripts />

Development setup benefits

With all this setup you can now run your application. This setup for development grants you HMR support for better DX and runs your Vite SPA every time you run your ASP.NET Core app.

You can now use a common layout between your SPA and your existing Razor pages, and you can benefit from server-side authentication to limit or control access to your SPA, something which you cannot do with a normal static web application.

We will now continue on setting up for a Vite production build.

Production build setup

Vite.NET has <dev-vite-scripts /> and <prod-vite-scripts /> as tag helpers to make Vite integrations easier.

To use the latter, you need to have a valid production build of your Vite application. When you set up the config with the Vite Plugin, it also changes the way in which the production build is generated to function according to ASP.NET Core conventions.

By default, running the build script will generate the production files in wwwroot/{appFolder} and you will have a manifest.json file which will let your application know how to retrieve all your scripts and assets for you.

To allow this, you will need to run npm run build.

Then you can use the <prod-vite-scripts /> tag helper.

@page
@model IndexModel
@{
    Layout = null; //This isn't necessary, but the default Vite application has CSS that conflicts with the default layout of an ASP.NET Core
}

<prod-vite-scripts /> @*Swap between the two tag helpers based on your needs*@

Conclusion

There's a lot more that you can do with Vite.NET, such as running multiple SPAs hosted in the same server application as well as more flexibility for configuration, but that will be covered in the Advanced section.