Fix NODE_ENV defaulting to production breaking dev server (#631) (#632)

Why
Dev server failed to load correct config when NODE_ENV unset.

Summary
NODE_ENV now intelligently defaults based on RAILS_ENV instead of
always defaulting to "production". Matches bin/shakapacker behavior.

Key improvements
- Dev server works out of box without requiring NODE_ENV to be set
- RAILS_ENV=production defaults to NODE_ENV=production (safe)
- All other RAILS_ENV values default to NODE_ENV=development (DX)

Impact
- Existing: Fixes port and 404 errors in development
- New: No migration needed; can remove manual NODE_ENV workarounds

Risks
- Tests relying on implicit production default needed updates (fixed)

Author: justin808

CHANGELOG.md

@@ -9,12 +9,38 @@ This guide outlines new features, breaking changes, and migration steps for upgr
 Shakapacker v9 includes TypeScript definitions for better IDE support and type safety.
 
 - **No breaking changes** - JavaScript configs continue to work
-- **Optional** - Use TypeScript only if you want it  
+- **Optional** - Use TypeScript only if you want it
 - **Type safety** - Catch configuration errors at compile-time
 - **IDE support** - Full autocomplete for all options
 
 See the [TypeScript Documentation](./typescript.md) for usage examples.
 
+### NODE_ENV Default Behavior Fixed
+
+**What changed:** NODE_ENV now intelligently defaults based on RAILS_ENV instead of always defaulting to "production".
+
+**New behavior:**
+
+- When `RAILS_ENV=production` → `NODE_ENV` defaults to `"production"`
+- When `RAILS_ENV=development` or unset → `NODE_ENV` defaults to `"development"`
+- When `RAILS_ENV` is any other value (test, staging, etc.) → `NODE_ENV` defaults to `"development"`
+
+**Benefits:**
+
+- **Dev server "just works"** - No need to explicitly set NODE_ENV when running the development server
+- **Correct configuration loaded** - Development server now properly loads the development configuration from shakapacker.yml
+- **Fixes port issues** - Dev server uses the configured port (e.g., 3035) instead of defaulting to 8080
+- **Fixes 404 errors** - Assets load correctly without requiring manual NODE_ENV configuration
+
+**No action required** - This change improves the default behavior and requires no migration.
+
+**If you previously worked around this bug**, you can now remove these workarounds:
+
+- Remove `NODE_ENV=development` from your `.env`, `.env.development`, or `.env.local` files
+- Remove `NODE_ENV=development` from your `docker-compose.yml` or Dockerfile
+- Remove custom scripts that set NODE_ENV before running the dev server
+- Remove `NODE_ENV=development` from your `bin/dev` or Procfile.dev
+
 ## Breaking Changes
 
 ### 1. CSS Modules Configuration Changed to Named Exports
@@ -25,25 +51,27 @@ See the [TypeScript Documentation](./typescript.md) for usage examples.
 
 **Quick Reference: Configuration Options**
 
-| Configuration | namedExport | exportLocalsConvention | CSS: `.my-button` | Export Available | Works With |
-|---------------|-------------|------------------------|-------------------|------------------|------------|
-| **v9 Default** | `true` | `'camelCaseOnly'` | `.my-button` | `myButton` only | ✅ Named exports |
-| **Alternative** | `true` | `'dashesOnly'` | `.my-button` | `'my-button'` only | ✅ Named exports |
-| **v8 Style** | `false` | `'camelCase'` | `.my-button` | Both `myButton` AND `'my-button'` | ✅ Default export |
-| **❌ Invalid** | `true` | `'camelCase'` | - | - | ❌ Build Error |
+| Configuration   | namedExport | exportLocalsConvention | CSS: `.my-button` | Export Available                  | Works With        |
+| --------------- | ----------- | ---------------------- | ----------------- | --------------------------------- | ----------------- |
+| **v9 Default**  | `true`      | `'camelCaseOnly'`      | `.my-button`      | `myButton` only                   | ✅ Named exports  |
+| **Alternative** | `true`      | `'dashesOnly'`         | `.my-button`      | `'my-button'` only                | ✅ Named exports  |
+| **v8 Style**    | `false`     | `'camelCase'`          | `.my-button`      | Both `myButton` AND `'my-button'` | ✅ Default export |
+| **❌ Invalid**  | `true`      | `'camelCase'`          | -                 | -                                 | ❌ Build Error    |
 
 **JavaScript Projects:**
+
 ```js
 // Before (v8)
-import styles from './Component.module.css';
-<button className={styles.button} />
+import styles from "./Component.module.css"
+;<button className={styles.button} />
 
 // After (v9)
-import { button } from './Component.module.css';
-<button className={button} />
+import { button } from "./Component.module.css"
+;<button className={button} />
 ```
 
 **TypeScript Projects:**
+
 ```typescript
 // Before (v8)
 import styles from './Component.module.css';
@@ -57,6 +85,7 @@ import * as styles from './Component.module.css';
 **Migration Options:**
 
 1. **Update your code** (Recommended):
+
    - JavaScript: Change to named imports (`import { className }`)
    - TypeScript: Change to namespace imports (`import * as styles`)
    - Kebab-case class names are automatically converted to camelCase
@@ -66,6 +95,7 @@ import * as styles from './Component.module.css';
    - This gives you time to migrate gradually
 
 **Benefits of the change:**
+
 - Eliminates webpack/TypeScript warnings
 - Better tree-shaking of unused CSS classes
 - More explicit about which classes are used
@@ -76,15 +106,17 @@ import * as styles from './Component.module.css';
 **What changed:** The configuration option has been renamed to better reflect its purpose.
 
 **Before (v8):**
+
 ```yml
 # config/shakapacker.yml
-webpack_loader: 'babel'
+webpack_loader: "babel"
 ```
 
 **After (v9):**
+
 ```yml
 # config/shakapacker.yml
-javascript_transpiler: 'babel'
+javascript_transpiler: "babel"
 ```
 
 **Note:** The old `webpack_loader` option is deprecated but still supported with a warning.
@@ -96,38 +128,48 @@ javascript_transpiler: 'babel'
 **Why:** SWC is 20x faster than Babel while maintaining compatibility with most JavaScript and TypeScript code.
 
 **Impact on existing projects:**
+
 - Your project will continue using Babel if you already have babel packages in package.json
 - To switch to SWC for better performance, see migration options below
 
 **Impact on new projects:**
+
 - New installations will use SWC by default
 - Babel dependencies won't be installed unless explicitly configured
 
 ### Migration Options
 
 #### Option 1 (Recommended): Switch to SWC
+
 ```yml
 # config/shakapacker.yml
-javascript_transpiler: 'swc'
+javascript_transpiler: "swc"
 ```
+
 Then install SWC:
+
 ```bash
 npm install @swc/core swc-loader
 ```
 
 #### Option 2: Keep using Babel
+
 ```yml
 # config/shakapacker.yml
-javascript_transpiler: 'babel'
+javascript_transpiler: "babel"
 ```
+
 No other changes needed - your existing babel packages will continue to work.
 
 #### Option 3: Use esbuild
+
 ```yml
 # config/shakapacker.yml
-javascript_transpiler: 'esbuild'
+javascript_transpiler: "esbuild"
 ```
+
 Then install esbuild:
+
 ```bash
 npm install esbuild esbuild-loader
 ```
@@ -138,24 +180,27 @@ npm install esbuild esbuild-loader
 
 ```yml
 # config/shakapacker.yml
-assets_bundler: 'rspack'  # or 'webpack' (default)
+assets_bundler: "rspack" # or 'webpack' (default)
 ```
 
 ### 5. All Peer Dependencies Now Optional
 
 **What changed:** All peer dependencies are now marked as optional via `peerDependenciesMeta`.
 
 **Benefits:**
+
 - **No installation warnings** - You won't see peer dependency warnings for packages you don't use
 - **Install only what you need** - Using webpack? Don't install rspack. Using SWC? Don't install Babel.
 - **Clear version constraints** - When you do install a package, version compatibility is still enforced
 
 **What this means for you:**
+
 - **Existing projects:** No changes needed. Your existing dependencies will continue to work.
 - **New projects:** The installer only adds the packages you actually need based on your configuration.
 - **Package manager behavior:** npm, yarn, and pnpm will no longer warn about missing peer dependencies.
 
 **Example:** If you're using SWC with webpack, you only need:
+
 ```json
 {
   "dependencies": {
@@ -168,6 +213,7 @@ assets_bundler: 'rspack'  # or 'webpack' (default)
   }
 }
 ```
+
 You won't get warnings about missing Babel, Rspack, or esbuild packages.
 
 ## Migration Steps
@@ -186,22 +232,22 @@ yarn upgrade shakapacker@^9.0.0
 
 ```js
 // Find imports like this:
-import styles from './styles.module.css';
+import styles from "./styles.module.css"
 
 // Replace with named imports:
-import { className1, className2 } from './styles.module.css';
+import { className1, className2 } from "./styles.module.css"
 ```
 
 #### Update TypeScript definitions:
 
 ```typescript
 // Update your CSS module type definitions
-declare module '*.module.css' {
+declare module "*.module.css" {
   // With namedExport: true, css-loader generates individual named exports
   // TypeScript can't know the exact names at compile time, so we declare
   // a module with any number of string exports
-  const classes: { readonly [key: string]: string };
-  export = classes;
+  const classes: { readonly [key: string]: string }
+  export = classes
   // Note: This allows 'import * as styles' but not 'import styles from'
   // because css-loader with namedExport: true doesn't generate a default export
 }
@@ -213,13 +259,15 @@ v9 automatically converts kebab-case to camelCase with `exportLocalsConvention:
 
 ```css
 /* styles.module.css */
-.my-button { }
-.primary-color { }
+.my-button {
+}
+.primary-color {
+}
 ```
 
 ```js
 // v9 default - camelCase conversion
-import { myButton, primaryColor } from './styles.module.css';
+import { myButton, primaryColor } from "./styles.module.css"
 ```
 
 **Alternative: Keep kebab-case names with 'dashesOnly'**
@@ -256,7 +304,7 @@ If you have `webpack_loader` in your configuration:
 # webpack_loader: 'babel'
 
 # NEW:
-javascript_transpiler: 'babel'
+javascript_transpiler: "babel"
 ```
 
 ### Step 5: Run Tests
@@ -291,6 +339,7 @@ If you see warnings about CSS module exports, ensure you've updated all imports
 ### Build Error: exportLocalsConvention Incompatible with namedExport
 
 If you see this error:
+
 ```
 "exportLocalsConvention" with "camelCase" value is incompatible with "namedExport: true" option
 ```
@@ -312,30 +361,35 @@ If you want to use `'camelCase'` (which exports both original and camelCase vers
 If you experience unexpected peer dependency warnings after upgrading to v9, you may need to clear your package manager's cache and reinstall dependencies. This ensures the new optional peer dependency configuration takes effect properly.
 
 **For npm:**
+
 ```bash
 rm -rf node_modules package-lock.json
 npm install
 ```
 
 **For Yarn:**
+
 ```bash
 rm -rf node_modules yarn.lock
 yarn install
 ```
 
 **For pnpm:**
+
 ```bash
 rm -rf node_modules pnpm-lock.yaml
 pnpm install
 ```
 
 **For Bun:**
+
 ```bash
 rm -rf node_modules bun.lockb
 bun install
 ```
 
 **When is this necessary?**
+
 - If you see peer dependency warnings for packages you don't use (e.g., warnings about Babel when using SWC)
 - If your package manager cached the old dependency resolution from v8
 - After switching transpilers or bundlers (e.g., from Babel to SWC, or webpack to rspack)

docs/v9_upgrade.md

@@ -6,7 +6,7 @@
 module Shakapacker
   extend self
 
-  DEFAULT_ENV = "production".freeze
+  DEFAULT_ENV = "development".freeze
 
   def instance=(instance)
     @instance = instance

lib/shakapacker.rb

@@ -6,21 +6,32 @@ const { isFileNotFoundError } = require("./utils/errorHelpers")
 const { sanitizeEnvValue } = require("./utils/pathValidation")
 
 const NODE_ENVIRONMENTS = ["development", "production", "test"] as const
-const DEFAULT = "production"
 
 // Sanitize environment variables to prevent injection
 const initialRailsEnv = sanitizeEnvValue(process.env.RAILS_ENV)
 const rawNodeEnv = sanitizeEnvValue(process.env.NODE_ENV)
 
+// Default NODE_ENV based on RAILS_ENV to match bin/shakapacker behavior (see lib/shakapacker/runner.rb:27)
+// - RAILS_ENV=production → DEFAULT="production" (safe for production builds)
+// - RAILS_ENV=development, test, staging, or unset → DEFAULT="development" (good DX for dev server)
+// This ensures the dev server works out of the box without requiring NODE_ENV to be set explicitly
+const DEFAULT = initialRailsEnv === "production" ? "production" : "development"
+
 // Validate NODE_ENV strictly
 const nodeEnv =
-  rawNodeEnv && NODE_ENVIRONMENTS.includes(rawNodeEnv as typeof NODE_ENVIRONMENTS[number]) ? rawNodeEnv : DEFAULT
+  rawNodeEnv &&
+  NODE_ENVIRONMENTS.includes(rawNodeEnv as (typeof NODE_ENVIRONMENTS)[number])
+    ? rawNodeEnv
+    : DEFAULT
 
 // Log warning if NODE_ENV was invalid
-if (rawNodeEnv && !NODE_ENVIRONMENTS.includes(rawNodeEnv as typeof NODE_ENVIRONMENTS[number])) {
+if (
+  rawNodeEnv &&
+  !NODE_ENVIRONMENTS.includes(rawNodeEnv as (typeof NODE_ENVIRONMENTS)[number])
+) {
   console.warn(
     `[SHAKAPACKER WARNING] Invalid NODE_ENV value: ${rawNodeEnv}. ` +
-    `Valid values are: ${NODE_ENVIRONMENTS.join(', ')}. Using default: ${DEFAULT}`
+      `Valid values are: ${NODE_ENVIRONMENTS.join(", ")}. Using default: ${DEFAULT}`
   )
 }
 
@@ -42,13 +53,13 @@ try {
     } catch (defaultError) {
       throw new Error(
         `Failed to load Shakapacker configuration.\n` +
-        `Neither user config (${configPath}) nor default config (${defaultConfigPath}) could be loaded.\n\n` +
-        `To fix this issue:\n` +
-        `1. Create a config/shakapacker.yml file in your project\n` +
-        `2. Or set the SHAKAPACKER_CONFIG environment variable to point to your config file\n` +
-        `3. Or reinstall Shakapacker to restore the default configuration:\n` +
-        `   npm install shakapacker --force\n` +
-        `   yarn add shakapacker --force`
+          `Neither user config (${configPath}) nor default config (${defaultConfigPath}) could be loaded.\n\n` +
+          `To fix this issue:\n` +
+          `1. Create a config/shakapacker.yml file in your project\n` +
+          `2. Or set the SHAKAPACKER_CONFIG environment variable to point to your config file\n` +
+          `3. Or reinstall Shakapacker to restore the default configuration:\n` +
+          `   npm install shakapacker --force\n` +
+          `   yarn add shakapacker --force`
       )
     }
   } else {
@@ -61,13 +72,14 @@ const regex = new RegExp(`^(${availableEnvironments})$`, "g")
 
 const runningWebpackDevServer = process.env.WEBPACK_SERVE === "true"
 
-const validatedRailsEnv = initialRailsEnv && initialRailsEnv.match(regex) ? initialRailsEnv : DEFAULT
+const validatedRailsEnv =
+  initialRailsEnv && initialRailsEnv.match(regex) ? initialRailsEnv : DEFAULT
 
 if (initialRailsEnv && validatedRailsEnv !== initialRailsEnv) {
   /* eslint no-console:0 */
   console.warn(
     `[SHAKAPACKER WARNING] Environment '${initialRailsEnv}' not found in the configuration.\n` +
-    `Using '${DEFAULT}' configuration as a fallback.`
+      `Using '${DEFAULT}' configuration as a fallback.`
   )
 }
 

package/env.ts

@@ -429,8 +429,8 @@
       )
     end
 
-    it "#cache_manifest? fall back to 'production' config from bundled file" do
-      expect(config.cache_manifest?).to be true
+    it "#cache_manifest? fall back to 'development' config from bundled file" do
+      expect(config.cache_manifest?).to be false
     end
 
     it "#shakapacker_precompile? use 'staging' config from custom file" do