Use APP_ENV to determine what config to load, falling back to NODE_ENV

.changeset/old-eagles-admire.md

@@ -0,0 +1,6 @@
+---
+'@backstage/backend-common': minor
+'@backstage/cli': minor
+---
+
+Use APP_ENV before NODE_ENV for determining what config to load

CHANGELOG.md

@@ -8,6 +8,10 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re
 
 > Collect changes for the next release below
 
+### @backstage/cli
+
+- The recommended way to set the configuration environment is now to use `APP_ENV` instead of `NODE_ENV`.
+
 ### Backend (example-backend, or backends created with @backstage/create-app)
 
 - A plugin database manager has been created, and plugins can now accept that interface as an argument during initialisation. Notably, the `auth` plugin has a [`createRouter` signature change](./plugins/auth-backend/src/service/router.ts). See [packages/backend/src/index.ts](./packages/backend/src/index.ts) on how to set it up. [#2697](https://github.com/spotify/backstage/pull/2697)

docs/conf/writing.md

@@ -65,9 +65,10 @@ All `app-config.yaml` files inside the monorepo root and package root are
 considered, as are files with additional `local` and environment affixes such as
 `development`, for example `app-config.local.yaml`,
 `app-config.production.yaml`, and `app-config.development.local.yaml`. Which
-environment config files are loaded is determined by the `NODE_ENV` environment
-variable. Local configuration files are always loaded, but are meant for local
-development overrides and should typically be `.gitignore`'d.
+environment config files are loaded is determined by the `APP_ENV` environment
+variable, or `NODE_ENV` if it is not set. Local configuration files are always
+loaded, but are meant for local development overrides and should typically be
+`.gitignore`'d.
 
 All loaded configuration files are merged together using the following rules:
 

docs/getting-started/deployment-other.md

@@ -13,7 +13,7 @@ Run the following commands if you have Docker environment
 ```bash
 $ yarn install
 $ yarn docker-build
-$ docker run --rm -it -p 7000:7000 -e NODE_ENV=development example-backend:latest
+$ docker run --rm -it -p 7000:7000 -e APP_ENV=production -e NODE_ENV=development example-backend:latest
 ```
 
 Then open http://localhost/ on your browser.

packages/backend-common/src/config.ts

@@ -24,7 +24,7 @@ export async function loadBackendConfig() {
   /* eslint-disable-next-line no-restricted-syntax */
   const paths = findPaths(__dirname);
   const configs = await loadConfig({
-    env: process.env.NODE_ENV ?? 'development',
+    env: process.env.APP_ENV ?? process.env.NODE_ENV ?? 'development',
     rootPaths: [paths.targetRoot, paths.targetDir],
     shouldReadSecrets: true,
   });

packages/cli/src/commands/app/build.ts

@@ -22,7 +22,7 @@ import { buildBundle } from '../../lib/bundler';
 
 export default async (cmd: Command) => {
   const appConfigs = await loadConfig({
-    env: process.env.NODE_ENV ?? 'production',
+    env: process.env.APP_ENV ?? process.env.NODE_ENV ?? 'production',
     rootPaths: [paths.targetRoot, paths.targetDir],
   });
   await buildBundle({

packages/cli/src/commands/app/serve.ts

@@ -22,7 +22,7 @@ import { serveBundle } from '../../lib/bundler';
 
 export default async (cmd: Command) => {
   const appConfigs = await loadConfig({
-    env: process.env.NODE_ENV ?? 'development',
+    env: process.env.APP_ENV ?? process.env.NODE_ENV ?? 'development',
     rootPaths: [paths.targetRoot, paths.targetDir],
   });
   const waitForExit = await serveBundle({

packages/cli/src/commands/backend/dev.ts

@@ -22,7 +22,7 @@ import { serveBackend } from '../../lib/bundler/backend';
 
 export default async (cmd: Command) => {
   const appConfigs = await loadConfig({
-    env: process.env.NODE_ENV ?? 'development',
+    env: process.env.APP_ENV ?? process.env.NODE_ENV ?? 'development',
     rootPaths: [paths.targetRoot, paths.targetDir],
   });
 

packages/cli/src/commands/config/print.ts

@@ -22,7 +22,8 @@ import { stringify as stringifyYaml } from 'yaml';
 
 export default async (cmd: Command) => {
   const appConfigs = await loadConfig({
-    env: cmd.env ?? process.env.NODE_ENV ?? 'development',
+    env:
+      cmd.env ?? process.env.APP_ENV ?? process.env.NODE_ENV ?? 'development',
     shouldReadSecrets: cmd.withSecrets ?? false,
     rootPaths: [paths.targetRoot, paths.targetDir],
   });

packages/cli/src/commands/index.ts

@@ -133,7 +133,7 @@ export function registerCommands(program: CommanderStatic) {
     .option('--with-secrets', 'Include secrets in the printed configuration')
     .option(
       '--env <env>',
-      'The environment to print configuration for [NODE_ENV or development]',
+      'The environment to print configuration for [APP_ENV or NODE_ENV or development]',
     )
     .option(
       '--format <format>',

packages/cli/src/commands/plugin/export.ts

@@ -22,7 +22,7 @@ import { buildBundle } from '../../lib/bundler';
 
 export default async (cmd: Command) => {
   const appConfigs = await loadConfig({
-    env: process.env.NODE_ENV ?? 'production',
+    env: process.env.APP_ENV ?? process.env.NODE_ENV ?? 'production',
     rootPaths: [paths.targetRoot, paths.targetDir],
   });
   await buildBundle({

packages/cli/src/commands/plugin/serve.ts

@@ -22,7 +22,7 @@ import { serveBundle } from '../../lib/bundler';
 
 export default async (cmd: Command) => {
   const appConfigs = await loadConfig({
-    env: process.env.NODE_ENV ?? 'development',
+    env: process.env.APP_ENV ?? process.env.NODE_ENV ?? 'development',
     rootPaths: [paths.targetRoot, paths.targetDir],
   });
   const waitForExit = await serveBundle({

packages/config-loader/src/lib/resolver.ts

@@ -28,7 +28,7 @@ type ResolveOptions = {
  * Resolves all configuration files that should be loaded in the given environment.
  *
  * For each root directory, search for the default app-config.yaml, along with suffixed
- * NODE_ENV and local variants, e.g. app-config.production.yaml or app-config.development.local.yaml
+ * APP_ENV and local variants, e.g. app-config.production.yaml or app-config.development.local.yaml
  *
  * The priority order of config loaded through suffixes is `env > local > none`, meaning that
  * for example app-config.development.yaml has higher priority than `app-config.local.yaml`.