{"id":33239046,"url":"https://github.com/excubo-ag/WebCompiler","last_synced_at":"2025-11-21T13:01:43.532Z","repository":{"id":38353733,"uuid":"248775516","full_name":"excubo-ag/WebCompiler","owner":"excubo-ag","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-02T15:43:44.000Z","size":12633,"stargazers_count":164,"open_issues_count":1,"forks_count":29,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-11-02T16:09:15.470Z","etag":null,"topics":["cross-platform","dotnet","js","minification","sass","scss","webcompiler"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/excubo-ag.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-03-20T14:28:20.000Z","updated_at":"2025-11-02T15:43:47.000Z","dependencies_parsed_at":"2023-02-18T11:31:26.698Z","dependency_job_id":"c9fc7c78-8938-49f4-a143-8eccf0cce786","html_url":"https://github.com/excubo-ag/WebCompiler","commit_stats":{"total_commits":638,"total_committers":33,"mean_commits":"19.333333333333332","dds":0.5031347962382445,"last_synced_commit":"43a02af6789dc4d13b31ee88540c373fa66a0f8d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/excubo-ag/WebCompiler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excubo-ag%2FWebCompiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excubo-ag%2FWebCompiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excubo-ag%2FWebCompiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excubo-ag%2FWebCompiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/excubo-ag","download_url":"https://codeload.github.com/excubo-ag/WebCompiler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excubo-ag%2FWebCompiler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285620632,"owners_count":27203062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-21T02:00:06.175Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-platform","dotnet","js","minification","sass","scss","webcompiler"],"created_at":"2025-11-16T19:00:38.869Z","updated_at":"2025-11-21T13:01:43.526Z","avatar_url":"https://github.com/excubo-ag.png","language":"C#","funding_links":[],"categories":["Tooling"],"sub_categories":["Others"],"readme":"## Excubo.WebCompiler\n\n[![Nuget](https://img.shields.io/nuget/v/Excubo.WebCompiler)](https://www.nuget.org/packages/Excubo.WebCompiler/)\n[![Nuget](https://img.shields.io/nuget/dt/Excubo.WebCompiler)](https://www.nuget.org/packages/Excubo.WebCompiler/)\n[![GitHub](https://img.shields.io/github/license/excubo-ag/WebCompiler)](https://github.com/excubo-ag/WebCompiler/)\n\n`Excubo.WebCompiler` is a dotnet global tool that compiles Scss files, minimizes css / js assets, and gzips files.\n\nThis project is based on [madskristensen/WebCompiler](https://github.com/madskristensen/WebCompiler). However, the dependency to node and the node modules have been removed, to facilitate a pure dotnet core implementation.\nAs a benefit, this implementation is cross-platform (x64 linux/win are tested, please help by testing other platforms!).\n\n: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.\n\n### Features\n\n- Compilation of Scss files\n- Dedicated compiler options for each individual file\n- Detailed error messages\n- `dotnet` core build pipeline support cross-platform\n- Minify the compiled output\n- Minification options for each language is customizable\n- Autoprefix for CSS\n\n### Changelog\n\n#### Changes in version 4.0.1\n\nDrop of support for net6.0. Add support for net9.0.\n\n#### Changes in version 4.X.Y\n\nThe default value for zipping minified assets has changed from `true` to `false`. This has no effect to pre-existing configuration files.\nThe change was made in anticipation of a new feature in the net9.0 SDK.\n\n#### Changes in version 3.8.14\n\nSupport for net7.0 was dropped. The nupkg file was getting outrageously large due to dependencies and duplication across the target frameworks.\n\n#### Changes in version 3.3.Y\n\n*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](https://docs.microsoft.com/en-us/dotnet/core/extensions/file-globbing).\n\nIf no Ignore value is defined in the CompilerSettings.json then **/_*.* (files prefixed with _) will be ignored.\nIf you wish to continue this behaviour and also ignore other patterns, ensure to also include this pattern.\n\nSimply add the following to CompilerSettings.json:\n\n```json\n  \"CompilerSettings\": {\n     \"Ignore\": [ \"**/_*.*\", \"wwwroot/*.scss\", \"wwwroot/css/specific-file.scss\", \"wwwroot/_lib/**/*.scss\", \"bin/**/*\", \"obj/**/*\" ],\n  }\n```\n\n#### Changes in version 3.2.Y\n\nSupports excluding certain files and folders (nb. Sub folders must be specified specifically if wanting to be ignored) when using recursive mode\nSimply add the following to CompilerSettings.json:\n\n```json\n  \"CompilerSettings\": {\n     \"IgnoreFolders\": [\"./wwwroot/\", \"./bin/\", \"./obj/\", \"./wwwroot/sass/\"],\n     \"IgnoreFiles\": [\"./sass/_variables.scss\"]\n  }\n```\n\n#### Changes in version 3.1.Y\n\nSupport for netcoreapp3.1 and net5.0 were dropped. The nupkg file was getting outrageously large due to dependencies and duplication across the target frameworks.\n\n#### Changes in version 3.X.Y\n\nThe 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:\n\n- `CompilerSettings.Sass.OutputStyle`: The valid values are now `Expanded` or `Compressed`. The former default value of `Nested` is now invalid.\n- The property `CompilerSettings.Sass.Precision` does not exist anymore.\n\n```json\n  \"CompilerSettings\": {\n    \"Sass\": {\n      \"IndentType\": \"Space\",\n      \"IndentWidth\": 2,\n      \"OutputStyle\": \"Expanded\", // was: \"Nested\"\n      //\"Precision\": 5, // Remove this\n      \"RelativeUrls\": true,\n      \"LineFeed\": \"Lf\",\n      \"SourceMap\": false\n    }\n  }\n```\n\n#### Changes in version 2.4.X\n\nAdded 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!\n\n#### Changes in version 2.3.X\n\nThere are now two more options:\n\n- `-o`/`--output-dir` helps to put files into a different folder. See `webcompiler -o --help` for more details.\n- `-p`/`--preserve` `disable` makes all temporary files disappear (note that this can increase compile time. The default is to keep all temporary files).\n\n#### Changes in version 2.1.X\n\n- 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 .`.\n- Now writes to `stderr` instead of `stdout` where appropriate.\n- 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.\n\n#### Breaking changes in version 2.0.X\n\nThe command line interface has been rewritten from scratch to enable sensible defaults without the need to have a configuration file around.\nStarting with version 2.0.0, the old compilerconfig.json.defaults is incompatible. A new file can be created with `webcompiler --defaults` (optional).\n\n```\nUsage:\n  webcompiler file1 file2 ... [options]\n  webcompiler [options]\n\nOptions:\n  -c|--config \u003cconf.json\u003e          Specify a configuration file for compilation.\n  -d|--defaults [conf.json]        Write a default configuration file (file name is webcompilerconfiguration.json, if none is specified).\n  -f|--files \u003cfiles.conf\u003e          Specify a list of files that should be compiled.\n  -h|--help                        Show command line help.\n  -m|--minify [disable/enable]     Enable/disable minification (default: enabled), ignored if configuration file is provided.\n  -o|--output-dir \u003cpath/to/dir\u003e    Specify the output directory, ignored if configuration file is provided.\n  -p|--preserve [disable/enable]   Enable/disable whether to preserve intermediate files (default: enabled).\n  -r|--recursive                   Recursively search folders for compilable files (only if any of the provided arguments is a folder).\n  -z|--zip [disable/enable]        Enable/disable gzip (default: enabled), ignored if configuration file is provided.\n  -a|--autoprefix [disable/enable] Enable/disable autoprefixing (default: enabled), ignored if configuration file is provided.\n```\n\nRecommended default usage: `webcompiler -r wwwroot`.\n\n### Language support\n\nDue to the removal of node as a dependency (as opposed to [madskristensen/WebCompiler](https://github.com/madskristensen/WebCompiler)), support for languages other than Scss is not yet available.\nPlease get in touch if you want to [contribute](#Contributing) to any of the following languages, or if you want to add yet another language.\n\n- LESS\n- Stylus\n- JSX\n- ES6\n- (Iced)CoffeeScript\n\n\n### Getting started\n\n#### Global\n\n##### 1. Install the tool as dotnet global tool\n\n`Excubo.Webcompiler` is distributed as a [nuget package](https://www.nuget.org/packages/Excubo.WebCompiler/). You can install it in a command line using\n\n```\ndotnet tool install Excubo.WebCompiler --global\n```\n\n##### 2. Call `webcompiler`\n\n```\nwebcompiler -r wwwroot\n```\n\n#### Local\n\nIt's also possible to use `Excubo.Webcompiler` as a local tool (ideal for CI environments)\n\n##### 1. Create a new tool manifest\n\n```\ndotnet new tool-manifest\n```\n\n##### 2. Add Excubo.Webcompiler\n\n```\ndotnet tool install Excubo.WebCompiler\n```\n\n##### 3. Restore\n\n```\ndotnet tool restore\n```\n\n##### 4. Usage\n\n```\ndotnet tool webcompiler -h\n```\n\n### Build integrations\n\n#### Command line / terminal\n\n##### Global\nYou can simply call `webcompiler` with the appropriate options, e.g.\n```powershell \nwebcompiler -r wwwroot\n```\n##### Local\n```powershell\ndotnet run tool webcompiler -r wwwroot\n```\nor you can simply call:\n```powershell\ndotnet webcompiler -r wwwroot\n```\n\n#### MSBuild\n\nYou can add `webcompiler` as a `Target` in your `csproj` file. This works cross platform:\n\n```xml\n  \u003cTarget Name=\"CompileStaticAssets\" AfterTargets=\"AfterBuild\"\u003e\n    \u003cExec Command=\"webcompiler -r wwwroot\" StandardOutputImportance=\"high\" /\u003e\n  \u003c/Target\u003e\n```\n\nIn this example, `webcompiler` is executed on the folder `wwwroot` inside your project folder.\n\n#### Docker\n\nThe 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](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/docker/building-net-docker-images?view=aspnetcore-5.0) and [here, in the docker documentation about multi-stage-build](https://docs.docker.com/develop/develop-images/multistage-build/).\n\n#### MSBuild with execution of webcompiler only if it is installed\n\n##### Global\nThis 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.\nIt will also check to see if you're executing inside a `Microsoft.NET.Sdk.Razor` project, and shut off compression accordingly.\n\n```xml\n\u003cTarget Name=\"CompileStaticAssets\" AfterTargets=\"CoreCompile\" \u003e\n    \u003cPropertyGroup\u003e\n        \u003c!-- Compression should be disabled by default if we're in a Razor Class Library --\u003e\n        \u003cWebCompilerCompression Condition=\"'$(RazorLangVersion)' != ''\"\u003edisabled\u003c/WebCompilerCompression\u003e\n        \u003cWebCompilerCompression Condition=\"'$(RazorLangVersion)' == ''\"\u003eenabled\u003c/WebCompilerCompression\u003e\n    \u003c/PropertyGroup\u003e\n\n    \u003c!-- Test if WebCompiler is installed --\u003e\n    \u003cExec Command=\"webcompiler -h\" ContinueOnError=\"true\" StandardOutputImportance=\"low\" StandardErrorImportance=\"low\" LogStandardErrorAsError=\"false\" IgnoreExitCode=\"true\"\u003e\n        \u003cOutput TaskParameter=\"ExitCode\" PropertyName=\"ErrorCode\" /\u003e\n    \u003c/Exec\u003e\n\n    \u003c!-- Execute the WebCompiler task if the test was successful --\u003e\n    \u003cExec Command=\"webcompiler -r wwwroot --zip ${WebCompilerCompression}\" StandardOutputImportance=\"high\" StandardErrorImportance=\"high\" Condition=\"'$(ErrorCode)' == '0'\" /\u003e\n\u003c/Target\u003e\n```\n\nThe `PropertyGroup` tests for Razor. The first `Exec` command simply tests whether `Excubo.WebCompiler` is installed at all. The second `Exec` command then executes `webcompiler` \nrecursively on the `wwwroot` folder if it is installed, and using compression if we're NOT in a Razor Class Library or Blazor project.\n\n##### Local\n\nUsing `dotnet tool` locally is quite simple. Unfortunately, there's no easy way to check if tools already exists (as the help always returns error code 0) without a script.\n\n```xml\n  \u003cTarget Name=\"ToolRestore\" BeforeTargets=\"PreBuildEvent\"\u003e\n      \u003cExec Command=\"dotnet tool restore\" StandardOutputImportance=\"high\" /\u003e\n  \u003c/Target\u003e\n\n  \u003cTarget Name=\"PreBuild\" AfterTargets=\"ToolRestore\"\u003e\n      \u003cExec Command=\"dotnet tool run webcompiler -r wwwroot\" StandardOutputImportance=\"high\" /\u003e\n  \u003c/Target\u003e\n```\n\nIf you only rely on webcompiler, it may be preferable to use the below `PreBuildEvent`\n\n```xml\n \u003cTarget Name=\"ToolRestore\" BeforeTargets=\"PreBuildEvent\"\u003e\n        \u003cExec Command=\"dotnet tool update excubo.webcompiler\" StandardOutputImportance=\"high\" /\u003e\n    \u003c/Target\u003e\n```\n\nWhich will either:\n\n- Do nothing if latest is installed\n- Install the latest if either out of date or uninstalled\n\n#### Compile on save (dotnet watch)\n\nFor automatic compilation whenever the content of source files change, add the following to your `csproj`:\n\n```xml\n\u003cItemGroup\u003e\n    \u003c!--specify file extensions here as needed--\u003e\n    \u003cWatch Include=\"**\\*.scss\" /\u003e\n\u003c/ItemGroup\u003e\n```\n\n##### Using net8.0 or newer\n\n`dotnet watch` no longer supports running tools, see https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-watch#arguments. As a workaround (see https://github.com/excubo-ag/WebCompiler/issues/95), integrate the MSBuild target `CompileStaticAssets` above, then run `dotnet watch build -t:CompileStaticAssets --no-restore`.\n\n##### Using net7.0 or older\n\nRun `dotnet watch tool run webcompiler` with the appropriate options in a terminal, e.g.\n`dotnet watch tool run webcompiler -r wwwroot`.\n\n### Configuration\n\nIf you want to change aspects of the compilation and minification process, create a configuration file, modify it to your needs, and run webcompiler using this config file:\n\n1. create config file (default file name: webcompilerconfiguration.json)\n\n```\nwebcompiler --defaults\n```\n\nThe default configuration is\n```json\n{\n  \"Minifiers\": {\n    \"GZip\": true,\n    \"Enabled\": true,\n    \"Css\": {\n      \"CommentMode\": \"Important\",\n      \"ColorNames\": \"Hex\",\n      \"TermSemicolons\": true,\n      \"OutputMode\": \"SingleLine\",\n      \"IndentSize\": 2\n    },\n    \"Javascript\": {\n      \"RenameLocals\": true,\n      \"PreserveImportantComments\": true,\n      \"EvalTreatment\": \"Ignore\",\n      \"TermSemicolons\": true,\n      \"OutputMode\": \"SingleLine\",\n      \"IndentSize\": 2\n    }\n  },\n  \"Autoprefix\": {\n    \"Enabled\": true,\n    \"ProcessingOptions\": {\n      \"Browsers\": [\n        \"last 4 versions\"\n      ],\n      \"Cascade\": true,\n      \"Add\": true,\n      \"Remove\": true,\n      \"Supports\": true,\n      \"Flexbox\": \"All\",\n      \"Grid\": \"None\",\n      \"IgnoreUnknownVersions\": false,\n      \"Stats\": \"\",\n      \"SourceMap\": true,\n      \"InlineSourceMap\": false,\n      \"SourceMapIncludeContents\": false,\n      \"OmitSourceMapUrl\": false\n    }\n  },\n  \"CompilerSettings\": {\n    \"Sass\": {\n      \"IndentType\": \"Space\",\n      \"IndentWidth\": 2,\n      \"OutputStyle\": \"Expanded\",\n      \"RelativeUrls\": true,\n      \"LineFeed\": \"Lf\",\n      \"SourceMap\": false\n    }\n  },\n  \"Output\": {\n    \"Preserve\": true\n  }\n}\n```\n\n2. change config file\n\nChange anything in the generated config file according to your needs. If you need help with the available settings, please refer to the documentation of [DartSassHost](https://github.com/Taritsyn/DartSassHost), [NUglify](https://github.com/xoofx/NUglify) and [AutoprefixerHost](https://github.com/Taritsyn/AutoprefixerHost).\n\nSome WebCompiler-specific configurations are:\n\n- `\"Output\": { \"Preserve\": true }`  \n  When disabled, removes all temporary files (which could increase compile time; the default is to keep all temporary files). Equivalent to the CLI's `-p` and `--preserve` switches.\n\n- `\"Output\": { \"Directory\": \"your/path/prefix/here\" }`  \n  Specifies the output directory. Equivalent to the CLI's `-o` and `--output-dir` switches. See `webcompiler -o --help` for more details.\n\n3. Make webcompiler use these options\n\n```\nwebcompiler -r wwwroot -c webcompilerconfiguration.json\n```\n\n### Error list\n\nWhen a compiler error occurs, the tool exits with code `1` and displays the error to the console.\n\n### Contributing\n\nThis project is just starting. You can help in many different ways:\n\n- File bug reports\n\n    If you find a bug with the tool itself, please file a bug. If the result of compilation is incorrect, please file a bug with the respective library (see [the list of libraries](#libraries)), and only file a bug report here, if the version used is outdated.\n\n- Implement support for a language\n\n    Please submit your pull request for the language that you're implementing. Please make sure that your code is tested.\n\n- Ask for support of a specific language\n\n    If you would like to see support of a specific language, but can't implement it yourself, please search the issues for the language and leave your +1 vote on the issue, or file a new issue with the name of the language.\n\n### Libraries\n\n`Excubo.WebCompiler` depends on nuget packages for the compilation tasks:\n\n| Language | Library | Comments |\n|----------|---------| ---------|\n| Sass     | [LibSassHost](https://github.com/Taritsyn/LibSassHost) |\n| Sass     | [DartSassHost](https://github.com/Taritsyn/DartSassHost) | WebCompiler 3.X.Y+\n| Autoprefix | [AutoprefixHost](https://github.com/Taritsyn/AutoprefixerHost) |\n| CSS/JS   | [NUglify](https://github.com/xoofx/NUglify) | \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcubo-ag%2FWebCompiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexcubo-ag%2FWebCompiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcubo-ag%2FWebCompiler/lists"}