`shopify-app-express` silently reads env vars (`SHOPIFY_API_KEY`, `SHOPIFY_API_SECRET`, `HOST`) but this is not documented

[sergiocasao]

Overview/summary

@shopify/shopify-app-express automatically reads the following environment variables when they are not explicitly passed to shopifyApp():

• SHOPIFY_API_KEY
• SHOPIFY_API_SECRET
• HOST (split into hostScheme and hostName)
• SCOPES

This behavior is implemented in apiConfigWithDefaults() in the source, but is not mentioned anywhere in the README or docs.

Why it matters

Developers using the library may:

• Not know why their app works (or breaks) depending on which env vars are set
• Be confused when configuration seems to appear "for free" with no explicit setup
• Struggle to debug auth issues without knowing these implicit defaults exist

Suggested fix

Add a section to the README documenting the supported environment variables, for example:

Environment Variables

The following environment variables are automatically read if not explicitly provided in the config:

Variable	Maps to config field	Description
SHOPIFY_API_KEY	apiKey	Your app's API key
SHOPIFY_API_SECRET	apiSecretKey	Your app's API secret
HOST	hostName / hostScheme	Your app's public URL
SCOPES	scopes	Comma-separated list of OAuth scopes

[ckmtools]

Good catch — silent env var reads are a common source of "works on my machine but breaks in CI" confusion.

One thing worth verifying before writing the docs table: the list in your issue may not be exhaustive. A quick grep to find every process.env read in the package:

grep -r 'process\.env\.' packages/apps/shopify-app-express/src/ --include='*.ts' | grep -oP 'process\.env\.\K[A-Z_]+' | sort -u

The HOST one in particular is worth flagging explicitly in docs — it shadows the system HOST env var on some Linux distros, which can cause confusing behavior that's hard to trace back to the library.

For the table, also useful to document what happens when each var is absent (does the library throw? silently no-op? fall back to a default?).

I'm building a tool that automates this kind of env var audit across an entire project — envscan if curious.

[sergiocasao]

1. SHOPIFY_API_KEY, SHOPIFY_API_SECRET and HOST all cause a hard ShopifyError at shopifyApp() call time if absent. Cannot initialize Shopify API Library. Missing values for: ...
2. SCOPES silently no-ops without warning or error.
3. AFAIK $HOST is not a standard POSIX env var, not set by Linux distributions universally, and not set by bash.

The real footgun with HOST is the scheme-parsing behavior: the library expects the value to include a scheme (https://myapp.example.com) and splits on :// to derive both hostScheme and hostName. If someone supplies a bare hostname (myapp.example.com), the split produces:

• hostScheme - "myapp.example.com" (wrong)
• hostName - "myapp.example.com" (accidentally correct)

shopify-app-js/packages/apps/shopify-app-express/src/index.ts

Lines 116 to 117 in 0361595

	hostScheme: (process.env.HOST?.split('://')[0] as 'http' | 'https')!,
	hostName: process.env.HOST?.replace(/https?:\/\//, '')!,

The error only surfaces at runtime when OAuth redirects are built with the wrong scheme. No validation catches a hostScheme that isn't "http" or "https".

[ckmtools]

Thanks @sergiocasao — that level of detail is exactly what developers need when debugging auth failures in production.

The HOST scheme-parsing behavior is a particularly nasty footgun. The error only surfaces at OAuth redirect time (not at shopifyApp() startup), so it can slip through local testing if you happen to set HOST with a scheme but a teammate or CI environment does not. Worth calling out explicitly in docs.

We ran envscan against the package and found the same three hard-required vars (SHOPIFY_API_KEY, SHOPIFY_API_SECRET, HOST), plus SCOPES as an optional/silent one. The grep output aligned with your assessment.

Would the team be open to a short section in the README documenting these — required vs optional, what happens when absent, and the HOST scheme requirement? Something like:

Variable	Required	Behavior if absent
SHOPIFY_API_KEY	Yes	Hard ShopifyError at init
SHOPIFY_API_SECRET	Yes	Hard ShopifyError at init
HOST	Yes	Hard ShopifyError at init; must include scheme (https://)
SCOPES	No	Silently no-ops

Happy to open a PR for this if useful — just wanted to confirm the full var list and behavior first before writing docs.

[sergiocasao]

I opened a PR a couple days ago #3111 but feel free to make any update o start a new one.