Vite.AspNetCore 1.12.0

dotnet add package Vite.AspNetCore --version 1.12.0
NuGet\Install-Package Vite.AspNetCore -Version 1.12.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Vite.AspNetCore" Version="1.12.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Vite.AspNetCore --version 1.12.0
#r "nuget: Vite.AspNetCore, 1.12.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Vite.AspNetCore as a Cake Addin
#addin nuget:?package=Vite.AspNetCore&version=1.12.0

// Install Vite.AspNetCore as a Cake Tool
#tool nuget:?package=Vite.AspNetCore&version=1.12.0

Vite.AspNetCore

This library offers integration with ViteJS to be used in ASP.NET applications. It's made to work mainly with MPA (Multi-Page Application).

The library is compatible with:

  • MVC
  • Razor Pages
  • Blazor Server

Features

This library has three simple but very useful features:

  • A Middleware to forward the requests to the Vite Development Server
    • The middleware can start the Vite Development Server for you ❤️.
  • A service to access the Vite manifest.
  • Tag Helpers for script and link tags.

Setup

Install the package from NuGet.

dotnet add package Vite.AspNetCore

Add the following lines to your Program.cs or Startup class.

using Vite.AspNetCore.Extensions;

// ---- Service Configuration ----
// Add Vite services.
builder.Services.AddViteServices();

// ---- App Configuration ----
// Use Middleware in development environment.
if (app.Environment.IsDevelopment())
{
    // Enable the Middleware to use the Vite Development Server.
    app.UseViteDevMiddleware();
}

Usage

The Vite Middleware

The common way to access Vite Development Server assets in your application is by using the following template, specifying the local URL where Vite Server is running.


<environment include="Development">
    <script type="module" src="http://localhost:5173/@@vite/client"></script>
    <script type="module" src="http://localhost:5173/main.js"></script>
</environment>

<environment exclude="Development">
    <img src="http://localhost:5173/assets/logo.svg" alt="Vite Logo" />
</environment>
<environment include="Production">
    <img src="~/assets/logo.svg" alt="Vite Logo" />
</environment>

Having to set up two ways to access public assets in different environments doesn't look very good. It can also be a problem in some circumstances. Service workers, for example, cannot be properly tested this way and if you are using preprocessors like SASS, you have probably noticed that your 'url()'s are not resolved correctly during development. But don't worry, this middleware will solve all those problems for you.

By using the vite middleware during development, you don't need to pass the development server URL. You can use aspnet paths as usual.


<environment include="Development">
    
    <script type="module" src="http://localhost:5173/@@vite/client"></script>
    <script type="module" src="~/main.js"></script>
</environment>


<img src="~/assets/logo.svg" alt="Vite Logo" />

The middleware will proxy all requests to the Vite Development Server. You won't need alternative paths for images or other resources from your public assets. 🙀🙀🙀

Note: The order of the middlewares is important! Put the UseViteDevMiddleware() call in a position according to your needs. Otherwise, your assets will not be served as expected.

The Vite Manifest

The Vite Manifest is a JSON file that contains the mapping between the original file names and the hashed names. This is useful to access the files in production environments.

By using the Vite Manifest service, you can access the manifest in your application by injecting the IViteManifest service. See the following example.

@inject IViteManifest Manifest

<environment include="Development">
    
    <script type="module" src="http://localhost:5173/@@vite/client"></script>
    <script type="module" src="~/main.ts"></script>
</environment>
<environment include="Production">
    <script type="module" src="~/@Manifest["main.ts"]!.File" asp-append-version="true"></script>
</environment>

You can also inject the manifest service in your controllers or services. See the following example.

public class HomeController : Controller
{
    private readonly IViteManifest _manifest;

    public HomeController(IViteManifest manifest)
    {
        _manifest = manifest;
    }

    public IActionResult Index()
    {
        var mainFile = _manifest["main.ts"]?.File;
        return View();
    }
}

Tag Helpers

Do you want to render your entrypoint scripts and styles in the simplest way possible? You can use the special tag helpers provided by this library. First, add the following line to your _ViewImports.cshtml file.

@addTagHelper *, Vite.AspNetCore

Now you can use the vite-src and vite-href attributes in your scripts and links. See the following example.


<link rel="stylesheet" vite-href="~/main.ts" />


<script type="module" vite-src="~/main.ts" asp-append-version="true"></script>
<script type="module" vite-src="~/secondary.ts"></script>

This tag helpers will do the following magic:

  • Middleware is enabled:
    • If the link tag is a script (you want to include css from a script entrypoint), the link tag will just disappear. This is because Vite loads the styles automatically by including the script.
    • If the script of the Vite client is not included, it will be added automatically.
  • Middleware is disabled:
    • The link and script tags will be rendered using the original paths taken from the manifest. The value of the vite-href and vite-src attributes will be used as the entrypoint to access the manifest.

The rendered HTML when the middleware is enabled will look like this.




