Assets & Bundle Layout
In some cases a component, in addition to Javscript files, also contains CSS files, images, JS workers that are not handled by the bundler. For example:
- An "icon" components wants to include extra SVG files.
- A component wraps a library which expects CSS files to be in a hardcoded place and the CSS references images with relative paths and hardcoded names.
- A component uses a library which uses web workers, which atm can't be bundled to ES6 modules because most browsers don't support them, so they have to be copied as is.
- A component uses a library that ships JSON files including translations which that library expects in a certain location.
In some cases this can be worked around in the bundler by using plugins to inline the files into JS and thus make them part of the bundling process:
Sadly the only way atm (ideas to improve this welcome) is to leak this implementation detail out and leave the copying of those files to the integrator/bundle creator.
To somewhat improve this we use a set of rules for how our packages expect those files to end up in the file system in relation to the bundle.
Assume this is the directory where everything ends up
Where all the bundle entry points end up.
This is were all auto generated and ideally content-hashed files end up. Usually produced by the bundling process. This directory can have longer caching durations as the file names depend on the content.
This is where all files end up that need to have a fixed name/path.
For example an icon component could have
files that need to be copied there need to be documented in the README of the
respective component. This also applies to all transitive dependencies, so if
COMPONENT-A wants asset ASSET-A and depends on COMPONENT-B which needs ASSET-B,
then you using COMPONENT-A requires you to copy both ASSET-A and ASSET-B.
Since these files have fixed names the cache duration should be limited to avoid stale data on re-deploys.
We allow developers to define custom assets, which means that the default dbp assets get overwritten by assets which the developers can define. This allows developers to develop for different environments, for example for a whitelabel dbp app and simultaneously for another organization with different assets.
To use custom assets, a directory with all custom assets has to be placed in
assets_custom/dbp-appname/assets/. For example, for mono the directory name would be
The structure of the
assets_custom/dbp-appname/assets/ directory has to be the same as the default assets directory
assets/. Thus, files and directories with the same name inside of
assets/ also have to be present inside
We recommend to simply copy the
assets/ directory to
assets_custom/dbp-appname/assets/ and to replace all dbp assets with the respective custom assets. This way, it is unlikely that some assets are forgotten when creating the custom assets directory.