DOCSEARCHbyAlgolia
Submit Docs

Excubo.WebCompiler

repository·main·Indexed 41 days ago

https://github.com/excubo-ag/webcompiler

A cross-platform .NET global tool for compiling Scss files, minifying CSS and JS assets, and applying Gzip compression. It provides a pure .NET implementation to remove Node.js dependencies from build pipelines and Docker environments, featuring MSBuild integration and JSON-based configuration.

Tokens
2.5K
Snippets
8
Records
8
Agent score
1%

What's inside Excubo.WebCompiler

  1. Configure webcompiler using a JSON file

    main

    To customize the compilation, minification, or autoprefixing process, use a configuration file.

    1. Generate a default config: Run webcompiler --defaults. This creates webcompilerconfiguration.json.
    2. Modify the file: Edit the generated JSON to your needs.
    3. Run with config: Use the -c flag to point to your file.

    Example usage:

    webcompiler -r wwwroot -c webcompilerconfiguration.json
    {
  "Minifiers": {
    "GZip": true,
    "Enabled": true,
    "Css": {
      "CommentMode": "Important",
      "ColorNames": "Hex",
      "TermSemicolons": true,
      "OutputMode": "SingleLine",
      "IndentSize": 2
    },
    "Javascript": {
      "RenameLocals": true,
      "PreserveImportantComments": true,
      "EvalTreatment": "Ignore",
      "TermSemicolons": true,
      "OutputMode": "SingleLine",
      "IndentSize": 2
    }
  },
  "Autoprefix": {
    "Enabled": true,
    "ProcessingOptions": {
      "Browsers": [
        "last 4 versions"
      ],
      "Cascade": true,
      "Add": true,
      "Remove": true,
      "Supports": true,
      "Flexbox": "All",
      "Grid": "None",
      "IgnoreUnknownVersions": false,
      "Stats": "",
      "SourceMap": true,
      "InlineSourceMap": false,
      "SourceMapIncludeContents": false,
      "OmitSourceMapUrl": false
    }
  },
  "CompilerSettings": {
    "Sass": {
      "OutputStyle": "Expanded",
      "RelativeUrls": true,
      "SourceMap": false
    }
  },
  "Output": {
    "Preserve": true
  }
}

  2. Install Excubo.WebCompiler as a local tool

    main

    For CI environments or project-specific isolation, install it as a local tool using a tool manifest.

    1. Create a new tool manifest.
    2. Install the tool.
    3. Restore the tool.
    4. Run it using dotnet tool webcompiler.
    dotnet new tool-manifest
dotnet tool install Excubo.WebCompiler
dotnet tool restore
dotnet tool webcompiler -h

  3. Integrate webcompiler with MSBuild

    main

    You can automate asset compilation by adding a Target to your .csproj file. This works cross-platform.

    To run webcompiler on the wwwroot folder after every build:

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

  5. Enable compile-on-save with dotnet watch

    main

    To automatically recompile assets when source files change, use dotnet watch.

    For .NET 8.0 or newer

    dotnet watch no longer supports running tools directly. Instead, integrate the MSBuild target (e.g., CompileStaticAssets) into your .csproj and run:

    dotnet watch build -t:CompileStaticAssets --no-restore

    For .NET 7.0 or older

    Run the tool directly via dotnet watch:

    dotnet watch tool run webcompiler -r wwwroot

    Project Configuration

    Ensure your .csproj includes the files you want to watch:

    <ItemGroup>
    <Watch Include="**\*.scss" />
</ItemGroup>

  6. Install Excubo.WebCompiler as a dotnet global tool

    main

    To use Excubo.WebCompiler globally on your machine, install it as a dotnet global tool via NuGet.

    Warning: Do not add Excubo.WebCompiler as a NuGet package reference to your project; it must be installed as a tool.

    dotnet tool install Excubo.WebCompiler --global

  7. Integrate webcompiler with MSBuild (Conditional/Robust)

    main

    For a more robust integration that handles Razor Class Libraries (where compression should be disabled) and checks if the tool is installed before running, use the following configuration in your .csproj.

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

    <!-- Test if WebCompiler is installed -->
    <Exec Command="webcompiler -h" ContinueOnError="true" StandardOutputImportance="low" StandardErrorImportance="low" LogStandardErrorAsError="false" IgnoreExitCode="true">
        <Output TaskParameter="ExitCode" PropertyName="ErrorCode" />
    </Exec>

    <!-- Execute the WebCompiler task if the test was successful -->
    <Exec Command="webcompiler -r wwwroot --zip ${WebCompilerCompression}" StandardOutputImportance="high" StandardErrorImportance="high" Condition="'$(ErrorCode)' == '0'" />
</Target>

  8. Reference: webcompiler CLI options

    main

    The following command-line options are available for webcompiler. Note that if a configuration file is provided via -c, most of these options are ignored in favor of the JSON settings.

    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.