Env as HTML Data #53

mars · 2025-11-21T15:27:37Z

A new approach to keeping config vars fresh at runtime 🍃

See rendered README doc:
Heroku Cloud Native Static Web Server Buildpack: Runtime App Configuration.

This will be a major version bump to v2.0.0, because all Release Phase integration is being dropped. This major version should not require any migration/upgrading docs, because this CNB project is still warned as experimental on the front-page README.

…s function renaming to clarify control flow.

…process.

…(top-level index.html)

…ntime config.

dzuelke · 2025-11-27T15:57:52Z

Would it not be much simpler (no re-rendering of the HTML document etc) to generate a .js file with the config var values that can then be included?

mars · 2025-12-01T19:24:48Z

@dzuelke HTML data-* attributes are a standard interface within web browsers for access from JS and CSS. The interface is available whether working locally or deployed in the container.

This body data attribute injection is a technique that we've been working with in Heroku Front-end engineering, and have found our current proof-of-concept used for vibes.heroku.com is performing beautifully.

Problems with writing a JS file at runtime:

if the goal is no file injection, how does it get imported at runtime?
what does the developer experience look like, to have something that works locally and equally in deployment?
adding JS at runtime may create problems for sites' Content-Security-Policy or Subresource Integrity
the interface to access values and set defaults would be proprietary.

HTML Data attributes avoids these issues using a web-native interface which is agnostic to any JS module type or framework.

colincasey · 2025-12-02T14:31:31Z

buildpacks/static-web-server/src/config_web_server.rs

+        .or(Some(PathBuf::from(DEFAULT_DOC_ROOT)))
+        .expect("should always default to some value");


Suggested change

.or(Some(PathBuf::from(DEFAULT_DOC_ROOT)))

.expect("should always default to some value");

.unwrap_or(PathBuf::from(DEFAULT_DOC_ROOT));

colincasey · 2025-12-02T14:31:50Z

buildpacks/static-web-server/src/config_web_server.rs

+        .or(Some(DEFAULT_DOC_INDEX.to_owned()))
+        .expect("should always default to some value");


Suggested change

.or(Some(DEFAULT_DOC_INDEX.to_owned()))

.expect("should always default to some value");

.unwrap_or(DEFAULT_DOC_INDEX.to_string());

colincasey · 2025-12-02T14:39:27Z

buildpacks/static-web-server/src/config_web_server.rs

+        .or(Some(true))
+        .expect("should always default to some boolean")


Suggested change

.or(Some(true))

.expect("should always default to some boolean")

.unwrap_or(true)

colincasey · 2025-12-02T15:00:44Z

buildpacks/static-web-server/src/bin/env-as-html-data.rs

+            Ok(true) => {
+                eprintln!("Runtime configuration written into {file_path}");
+            }
+            _ => (),


Silence for this branch?

colincasey · 2025-12-02T15:09:40Z

common/env_as_html_data/src/lib.rs

