search

dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.09k stars 866 forks source link

[Feature Request] Remove ‘*.map‘ files from nupkg #9058

Open filzrev opened 1 year ago

filzrev commented 1 year ago

Is your feature request related to a problem? Please describe. Currently docfx NuGet package is relatively large size (about 72 MB). And almost size is occupied by template's source map(.map) files. For example. modern template is about 36MB and .map files occupies 26.6MB. (about 73%)

If it can reduce nupkg size. It can save local disk space and faster install/update.

Describe the solution you'd like Disable sourcemap option when publishing packages.

Downsides

Describe alternatives you've considered Another approach to reduce nupkg size is to merge templates folders that contains duplicated files. (#8691)

Additional context Related issue/discussion

yufeih commented 1 year ago

Sounds reasonable. We can publish the .map files to http://dotnet.github.io/docfx/jsmap/{version}/ to help with debugging.

KalleOlaviNiemitalo commented 1 year ago

Do the minified files include all the legal notices that have to be distributed, or are some of them only in the map files?

KalleOlaviNiemitalo commented 1 year ago

docfx.2.70.0.nupkg = 76011217 bytes.

Extract the files and repack with PowerShell Compress-Archive "*" -DestinationPath ../docfx.zip = 75996068 bytes. This is a bit less because Compress-Archive does not make zip entries for directories.

Delete all *.js.map and *.css.map files and repack with PowerShell = 56176187 bytes. Saved 19819881 bytes = 26%. The actual savings might be a bit more if the *.js files would no longer carry the names of the map files.

KalleOlaviNiemitalo commented 1 year ago

In a private project, I needed to distribute some large XSD and XSLT files with an executable. I made the build system compress them with gzip and embed the results to the assembly, and made the executable decompress them on the fly. This reduced the artifact size and did not noticeably slow down the execution. For DocFX, I think a similar hack would not reduce the nupkg size as the files are compressed in the nupkg anyway, but it would reduce I/O during nupkg install.

yufeih commented 1 year ago

Eventually I think we would publish templates separately from the executable, for both the official templates and community templates. Packaging options are open for discussion, such as NuGet (#7974), npmjs, git, OCI, etc.

KalleOlaviNiemitalo commented 1 year ago

I'd like to keep using the docfx tool without having to install node.js and run NPM. Popular NPM packages have been hijacked in the past, and although NPM is starting to require two-factor authentication, I'd prefer avoiding that ecosystem as much as possible.

filzrev commented 1 year ago

Do the minified files include all the legal notices that have to be distributed, or are some of them only in the map files?

It seems current docfx generated site don't contains license notice comments information for some files that are generated by esbuild'splitting feature.

I've created separate issue relating legal comments: https://github.com/dotnet/docfx/issues/9059