WebCompiler

Excubo.WebCompiler

Excubo.WebCompiler is a dotnet global tool that compiles Scss files, minimizes css / js assets, and gzips files.

This project is based on madskristensen/WebCompiler. However, the dependency to node and the node modules have been removed, to facilitate a pure dotnet core implementation. As a benefit, this implementation is cross-platform (x64 linux/win are tested, please help by testing other platforms!).

:warning: A common mistake is to add the package Excubo.WebCompiler as a nuget package reference to a project (e.g. by installing it via the nuget package manager in Visual Studio). This does not work! Instead, one needs to install it as a dotnet tool. See the "Getting started" section further down on this page.

Features

• Compilation of Scss files
• Dedicated compiler options for each individual file
• Detailed error messages
• dotnet core build pipeline support cross-platform
• Minify the compiled output
• Minification options for each language is customizable
• Autoprefix for CSS

Changelog

Changes in version 4.0.1

Drop of support for net6.0. Add support for net9.0.

Changes in version 4.X.Y

The default value for zipping minified assets has changed from true to false. This has no effect to pre-existing configuration files. The change was made in anticipation of a new feature in the net9.0 SDK.

Changes in version 3.8.14

Support for net7.0 was dropped. The nupkg file was getting outrageously large due to dependencies and duplication across the target frameworks.

Changes in version 3.3.Y

Breaking Change / Warning: This change removes the key of IgnoreFolders and IgnoreFiles per 3.2.Y and in favour of an "Ignore" key with support for File Globbing support.

If no Ignore value is defined in the CompilerSettings.json then **/_. (files prefixed with _) will be ignored. If you wish to continue this behaviour and also ignore other patterns, ensure to also include this pattern.

Simply add the following to CompilerSettings.json:

  "CompilerSettings": {
     "Ignore": [ "**/_*.*", "wwwroot/*.scss", "wwwroot/css/specific-file.scss", "wwwroot/_lib/**/*.scss", "bin/**/*", "obj/**/*" ],
  }

Changes in version 3.2.Y

Supports excluding certain files and folders (nb. Sub folders must be specified specifically if wanting to be ignored) when using recursive mode Simply add the following to CompilerSettings.json:

  "CompilerSettings": {
     "IgnoreFolders": ["./wwwroot/", "./bin/", "./obj/", "./wwwroot/sass/"],
     "IgnoreFiles": ["./sass/_variables.scss"]
  }

Changes in version 3.1.Y

Support for netcoreapp3.1 and net5.0 were dropped. The nupkg file was getting outrageously large due to dependencies and duplication across the target frameworks.

Changes in version 3.X.Y

The underlying SASS compiler is changed from libsass to dart-sass. This is a necessary change, as libsass is discontinued. There are two breaking changes when working with the config json file:

• CompilerSettings.Sass.OutputStyle: The valid values are now Expanded or Compressed. The former default value of Nested is now invalid.
• The property CompilerSettings.Sass.Precision does not exist anymore.

  "CompilerSettings": {
    "Sass": {
      "IndentType": "Space",
      "IndentWidth": 2,
      "OutputStyle": "Expanded", // was: "Nested"
      //"Precision": 5, // Remove this
      "RelativeUrls": true,
      "LineFeed": "Lf",
      "SourceMap": false
    }
  }

Changes in version 2.4.X

Added support for .NET 5. You will most likely only notice that when using webcompiler in a docker context, but that's covered now as well!

Changes in version 2.3.X

There are now two more options:

• -o/--output-dir helps to put files into a different folder. See webcompiler -o --help for more details.
• -p/--preserve disable makes all temporary files disappear (note that this can increase compile time. The default is to keep all temporary files).

Changes in version 2.1.X

• Previously, running e.g. webcompiler -r without specifying a file and/or folder just returned without any message, warning or error. This is now an error. If the intention is to run in the working directory, use webcompiler -r ..
• Now writes to stderr instead of stdout where appropriate.
• Bug fixed: Sass files were not recompiled on change, if that change was to the sass file itself rather than one of its dependencies. Now it correctly recompiles for any change to the file itself or any of its dependencies.

