Merge pull request #3208 from pierreb-devkit/docs/downstream-config-naming

docs(config): document downstream naming convention

Author: PierreBrisorgueil

MIGRATIONS.md

@@ -15,6 +15,8 @@ The monolithic `config/defaults/development.js` has been split into per-module c
 - **Updated**: `config/index.js` now globs module configs and merges them in layers
 - **Standalone env files**: `config.production.js` and `config.test.js` no longer import `development.js` — they export only their overrides
 - **Assets glob**: `config/assets.js` changed from `modules/*/config/*.js` to `modules/*/config/*.config.js` (excludes data config files, still matches init modules like `users.config.js`)
+- **Template**: `config/defaults/config.myproject.js` added as a starting point for downstream projects
+- **Startup warning**: the loader now warns when `NODE_ENV` is non-standard and no matching config files are found
 
 ### New file layout
 
@@ -51,6 +53,10 @@ Create `NODE_ENV=staging` by adding any of:
 
 No file is required — only modules that define a `config.<env>.js` will be overridden.
 
+### Downstream project config files
+
+Files must be named `config.{projectname}.js` — files without the `config.` prefix are silently ignored. A template is provided at `config/defaults/config.myproject.js`.
+
 ### Steps for downstream projects
 
 1. If you have **customized** `config/defaults/development.js`:
@@ -64,8 +70,9 @@ No file is required — only modules that define a `config.<env>.js` will be ove
    - Remove the `import ... from './development.js'` and `merge()` wrapper — just export the override object directly
    - If your test overrides contain module-specific keys (e.g. `uploads`), move them to `modules/<name>/config/config.test.js`
 3. If you have **custom init modules** matching `modules/*/config/*.js` that are NOT named `*.config.js`, rename them to follow the `*.config.js` convention (the assets glob has changed).
-4. If you have **not customized** any config files, the merge will apply cleanly.
-5. Run `npm run lint && npm test` to confirm everything works.
+4. Rename any `{projectname}.js` config files to `config.{projectname}.js` (both in `config/defaults/` and `modules/*/config/`)
+5. If you have **not customized** any config files, the merge will apply cleanly.
+6. Run `npm run lint && npm test` to confirm everything works.
 
 ---
 

README.md

@@ -156,6 +156,20 @@ DEVKIT_NODE_app_title='my app'               # sets config.app.title
 DEVKIT_NODE_db_uri='mongodb://...'           # sets config.db.uri
 ```
 
+### Downstream projects
+
+When running a downstream project that clones this stack, set `NODE_ENV` to the project name and create matching config files:
+
+```text
+config/defaults/
+  config.myproject.js            ← global project overrides (optional)
+
+modules/<name>/config/
+  config.myproject.js            ← module project overrides (optional)
+```
+
+The loader discovers files named `config.${NODE_ENV}.js` — files without the `config.` prefix are ignored.
+
 ## :whale: Docker
 
 ```bash

config/defaults/config.myproject.js

@@ -0,0 +1,17 @@
+/**
+ * Downstream project config template.
+ *
+ * 1. Copy this file and rename it to config.{yourproject}.js
+ * 2. Set NODE_ENV={yourproject} when running the app
+ * 3. Override only the keys you need — development defaults are used for everything else
+ *
+ * @example NODE_ENV=myproject npm start
+ */
+export default {
+  // app: {
+  //   title: 'My Project',
+  // },
+  // db: {
+  //   uri: 'mongodb://localhost/MyProjectDev',
+  // },
+};

config/index.js

@@ -10,6 +10,8 @@ import { pathToFileURL } from 'url';
 import assets from './assets.js';
 import configHelper from '../lib/helpers/config.js';
 
+const STANDARD_ENVS = new Set(['development', 'production', 'test']);
+
 /**
  * Deep merge two objects, replacing arrays instead of merging by index.
  * @param {Object} target - Base object
@@ -91,15 +93,25 @@ const initGlobalConfig = async () => {
   // Layer 3 & 4: environment overrides (only if not development)
   if (env !== 'development') {
     // Layer 3: module env overrides
-    const moduleEnvConfigs = await loadModuleConfigs(`modules/*/config/config.${env}.js`);
+    const moduleEnvPattern = `modules/*/config/config.${env}.js`;
+    const moduleEnvConfigs = await loadModuleConfigs(moduleEnvPattern);
+    const hasModuleEnvConfigs = (await configHelper.getGlobbedPaths(moduleEnvPattern)).length > 0;
     config = deepMerge(config, moduleEnvConfigs);
 
     // Layer 4: global env override
     const globalEnvPath = path.join(process.cwd(), 'config', 'defaults', `config.${env}.js`);
-    if (fs.existsSync(globalEnvPath)) {
+    const hasGlobalEnvConfig = fs.existsSync(globalEnvPath);
+    if (hasGlobalEnvConfig) {
       const globalEnv = await loadConfigFile(globalEnvPath);
       config = deepMerge(config, globalEnv);
     }
+
+    // Warn when a non-standard NODE_ENV has no matching config files
+    if (!STANDARD_ENVS.has(env) && !hasModuleEnvConfigs && !hasGlobalEnvConfig) {
+      console.warn(
+        chalk.yellow(`+ Warning: NODE_ENV="${env}" but no config.${env}.js files found — using development defaults. Downstream projects should create config.${env}.js files (see README).`),
+      );
+    }
   }
 
   // Layer 5: DEVKIT_NODE_* env vars (final override)