inject_assets_builder 1.0.0 inject_assets_builder: ^1.0.0 copied to clipboard
A builder that makes it possible for a package to access files from packages depending on it.
inject assets builder #
This package contains a builder that makes it possible for a package to access files from packages depending on it.
The build package uses the syntax pkg|lib/foo.txt
to refer to the file foo.txt
in the lib/
directory of package pkg
. In this document, I'll use the same syntax for all references to files to avoid ambiguity.
Example use case #
I'll use this example to illustrate how the builder works, but the injection mechanism is not limited to SASS files, as explained below. In this document, I'll refer to a package that is used as a dependency as dep
, and to a package consuming dep
and injecting assets into it as app
.
I work on a package that contains Angular components, and a couple of web apps that use these components. Each app has a different design, so I need to set some CSS properties of the components from within the app packages. The component styles are compiled from SASS, so the most convenient solution (for a consumer of dep
) would be if dep
read these values from a file in app
. I want that file to be app|lib/_variables.scss
.
dep
can't simply import a file from app
, because SASS import paths must be statically known, and dep
could be used by multiple apps. That's where this builder comes into play.
This package contains a builder inject_scss_files
that looks for a provisional dep|lib/_variables.default.scss
file and creates the final dep|lib/_variables.scss
file. The contents of dep|lib/_variables.scss
are copied from app|lib/_variables.scss
, but the source file is configurable in the build configuration. This way, a package app2
could set app2|lib/_variables.scss
as the source.
Now, components in dep
can use the statically known import path dep|lib/_variables.scss
, but will access the file contents from app
at build time.
Injecting SASS files #
These are all the required steps to implement this use case.
In dep
, add this package to the dependencies. Also add a dependency on build_config to ensure compatibility with consumers of your package.
Then, create a dep|build.yaml
file with the following content:
targets:
# When a package depending on `dep` is built, this build target is
# automatically built too.
$default:
builders:
inject_assets_builder|inject_scss_files:
enabled: true
In app|build.yaml
, specify which assets should be injected for the .default
assets:
global_options:
inject_assets_builder|inject_scss_files:
options:
asset_overrides:
'dep|lib/_variables.default.scss': 'app|lib/_variables.scss'
If you don't specify a source for a .default
asset, the asset itself will be used as the final file. This means that a consumer doesn't have to configure anything if they are satisfied with the default contents.
Side note on SASS files: app|lib/_variables.scss
can import the default file with @import 'package:dep/variables.default';
. Then, you only need to assign those variables you actually want to change.
Injecting assets with other extensions #
The Dart build system requires that builders statically declare all the file extensions they run on. This makes it impossible to process all .default.*
files in a single builder. If you need to inject assets that don't end in .scss
or .sass
, you need to declare your own builder. You can use inject_asset_builder|build.yaml
as a template; you should only need to change the build_extensions
and file_extensions
configuration and the builder name. Then reference it with $yourPackage|$builderName
in builders
and global_options
.