Asset Handling Overhaul
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 738
- Forks
- 48
- PR merge metrics
- No merged PRs in 30d
Description
This issue was originally opened by @chriseppstein at https://github.com/sass-eyeglass/ember-cli-eyeglass/issues/52.
There's a number of issues involving assets and how they work in eyeglass with ember apps, especially with ember engines, and especially when those engines are in lazy mode. We're going to change the way assets are configured by default for ember applications so that `asset-url()` works better and more predictably for ember applications.
## Constraints
Current invocations of `asset-url()` will continue to work unmodified, providing backwards compatibility to existing apps. This change must be non-breaking and introduce no deprecations. The only risk for apps is if there is a url to an asset installed by eyeglass during compilation, where that URL has been hard-coded instead of referencing the asset according to the url returned by `asset-url()` or `asset-uri()`.
## Current Problems:
* In some cases, assets installed by eyeglass do not end up in the final build.
* Assets in an addon are installed by eyeglass as well as by ember-cli, and depending on configuration, they might be duplicated and have different urls, resulting in additional asset transfer for some applications.
* Transitive dependencies on assets delivered by the same eyeglass module in an application can result in the same asset being installed in different locations on a per consuming engine, addon, or application basis.
* It's unclear whether relative asset paths are working correctly across the range of use cases for builds occurring in addons and engines.
* It's unclear whether assets can be correctly referenced from both the addon and app directories using `asset-url()`.
* It's unclear whether assets are correctly handled for nested engines/addons.
## Design
Assets delivered from an eyeglass module should be installed to a canonical location. Because eyeglass modules are guaranteed to resolve to a single instance, the assets are guaranteed to be the same across multiple transitive dependencies even if they resolve from npm to different versions.
### Asset Installation and Default URLs
Assets will be installed according to the source location.
* Assets in the public directory of an application or addon can be referenced by the `asset-url()` function. Baring intervention from a custom installer, Eyeglass will not install these assets, but it will return a url that conforms to the location that ember will ultimately install the public asset.
* Baring intervention from a custom installer, Assets from an eyeglass module will be installed into `assets/eyeglass-modules//`. `ember-cli-eyeglass` will accept a new configuration parameter that allows the directory of eyeglass module assets to be specified but it will default to `assets/eyeglass-modules`. The behavior of how conflicts between installed assets and assets in the public directory is handled will be documented, but it is decided by whatever ember-cli does naturally.
* An ember engine that is also an eyeglass module can expose assets from a non-public directory. (Open Question: Should addons have this ability without becoming an eyeglass module? The answer may depend on how overrides turn out to work.)
### Asset Overrides:
*Note: there is currently an override behavior in eyeglass, but it's really not clear how it interacts with ember-cli's public directory semantics* We need to decide what the right semantics are and make sure it's clearly documented and implemented accordingly.
Here's how I think it should work:
Assets in the public directory of the app can override the asset normally delivered by an engine, addon, or module by having an asset in a directory that overrides that of the same source url. For example, if an engine or addon named `my-swanky-addon` has an asset at `/public/assets/icons/swanky.gif`, then that can be accessed via `asset-url("my-swanky-addon/icons/swanky.gif")`. If the app puts a different image in the public directory at `/public/assets/my-swanky-addon/icons/swanky.gif`, this will be the asset resolved regardless of whether the app or addon is the one creating the url.
If the asset is referenced as `asset-url("icons/swanky.gif")` from either the addon or the app, it will still work, but the override location will then be `/public/assets/icons/swanky.gif` and I need to know whether this file would be overwritten by the addon or if the app wins according to ember-cli semantics.
I think the decisions for how to find files in the public directory are based on a merged app tree, not the application source. This means that addons can deliver assets to the app's public directory that have the effect of overriding the assets of other eyeglass addons or modules. This allows for overriding of assets by an addon that nests another addon or is installed along side the main application.
Asset overriding must work the same for both lazy and eager engines, even though lazy engines have a different broccoli tree.
## WIP
There's still some unanswered aspects but I want to make sure this core design is solid.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing asset-url() and asset-uri() through the Ember CLI integration, including the public directories, custom installer behavior, and the proposed configuration for assets/eyeglass-modules. Resolve the open questions about overrides and relative paths for nested, lazy, and eager engines. Done means canonical asset installation, compatible URLs, defined override semantics, and documented behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- sass, typescript
- Domain
- build-system, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100