Smidge

A lightweight runtime CSS/JavaScript file minification, combination, compression & management library for ASP.Net (.NET Standard)

❤️ If you use and like Smidge please consider becoming a GitHub Sponsor ❤️

News

Features

Minification, combination, compression for JS/CSS files
Properly configured client side caching, persistent server side caching (no rebundling unnecessarily)
Fluent syntax for creating and configuring bundles
Debug/Production configurations for each bundle
Cache busting - and you can customize/replace how it works
JS source maps (via the Smidge.Nuglify package)
File watchers to auto invalidate/refresh a processed bundle
Extensible - you can completely customize the pre-processor pipeline and create your own processors and for any file type

Quick Start

Install from Nuget:
```
Install-Package Smidge
```

Add Smidge config to appsettings.json:

"smidge": {
    "dataFolder" : "Smidge",
    "version" : "1"
  }

Add smidge to your services:

services.AddSmidge(Configuration.GetSection("smidge"));

Create a bundle in your configure method:

app.UseSmidge(bundles =>
{
   bundles.CreateJs("my-application", "~/js/site.js", "~/js/app");
});

Add the tag helpers to your _ViewImports.cshtml file:
```
@addTagHelper *, Smidge
```

Render your bundle:

<script src="https://github.com/Shazwazza/Smidge/raw/develop/my-application"></script>

See Installation for full configuration details

Usage

Pre-defined bundles

Define your bundles during startup:

services.UseSmidge(bundles =>
{
   //Defining using file/folder paths:

   bundles.CreateJs("test-bundle-2", "~/Js/Bundle2", "~/Js/OtherFolder/*.js");

   //Or defining using JavaScriptFile's or CssFile's
   //this allows you to custom the pipeline per file

   bundles.Create("test-bundle-1", //bundle name
      new JavaScriptFile("~/Js/Bundle1/a1.js"),
      new JavaScriptFile("~/Js/Bundle1/a2.js"));

   //Then there's all sorts of options for configuring bundles with regards to customizing their pipelines,
   //customizing how rendering is done based on Debug or Production environments, if you want to 
   //enable file watchers, configure custom cache busters or the cache control options, etc...
   //There's even a fluent API to do this! Example: 

   bundles.CreateJs("test-bundle-3", "~/Js/Bundle3")
      .WithEnvironmentOptions(BundleEnvironmentOptions.Create()
         .ForDebug(builder => builder
            .EnableCompositeProcessing()
            .EnableFileWatcher()
            .SetCacheBusterType<AppDomainLifetimeCacheBuster>()
            .CacheControlOptions(enableEtag: false, cacheControlMaxAge: 0))
         .Build()
   );
});

If you don't want to create named bundles and just want to declare dependencies individually inside your Views, you can do that too! You can create bundles (named or unnamed) during runtime ... no problem.

See Declarations for full declaration/usage details

Rendering

The easiest way to render bundles is simply by the bundle name:

<script src="https://github.com/Shazwazza/Smidge/raw/develop/my-awesome-js-bundle"></script>
<link rel="stylesheet" href="https://github.com/Shazwazza/Smidge/blob/develop/my-cool-css-bundle"/>

This uses Smidge's custom tag helpers to check if the source is a bundle reference and will output the correct bundle URL. You can combine this with environment variables for debug/non-debug modes. Alternatively, you can also use Razor to do the rendering.

See Rendering for full rendering & debug mode details

Custom pre-processing pipeline

It's easy to customize how your files are processed including the way files are minified, how URLs are resolved, etc.... This can be done at a global/default level, at the bundle level or at an individual file level.

See Custom Pre-Processing Pipeline for information about customizing the pre-process pipeline

URLs

There's a couple of methods you can use to retrieve the URLs that Smidge will generate when rendering the <link> or <script> html tags. This might be handy in case you need to load in these assets manually (i.e. lazy load scripts, etc...):

Task<IEnumerable<string>> SmidgeHelper.GenerateJsUrlsAsync()
Task<IEnumerable<string>> SmidgeHelper.GenerateCssUrlsAsync()

See Asset URLs for information about retrieving the debug and non-debug asset urls for your bundles

Documentation

All of the documentation lives here

I haven't had time to document all of the features and extensibility points just yet but I'm working on it :)

Copyright & Licence

This is free software and is licensed under the MIT License

Logo image Designed by Freepik

Shazwazza / Smidge

readme