Breaking changes in version 2.0.X

The command line interface has been rewritten from scratch to enable sensible defaults without the need to have a configuration file around. Starting with version 2.0.0, the old compilerconfig.json.defaults is incompatible. A new file can be created with webcompiler --defaults (optional).

Usage:
  webcompiler file1 file2 ... [options]
  webcompiler [options]

Options:
  -c|--config <conf.json>          Specify a configuration file for compilation.
  -d|--defaults [conf.json]        Write a default configuration file (file name is webcompilerconfiguration.json, if none is specified).
  -f|--files <files.conf>          Specify a list of files that should be compiled.
  -h|--help                        Show command line help.
  -m|--minify [disable/enable]     Enable/disable minification (default: enabled), ignored if configuration file is provided.
  -o|--output-dir <path/to/dir>    Specify the output directory, ignored if configuration file is provided.
  -p|--preserve [disable/enable]   Enable/disable whether to preserve intermediate files (default: enabled).
  -r|--recursive                   Recursively search folders for compilable files (only if any of the provided arguments is a folder).
  -z|--zip [disable/enable]        Enable/disable gzip (default: enabled), ignored if configuration file is provided.
  -a|--autoprefix [disable/enable] Enable/disable autoprefixing (default: enabled), ignored if configuration file is provided.

Recommended default usage: webcompiler -r wwwroot.

Language support

Due to the removal of node as a dependency (as opposed to madskristensen/WebCompiler), support for languages other than Scss is not yet available. Please get in touch if you want to contribute to any of the following languages, or if you want to add yet another language.

• LESS
• Stylus
• JSX
• ES6
• (Iced)CoffeeScript

Getting started

Global

1. Install the tool as dotnet global tool

Excubo.Webcompiler is distributed as a nuget package. You can install it in a command line using

dotnet tool install Excubo.WebCompiler --global

2. Call webcompiler

webcompiler -r wwwroot

Local

It's also possible to use Excubo.Webcompiler as a local tool (ideal for CI environments)

1. Create a new tool manifest

dotnet new tool-manifest

2. Add Excubo.Webcompiler

dotnet tool install Excubo.WebCompiler

3. Restore

dotnet tool restore

4. Usage

dotnet tool webcompiler -h

Build integrations

Command line / terminal

Global

You can simply call webcompiler with the appropriate options, e.g.

webcompiler -r wwwroot

Local

dotnet run tool webcompiler -r wwwroot

or you can simply call:

dotnet webcompiler -r wwwroot

MSBuild

You can add webcompiler as a Target in your csproj file. This works cross platform:

  <Target Name="CompileStaticAssets" AfterTargets="AfterBuild">
    <Exec Command="webcompiler -r wwwroot" StandardOutputImportance="high" />
  </Target>

In this example, webcompiler is executed on the folder wwwroot inside your project folder.

Docker

The integration into docker images is as straight-forward as installing the tool and invoking it. However, there's a caveat that some users ran into, which is the use of alpine-based images, such as mcr.microsoft.com/dotnet/sdk:5.0-alpine. Excubo.WebCompiler will not work on this image, as some fundamental libraries are missing on alpine. The alpine distribution is usually intended to create small resulting images. If this is the goal, the best approach is to perform build/compilation operations in a non-alpine distribution, and then finally copy only the resulting files to an alpine based image intended only for execution. Learn more about it here, in Microsoft's usage for dotnet and here, in the docker documentation about multi-stage-build.

MSBuild with execution of webcompiler only if it is installed

Global

This configuration will not break the build if Excubo.WebCompiler is not installed. This can be helpful, e.g. if compilation is only necessary on the build server. It will also check to see if you're executing inside a Microsoft.NET.Sdk.Razor project, and shut off compression accordingly.

<Target Name="CompileStaticAssets" AfterTargets="CoreCompile" >
    <PropertyGroup>
        <!-- Compression should be disabled by default if we're in a Razor Class Library -->
        <WebCompilerCompression Condition="'$(RazorL