[browser-esbuild] add ability to configure processed assets output folder name

[MarcoGlauser]

Command

build

Description

The esbuild builder will hash asset filenames that are imported from css and put them in the /media folder.

.test {
    background: url('assets/images/next-arrow.svg') center no-repeat;
}

Will be transformed into the following:

.test {
    background: url('./media/next-arrow.CZQC2LXJ.svg') center no-repeat;
}

While this is a nice feature for cache busting, it clashes with our django server that also serves a /media folder.
For the sake of not breaking existing urls, it would be nice, if there was a way to configure this folder name.
We tried the resourcesOutputPath option but that doesn't seem to have any effect.

Describe the solution you'd like

It would be great if there was a way to configure the name of the processed asset output folder.

Describe alternatives you've considered

We can change the media folder for django. However, that would break existing links and I think that the folder name should not be hardcoded in the first place.

[I-A-S]

Agreed. Ability to customize this would be a good thing. I can look into implementing this if there's enough interest and the core team approves.

For the time being, if using an custom built Angular-cli is an option for you, start looking at these files and modify as needed. If you don't want to hardcode a new name even for the time being, you can look into adding to angular.json schema as well.

Line 122 of packages/angular_devkit/build_angular/src/builders/application/options.ts

Line 148 of packages/schematics/angular/service-worker/index.ts

Note these are just where angular hardcodes where to output but you might also want to update where it consumes/expects those resources to be too.

Cheers

[dgp1130]

We discussed this within the team recently. Normally asset URLs are just left alone because they can be used anywhere in any application and we can't reliably rename them across all usages. In this case the image was copied specifically because it is a file imported from CSS. It's likely the file actually exists at both the asset URL and the media/ path.

You can opt out of this transformation by adding assets/* to externalDependencies in the angular.json builder. #26093 (comment) This also means the URL with not include the file hash, which may or may not desirable for your use case. This is probably the easiest workaround for your particular use case.

We did briefly debate whether assets should always be considered external, given that we have to assume there is some reference to their path which can't be renamed by the build. However we decided not to because:

1. If asset paths are automatically external, there is no easy to way to disable that behavior. We'd need some other assetsDefaultToExternal: false flag, which we'd rather not add.
2. Copying an asset file to media/ is occasionally useful because it appends the file hash, which is helpful for immutable network caching.

A copied asset file can be a little misleading, but isn't the end of the world.

As for serving /media/... paths in production, I can understand that /media/... might have some unique meaning to your specific domain (such as serving user generated media). Given that Angular doesn't really own the URL space of a domain, we can't safely assume that any path is unused and free to put Angular assets on. This is true not just for media, but for any hard-coded path generated by Angular. I suspect that as a general rule we will likely need to always make any URL path configurable to allow developers to craft the URL scheme they want for their application.

We briefly considered moving this content into an Angular-namespaced path such as /__angular__/media/... which is significantly less likely to encounter a conflict and wouldn't need to be configurable. Ultimately, we decided that wasn't the right direction for now. We don't have any precedent for that kind of approach, and even then it doesn't fully remove the possibility of conflicts with a URL scheme (ex. serving /**/:image.png from some database would still conflict).

For now the right approach is probably to make the media/ path configurable.

[MarcoGlauser]

Thank you for the update!

The externalDependencies list solved the issue for assets in the /asset folder. We already have a cache invalidation flow in place, so that should be fine for now.

After adding externalDependencies for our asset folder, we found another case that we weren't aware of before.
We're using the 3rd party intl-tel-input package, which is shipping assets that are linked from their css files. (Country flags)
Webpack used to add a hash to these assets and put them i the root of the build output.
Esbuild is adding a hash to these and putting them in the media folder.
For our specific usecase, keeping the webpack behaviour would also work. But adding the ability to rename the output folder is probably the more versatile option.

The way I see it, a work around could be to add these assets to the externalDependencies list and after the build, copy them from project_root/node_modules/intl-tel-input/build/img/asset.png to output_root/node_modules/intl-tel-input/build/img/asset.png. It's a fragile work around but would work for us, until there's a more robust solution.

[giniedp]

@dgp1130 while "externalDependencies": ["assets/*"] does work for the build-angular:application builder, there seems to be no such option for build-angular:karma. In my case tests fail to compile and run. What is the proper way to make css asset URLs to work in both, build and test scenarios?

My use case is:
I have a custom tailwind plugin, that adds css components.

module.exports = ({ addComponents }) => {
  addComponents({
    '.nw-bg-pane': {
      background: "url('assets/bg-pane.jpg') black",
    },
  })
}

This produces following error during tests

./apps/web/styles/main.scss - Error: Module Error (from ./node_modules/.pnpm/postcss-loader@7.3.3_postcss@8.4.31_typescript@5.2.2_webpack@5.89.0/node_modules/postcss-loader/dist/cjs.js):
E:\Projects\nw-buddy\node_modules\.pnpm\tailwindcss@3.3.5_ts-node@10.9.1\node_modules\tailwindcss\components.css:1:0: Can't resolve 'assets/bg-pane.jpg' in 'E:\Projects\nw-buddy\apps\web\styles'

Changing the URL to absolute would work for build and test.

background: "url('/assets/bg-pane.jpg') black",

However, that needs the page to be served by a server, yet my second comilation target is electron and there i need to have such references to be relative.

[dgp1130]

@giniedp That feels like a different issue. Karma is still using Webpack under the hood so it doesn't have externalDependencies but also I don't believe it performs the media/ rename where that would be necessary. Can you file another issue about that? I suspect the real problem is either the Tailwind integration isn't respecting relative paths correctly or the Electron integration shouldn't require relative paths in the first place.

[giniedp]

ok, thx. Going to craft a reproduction repo and file a new issue.
Regarding electron: It serves files via file:// scheme by default, without a server. Relative URLs are required otherwise something like /assets/bg-pane.jpg is going to resolve to file:///assets/bg-pane.jpg which is then C://assets/bg-pane.jpg instead of being relative to the index html. Surely this can be configured, yet this is the default electron behavior.

[wleese]

Also ran into this. Not sure what the workaround would be, because I want cache busting on the assets that are now located in "media/", so using externalDependencies doesn't help. Also, because users of our Angular app sometimes define their own 'layer 7 firewall rules' (e.g. account X cannot access /admin, but can access /assets/**), changing the location of the assets, even when fixing all references in our stylesheets, is a 'breaking change' for our users.

Of course, this is a new major Angular release, so breaking changes should be fine. I'd prefer not forcing a breaking change upon my own users, however who previously were oblivious to Angular upgrades, because it was a frontend-only thing.

Would be great if this was configurable 🙏