Add dev prod example

[allan2]

Many recurring questions from users are about overriding or how to handle errors when a .env file is found or not found.

This PR

• creates an examples directory
• adds an example showing how behaviour can differ across dev and prod modes

[sonro]

Overall I like the example - but is a full directory per example the direction we want to go? Tokio is a large multi-crate library and they just have single files for their top level examples.

Axum does it with a crate per example, but I think a web framework is more suited to this approach than an envfile loader. I doubt any of our future examples will require multiple source files (and if we do they can be in their own directory).

[allan2]

The reason for the crate per example was to have the .env fille collocated. I imagine different examples will use different .env files.

Does it still make sense to do it this way?

[github-actions[bot]]

[sonro]

The reason for the crate per example was to have the .env fille collocated. I imagine different examples will use different .env files.

That is a good point. One alternative would be to have a shared .env file in the repository root - with keys per example. It could get quite messy as the examples folder grows. However, it does mean a user can do cargo run --example dev-prod directly from the repo root. On the other hand if they wanted to inspect the .env file, it might be hard to discern how it affects the example with multiple keys.

---

Another alterative would be to just have separate folders (not crates) per example. With an .env file and a .rs file - nothing more. Each example would need to set its process' working directory to still be run from the repo root...

let file = PathBuf::from_str(file!()).unwrap();
let dir = file.parent().unwrap();
env::set_current_dir(dir).unwrap();

Which is rather gruesome IMO. It could be abstracted away into a shared/common module, but it still leaves the problem of an example containing setup code a user wouldn't need.

---

So it comes down to a larger envfile in the repo root with the convenience of cargo run --example dev-prod and a flat examples directory OR simpler .env files but cd examples/dev-prod && cargo run being needed per example and a "crate-per-example" structure.

Personally I prefer the larger envfile, but it shouldn't matter if the examples folder has a readme which is quick and clear in how to view and run them. It's up to you.