+pub fn env_as_html_data<S: BuildHasher>(
+    data: &HashMap<String, String, S>,
+    file_path: &PathBuf,
+) -> Result<bool, Error> {


Nit: I'm having trouble following what this bool represents while reading through the code. Personally, I find enums or newtypes are a cheap way to clarify intent vs. boolean flags when it comes to both argument and return values. E.g.;

pub(crate) struct EnvInjected(bool); // or pub(crate) enum EnvInjected { Yes, No } pub fn env_as_html_data<S: BuildHasher>( data: &HashMap<String, String, S>, file_path: &PathBuf, ) -> Result<EnvInjected, Error> { ... }

colincasey · 2025-12-02T15:13:24Z

common/env_as_html_data/src/lib.rs

+pub(crate) fn parse_html_and_inject_data<S: BuildHasher>(
+    data: &HashMap<String, String, S>,
+    html_bytes: &[u8],
+) -> Result<(bool, String), Error> {


Similar comment as above. Given how this value is propagating, maybe an enum makes more sense because it could simplify the false path which doesn't do anything with the html doc returned but is kind of forced to return it due to the use of the tuple (bool, String). E.g.;

pub(crate) enum EnvInjected { Yes(String), No }

colincasey · 2025-12-02T15:20:14Z

common/env_as_html_data/src/lib.rs

+fn match_html_body_and_inject_data<S: BuildHasher>(
+    data: &HashMap<String, String, S>,
+    node: &Handle,
+) -> Result<(bool, bool), Error> {


And this boolean tuple is the most confusing 😅

Looking at the signature of the function, I have no clue what boolean 1 represents nor boolean 2 without reading the implementation and how the return values are used. I imagine this same will be true for anyone returning to this code in a week or two.

It also makes it hard to spot during review if someone changes this code in the future and accidentally confuses boolean 2 with boolean 1 in the return value.

colincasey · 2025-12-02T15:25:38Z

buildpacks/static-web-server/src/config_web_server.rs

+            "ENV_AS_HTML_DATA_TARGET_FILES",
+            default_doc_path,


The environment variable (and usage in the env-as-html-data binary) implies that multiple files can be processed but only one is set here? How does this work when there are multiple HTML files in the static site? Is the user expected to manually configure each? Can they use a glob pattern?

colincasey · 2025-12-02T15:26:23Z

buildpacks/static-web-server/src/bin/env-as-html-data.rs

+        std::process::exit(1);
+    }).map(|v| v.split(',').collect()).expect("should exit failure when none");
+
+    for file_path in file_paths {


It may also be a good idea to only process files found within the app's workspace directory.

mars added 20 commits November 20, 2025 10:27

Initial impl of HTML DOM injection

c1408a1

Fix lint warnings

86aab50

Make no HTML changes without public data.

f333d29

Organize use statements

c12f4b6

Clarify element expectations as errors

e8ec8b3

Emit proper No Body Element error

78033b0

Test to prove that invalid HTML is corrected.

28897af

Distinguish whether HTML data-* attribute injection happened; include…

6032b02

…s function renaming to clarify control flow.

Overwrite pre-existing attributes.

e3c88c6

Rewrite HTML file with env_to_html_data; implement exec.d/web launch …

c073f92

…process.

Make runtime config compatible with apps that have an empty doc root …

8ea6269

…(top-level index.html)

A missing target file is not an error, but skipped & warned during ru…

e847c14

…ntime config.

Fix lints

d006e45

Correct runtime config description

a924503

Fix lints

34f74ae

Fix lints

9deb04f

Scope the runtime config internals to web process

9833262

Replace Release Build with Runtime Config in Ember buildpack

ce8cbfc

Doc replacement of Release Build with Runtime Config

f3b456d

Remove release-phase buildpack dependencies

ae71810

mars requested a review from colincasey November 26, 2025 22:43

Clarify docs about static-web-server build command

7d41ccb

mars requested review from angeldcampbell, chandlerprall and wycats December 1, 2025 20:56

mars marked this pull request as ready for review December 1, 2025 20:58

colincasey reviewed Dec 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Env as HTML Data #53

Env as HTML Data #53

Uh oh!

mars commented Nov 21, 2025 •

edited

Loading

Uh oh!

dzuelke commented Nov 27, 2025

Uh oh!

mars commented Dec 1, 2025 •

edited

Loading

Uh oh!

colincasey Dec 2, 2025

Uh oh!

colincasey Dec 2, 2025

Uh oh!

colincasey Dec 2, 2025

Uh oh!

colincasey Dec 2, 2025

Uh oh!

colincasey Dec 2, 2025

Uh oh!

colincasey Dec 2, 2025

Uh oh!

colincasey Dec 2, 2025

Uh oh!

colincasey Dec 2, 2025

Uh oh!

colincasey Dec 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		.or(Some(PathBuf::from(DEFAULT_DOC_ROOT)))
		.expect("should always default to some value");

	.or(Some(PathBuf::from(DEFAULT_DOC_ROOT)))
	.expect("should always default to some value");
	.unwrap_or(PathBuf::from(DEFAULT_DOC_ROOT));

		.or(Some(DEFAULT_DOC_INDEX.to_owned()))
		.expect("should always default to some value");

	.or(Some(DEFAULT_DOC_INDEX.to_owned()))
	.expect("should always default to some value");
	.unwrap_or(DEFAULT_DOC_INDEX.to_string());

		.or(Some(true))
		.expect("should always default to some boolean")

	.or(Some(true))
	.expect("should always default to some boolean")
	.unwrap_or(true)

Env as HTML Data #53

Are you sure you want to change the base?

Env as HTML Data #53

Uh oh!

Conversation

mars commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dzuelke commented Nov 27, 2025

Uh oh!

mars commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mars commented Nov 21, 2025 •

edited

Loading

mars commented Dec 1, 2025 •

edited

Loading