astro:env .env.template generation

[florian-lefebvre]

Body

Summary

Generate .env.template based on the astro:env schema.

Background & Motivation

The .env.template file is used as template for .env. It contains all the necessary keys (and sometimes default values). It should not contain sensitive data. Developers can then copy it to .env and filling the environment variables.

While it's simple to keep in sync the env schema with a custom .env.template, it gets harder:

• For big applications where it's easy to reach 20-30 variables
• When using integrations that add their own requirements

It's also common to want to group variable keys by purpose (eg. stripe).

Goals

• Allow generating a .env.template from the env schema
• Allow creating groups of keys
• Allow opting-out per key

Example

Enabling

I think this feature should be opt-in, under a flag:

export default defineConfig({
	env: {
		schema: {
			// ...
		},
		generateTemplate: true
	}
})

Configuration

Each field would have a new template property:

• undefined (default): use the default sorting method (more below)
• string: used to group
• false: exclude from the generation (eg. for inlined system env vars by adapters)

Creating the file

The .env.template generation would happen each time a sync occurs, that is when astro sync or syncInternal is called.

As for its content, it would follow these rules for sorting:

• Groups first
• Order groups by key
• Order keys alphabetically

Example

export default defineConfig({
	env: {
		schema: {
			A: envField.string({ /* ... */ }),
			B: envField.number({ template: 'foo' }),
			C: envField.boolean({ template: 'bar' }),
			AB: envField.boolean({ template: 'bar' }),
			D: envField.string({ template: false }),
			E: envField.boolean({ /* ... */ }),
		},
		generateTemplate: true
	}
})

# bar
AB=
C=

# foo
B=

A=
E=

Questions

• What if the user already has a .env.template? Should we override it? Merge it? I'm a bit concerned about the complexity if we have to diff etc

[Adammatthiesen]

This would be great, would it be able to do full comment blocks(multi-line)? The example shown is already very similar to how i create the example files used for most of my integrations 😅

Merge option would be the best IMO if there is a way to check for existing values? in my example below the Authentication env variables come from one integration while the Cloudinary one comes from another...

For example, StudioCMS playground .env.demo file

# credentials for GitHub OAuth
CMS_GITHUB_CLIENT_ID=
CMS_GITHUB_CLIENT_SECRET=
# Github Callback URL `http://localhost:4321/dashboard/login/github/callback`
# Github callback URL is NOT AN ENV VARIABLE!

# credentials for Discord OAuth
CMS_DISCORD_CLIENT_ID=
CMS_DISCORD_CLIENT_SECRET=
CMS_DISCORD_REDIRECT_URI=http://localhost:4321/dashboard/login/discord/callback

# credentials for Google OAuth
CMS_GOOGLE_CLIENT_ID=
CMS_GOOGLE_CLIENT_SECRET=
CMS_GOOGLE_REDIRECT_URI=http://localhost:4321/dashboard/login/google/callback

# credentials for auth0 OAuth
CMS_AUTH0_CLIENT_ID=
CMS_AUTH0_CLIENT_SECRET=
CMS_AUTH0_DOMAIN=
CMS_AUTH0_REDIRECT_URI=http://localhost:4321/dashboard/login/auth0/callback

## Cloudinary Javascript SDK
CMS_CLOUDINARY_CLOUDNAME="demo"

[florian-lefebvre]

would it be able to do full comment blocks(multi-line)

We can see how to handle this, any API idea?

Merge option would be the best IMO if there is a way to check for existing values?

Not sure what you mean! The template is generated after all configs are merged so a same group can be reused across integrations

[alexanderniebuhr]

I like the idea, but I don't think we should limit this to .env files. We should think of an modular API, which allows adapters to generate different files, e.g. wrangler.toml and .dev.vars for Cloudflare projects 🤔

[florian-lefebvre]

You're right. Given how setAdapter works, I think this should not happen in this function but rather by exposing a utility in astro:config:setup?

[bluwy]

My thoughts on this from the last discussion is that it would be simpler if users authored the .env.template themselves.

1. They can include more documentation on what each env var is for, how to retrieve an API key etc.
2. They can set example defaults that would work locally (e.g. for quick onboarding).
3. Env vars are not changed often that we need a way to sync it.
4. Less point of configuration, e.g. what if they want it to be .env.sample or .env.demo instead?

What if the user already has a .env.template?

We also wouldn't have to worry about this. If someone added additional documentation to .env.template, we would need to warn there's a mismatch to either "update the documentation in astro.config.js instead" or "turn off template generation". Both which I feel isn't a great dev experience.

[florian-lefebvre]

Yeah that makes more sense now since the call, there aare way more scenarios and things to handle than anticipated. I guess that would be fine as an integration

[florian-lefebvre]

Closing as this can be an integration