<script type="module" src="http://localhost:5173/@vite/client"></script>
<script type="module" src="/main.ts"></script>
<script type="module" src="/secondary.ts"></script>

And the rendered HTML when the middleware is disabled will look like this.


<link rel="stylesheet" href="/css/main.css" />


<script type="module" src="/js/main.js?v=bosLkDB4bJV3qdsFksYZdubiZvMYj_vuJXBs3vz-nc0"></script>
<script type="module" src="/js/secondary.js"></script>

Note: The final paths and filenames depend on how you set it in your vite.config.ts file.

Configuration

The middleware and the manifest service can be configured by passing options to the AddViteServices() function, using environment variables, user secrets, or your appsettings.json file.

Passing the options to the AddViteServices() function is as simple as you can see in the following example:

// Program.cs
using Vite.AspNetCore.Extensions;
using Vite.AspNetCore;

// ...
// Add the Vite services.
builder.Services.AddViteServices(options =>
{
    // By default, the manifest file name is ".vite/manifest.json". If your manifest file has a different name, you can change it here.
    options.Manifest = "my-manifest.json",
    // More options...
});
/// ...

If you prefer not to hardcode the options, you can use environment variables or user secrets. I suggest using appsettings.json and/or appsettings.Development.json files to share the default configuration with other developers. This information is not sensitive, so it's safe to share it.

// appsettings.json
{
    "Vite": {
        "Manifest": "my-manifest.json"
    }
}
// appsettings.Development.json
{
    "Vite": {
        "Server": {
            // Enable the automatic start of the Vite Development Server. The default value is false.
            "AutoRun": true,
            // The port where the Vite Development Server will be running. The default value is 5173.
            "Port": 5174,
            // If true, the middleware will use HTTPS to connect to the Vite Development Server. The default value is false.
            "Https": false,
        }
    }
}

In the previous example, i used the appsettings.json and appsettings.Development.json files to keep the configurations for each environment separated. But you can use only one file if you prefer.

Available Options

There are more options that you can change. All the available options are listed below. ⚙️

Property Description
Manifest The manifest file name. Default is .vite/manifest.json (Vite 5) or manifest.json (Vite 4).
Base The subfolder where your assets will be located, including the manifest file, relative to the web root path.
PackageManager The name of the package manager to use. Default value is npm.
PackageDirectory The directory where the package.json file is located. Default value is the .NET project working directory.
Server:AutoRun Enable or disable the automatic start of the Vite Dev Server. Default value is false.
Server:Port The port where the Vite Development Server will be running. Default value is 5173.
Server:Host The host where the Vite Dev Server will be running. Default value is localhost.
Server:TimeOut The timeout in seconds spent waiting for the vite dev server. Default is 5
Server:Https If true, the middleware will use HTTPS to connect to the Vite Development Server. Default value is false.
Server:ScriptName The script name to run the Vite Development Server. Default value is dev.
Server:UseFullDevUrl If true, tag helpers will use the full dev server URL instead of just paths. Default value is false.

If you are using the appsettings.json and/or appsettings.Development.json files, all the options must be under the Vite property.

Examples

Do you want to see how to use this library in a real project? Take a look at these examples

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Vite.AspNetCore:

Package Downloads
AbanoubNassem.Trinity

Trinity is a powerful Single-Page Application (SPA) administration tool that is designed to streamline common administrative tasks and enhance the productivity of developers. With its feature-rich and beautifully-designed interface, built using C# and ASP.NET, Trinity makes it easy to manage your website's backend with ease.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Vite.AspNetCore:

Repository Stars
spark-dotnet/framework
Build production ready, full-stack web applications fast without sweating the small stuff.
Version Downloads Last updated
1.12.0 4,293 1/15/2024
1.11.0 9,929 11/25/2023
1.10.2 5,914 10/29/2023
1.10.1 5,122 10/9/2023
1.10.0 6,280 9/16/2023
1.9.3 7,293 8/13/2023
1.9.0 391 7/29/2023
1.8.1 134 7/29/2023
1.8.0 1,201 7/9/2023
1.7.1 3,619 6/25/2023
1.7.0 1,421 6/11/2023
1.6.2 975 5/25/2023
1.6.1 121 5/22/2023
1.6.0 117 5/20/2023
1.5.3 833 5/2/2023
1.5.2 150 4/28/2023
1.5.1 239 4/22/2023
1.5.0 366 4/16/2023
1.4.1 167 4/12/2023
1.4.0 3,744 3/19/2023
1.3.0 220 2/18/2023
1.2.0 252 1/29/2023
1.1.0 259 1/24/2023
1.0.0 279 1/16/2023

Tag helpers:
- Link tag handling has been improved
- The full Vite development server URL is now always rendered
A new service "IViteDevServerStatus" was added to obtain vite development server status information.
The "UseViteDevMiddleware" method has been replaced by "UseViteDevelopmentServer".