shakapacker 9.0.0.beta.2 → 9.0.0.beta.4

data/package/utils/helpers.js

@@ -25,6 +25,46 @@ const canProcess = (rule, fn) => {
   return null
 }
 
+const validateBabelDependencies = () => {
+  // Only validate core dependencies that are absolutely required
+  // Additional packages like presets are optional and project-specific
+  const coreRequiredPackages = ["@babel/core", "babel-loader"]
+
+  const missingCorePackages = coreRequiredPackages.filter(
+    (pkg) => !moduleExists(pkg)
+  )
+
+  if (missingCorePackages.length > 0) {
+    const installCommand = `npm install --save-dev ${missingCorePackages.join(" ")}`
+
+    // Check for commonly needed packages and suggest them
+    const suggestedPackages = [
+      "@babel/preset-env",
+      "@babel/plugin-transform-runtime",
+      "@babel/runtime"
+    ]
+
+    const missingSuggested = suggestedPackages.filter(
+      (pkg) => !moduleExists(pkg)
+    )
+    let additionalHelp = ""
+
+    if (missingSuggested.length > 0) {
+      additionalHelp =
+        `\n\nYou may also need: ${missingSuggested.join(", ")}\n` +
+        `Install with: npm install --save-dev ${missingSuggested.join(" ")}`
+    }
+
+    throw new Error(
+      `Babel is configured but core packages are missing: ${missingCorePackages.join(", ")}\n\n` +
+        `To fix this, run:\n  ${installCommand}${additionalHelp}\n\n` +
+        `💡 Tip: Consider migrating to SWC for 20x faster compilation:\n` +
+        `   1. Set javascript_transpiler: 'swc' in config/shakapacker.yml\n` +
+        `   2. Run: npm install @swc/core swc-loader`
+    )
+  }
+}
+
 const loaderMatches = (configLoader, loaderToCheck, fn) => {
   if (configLoader !== loaderToCheck) {
     return null
@@ -32,9 +72,33 @@ const loaderMatches = (configLoader, loaderToCheck, fn) => {
 
   const loaderName = `${configLoader}-loader`
 
+  // Special validation for babel to check all dependencies
+  if (configLoader === "babel") {
+    validateBabelDependencies()
+  }
+
   if (!moduleExists(loaderName)) {
+    let installCommand = ""
+    let migrationHelp = ""
+
+    if (configLoader === "babel") {
+      installCommand =
+        "npm install --save-dev babel-loader @babel/core @babel/preset-env @babel/plugin-transform-runtime @babel/runtime"
+      migrationHelp =
+        "\n\n💡 Tip: Consider migrating to SWC for 20x faster compilation:\n" +
+        "   1. Set javascript_transpiler: 'swc' in config/shakapacker.yml\n" +
+        "   2. Run: npm install @swc/core swc-loader"
+    } else if (configLoader === "swc") {
+      installCommand = "npm install --save-dev @swc/core swc-loader"
+      migrationHelp =
+        "\n\n✨ SWC is 20x faster than Babel with zero configuration!"
+    } else if (configLoader === "esbuild") {
+      installCommand = "npm install --save-dev esbuild esbuild-loader"
+    }
+
     throw new Error(
-      `Your Shakapacker config specified using ${configLoader}, but ${loaderName} package is not installed. Please install ${loaderName} first.`
+      `Your Shakapacker config specified using ${configLoader}, but ${loaderName} package is not installed.\n\n` +
+        `To fix this, run:\n  ${installCommand}${migrationHelp}`
     )
   }
 
@@ -56,6 +120,7 @@ module.exports = {
   ensureTrailingSlash,
   canProcess,
   moduleExists,
+  validateBabelDependencies,
   loaderMatches,
   packageFullVersion,
   packageMajorVersion

data/package/utils/validateCssModulesConfig.js

@@ -0,0 +1,91 @@
+/* eslint global-require: 0 */
+const { warn } = require("./debug")
+
+/**
+ * Validates CSS modules configuration and warns about potential issues
+ * with v9 defaults or conflicting settings.
+ */
+const validateCssModulesConfig = (cssLoaderOptions) => {
+  // Skip validation in production by default for performance
+  if (
+    process.env.NODE_ENV === "production" &&
+    process.env.SHAKAPACKER_VALIDATE_CSS_MODULES !== "true"
+  ) {
+    return
+  }
+
+  if (!cssLoaderOptions || !cssLoaderOptions.modules) {
+    return
+  }
+
+  const { modules } = cssLoaderOptions
+
+  // Check for conflicting namedExport and esModule settings
+  if (modules.namedExport === true && modules.esModule === false) {
+    warn(
+      "⚠️  CSS Modules Configuration Warning:\n" +
+        "    namedExport: true with esModule: false may cause issues.\n" +
+        "    Consider setting esModule: true or removing it (defaults to true)."
+    )
+  }
+
+  // Check for v8-style configuration with v9
+  if (modules.namedExport === false) {
+    warn(
+      "ℹ️  CSS Modules Configuration Note:\n" +
+        "    You are using namedExport: false (v8 behavior).\n" +
+        "    Shakapacker v9 defaults to namedExport: true for better tree-shaking.\n" +
+        "    See docs/css-modules-export-mode.md for migration instructions."
+    )
+  }
+
+  // Check for inconsistent exportLocalsConvention with namedExport
+  if (
+    modules.namedExport === true &&
+    modules.exportLocalsConvention === "asIs"
+  ) {
+    warn(
+      "⚠️  CSS Modules Configuration Warning:\n" +
+        "    Using namedExport: true with exportLocalsConvention: 'asIs' may cause issues\n" +
+        "    with kebab-case class names (e.g., 'my-button').\n" +
+        "    Consider using exportLocalsConvention: 'camelCase' (v9 default)."
+    )
+  }
+
+  // Check for deprecated localIdentName pattern
+  if (
+    modules.localIdentName &&
+    modules.localIdentName.includes("[hash:base64]")
+  ) {
+    warn(
+      "⚠️  CSS Modules Configuration Warning:\n" +
+        "    [hash:base64] is deprecated in css-loader v6+.\n" +
+        "    Use [hash] instead for better compatibility."
+    )
+  }
+
+  // Check for potential TypeScript issues
+  if (
+    modules.namedExport === true &&
+    process.env.SHAKAPACKER_ASSET_COMPILER_TYPESCRIPT === "true"
+  ) {
+    warn(
+      "ℹ️  TypeScript CSS Modules Note:\n" +
+        "    With namedExport: true, TypeScript projects should use:\n" +
+        "    import * as styles from './styles.module.css'\n" +
+        "    instead of: import styles from './styles.module.css'\n" +
+        "    See docs/css-modules-export-mode.md for TypeScript setup."
+    )
+  }
+
+  // Check for auto: true with getLocalIdent (potential conflict)
+  if (modules.auto === true && modules.getLocalIdent) {
+    warn(
+      "⚠️  CSS Modules Configuration Warning:\n" +
+        "    Using both 'auto: true' and 'getLocalIdent' may cause conflicts.\n" +
+        "    The 'auto' option determines which files are treated as CSS modules."
+    )
+  }
+}
+
+module.exports = { validateCssModulesConfig }

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakapacker",
-  "version": "9.0.0-beta.2",
+  "version": "9.0.0-beta.4",
   "description": "Use webpack to manage app-like JavaScript modules in Rails",
   "homepage": "https://github.com/shakacode/shakapacker",
   "bugs": {
@@ -39,12 +39,18 @@
   "devDependencies": {
     "@rspack/cli": "^1.4.11",
     "@rspack/core": "^1.4.11",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.5.2",
+    "@types/path-complete-extname": "^1.0.3",
+    "@types/webpack": "^5.28.5",
+    "@types/webpack-dev-server": "^4.7.2",
+    "@types/webpack-merge": "^5.0.0",
     "babel-loader": "^8.2.4",
     "compression-webpack-plugin": "^9.0.0",
     "css-loader": "^7.1.2",
     "esbuild-loader": "^2.18.0",
     "eslint": "^8.0.0",
-    "eslint-config-airbnb": "^19.0.0",
+    "eslint-config-airbnb": "^19.0.4",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-jest": "^27.9.0",
@@ -60,6 +66,7 @@
     "sass-loader": "^16.0.5",
     "swc-loader": "^0.1.15",
     "thenify": "^3.3.1",
+    "typescript": "^5.9.2",
     "webpack": "5.93.0",
     "webpack-assets-manifest": "^5.0.6",
     "webpack-merge": "^5.8.0",

data/test/package/rules/babel.test.js

@@ -11,6 +11,7 @@ jest.mock("../../../package/config", () => {
   const original = jest.requireActual("../../../package/config")
   return {
     ...original,
+    javascript_transpiler: "babel", // Force babel for this test
     additional_paths: [...original.additional_paths, "node_modules/included"]
   }
 })
@@ -32,6 +33,21 @@ const createWebpackConfig = (file, use) => ({
 })
 
 describe("babel", () => {
+  // Mock validateBabelDependencies to avoid actual dependency checking in tests
+  beforeAll(() => {
+    jest.mock("../../../package/utils/helpers", () => {
+      const original = jest.requireActual("../../../package/utils/helpers")
+      return {
+        ...original,
+        validateBabelDependencies: jest.fn() // Mock to do nothing
+      }
+    })
+  })
+
+  afterAll(() => {
+    jest.unmock("../../../package/utils/helpers")
+  })
+
   test("process source path", async () => {
     const normalPath = `${pathToAppJavascript}/a.js`
     const [tracked, loader] = createTrackLoader()

data/tools/README.md

@@ -0,0 +1,124 @@
+# Shakapacker v9 Migration Tools
+
+## CSS Modules Codemod
+
+A jscodeshift codemod to help migrate CSS module imports from v8 to v9 format.
+
+### What it does
+
+#### For JavaScript files (.js, .jsx):
+- Converts `import styles from './styles.module.css'` to `import { className1, className2 } from './styles.module.css'`
+- Automatically detects which CSS classes are used in the file
+- Handles kebab-case to camelCase conversion (e.g., `my-button` → `myButton`)
+- Updates all class references from `styles.className` to `className`
+
+#### For TypeScript files (.ts, .tsx):
+- Converts `import styles from './styles.module.css'` to `import * as styles from './styles.module.css'`
+- Preserves the same usage pattern (`styles.className`)
+- Works around TypeScript's limitation with dynamic named exports
+
+### Installation
+
+```bash
+npm install -g jscodeshift
+```
+
+### Usage
+
+#### Dry run (see what would change):
+```bash
+npx jscodeshift -t tools/css-modules-v9-codemod.js src/ --dry
+```
+
+#### Apply to JavaScript files:
+```bash
+npx jscodeshift -t tools/css-modules-v9-codemod.js src/
+```
+
+#### Apply to TypeScript files:
+```bash
+npx jscodeshift -t tools/css-modules-v9-codemod.js --parser tsx src/
+```
+
+#### Apply to specific file patterns:
+```bash
+# Only .jsx files
+npx jscodeshift -t tools/css-modules-v9-codemod.js src/**/*.jsx
+
+# Only .tsx files
+npx jscodeshift -t tools/css-modules-v9-codemod.js --parser tsx src/**/*.tsx
+```
+
+### Options
+
+- `--dry` - Run without modifying files
+- `--print` - Print the transformed output
+- `--parser tsx` - Use TypeScript parser
+- `--verbose` - Show detailed progress
+
+### Examples
+
+#### Before (JavaScript):
+```javascript
+import styles from './Button.module.css';
+
+function Button() {
+  return (
+    <button className={styles.button}>
+      <span className={styles['button-text']}>Click me</span>
+    </button>
+  );
+}
+```
+
+#### After (JavaScript):
+```javascript
+import { button, buttonText } from './Button.module.css';
+
+function Button() {
+  return (
+    <button className={button}>
+      <span className={buttonText}>Click me</span>
+    </button>
+  );
+}
+```
+
+#### Before (TypeScript):
+```typescript
+import styles from './Button.module.css';
+
+const Button: React.FC = () => {
+  return <button className={styles.button}>Click</button>;
+};
+```
+
+#### After (TypeScript):
+```typescript
+import * as styles from './Button.module.css';
+
+const Button: React.FC = () => {
+  return <button className={styles.button}>Click</button>;
+};
+```
+
+### Notes
+
+1. **Kebab-case conversion**: CSS classes with kebab-case (e.g., `my-button`) are automatically converted to camelCase (`myButton`) for JavaScript files, matching css-loader's `exportLocalsConvention: 'camelCase'` setting.
+
+2. **Unused imports**: The codemod only imports CSS classes that are actually used in JavaScript files. If you pass the entire styles object to a component, it will convert to namespace import for safety.
+
+3. **Manual review recommended**: Always review the changes, especially for complex usage patterns or dynamic class name construction.
+
+4. **Backup your code**: Run the codemod on version-controlled code or create a backup first.
+
+### Troubleshooting
+
+**Issue**: Codemod doesn't detect all CSS class usages
+**Solution**: For dynamic class names or complex patterns, manual migration may be needed.
+
+**Issue**: TypeScript errors after transformation
+**Solution**: Ensure your TypeScript definitions are updated as shown in the [v9 Upgrade Guide](../docs/v9_upgrade.md).
+
+**Issue**: Runtime errors about missing CSS classes
+**Solution**: Check if you have kebab-case class names that need camelCase conversion.

data/tools/css-modules-v9-codemod.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * Shakapacker v9 CSS Modules Codemod
+ *
+ * This codemod helps migrate CSS module imports from v8 (default exports)
+ * to v9 (named exports for JS, namespace imports for TS).
+ *
+ * Usage:
+ *   npx jscodeshift -t tools/css-modules-v9-codemod.js src/
+ *   npx jscodeshift -t tools/css-modules-v9-codemod.js --parser tsx src/ (for TypeScript)
+ *
+ * Options:
+ *   --dry                Run in dry mode (no files modified)
+ *   --print              Print transformed files to stdout
+ *   --parser tsx         Use TypeScript parser
+ */
+
+module.exports = function transformer(fileInfo, api) {
+  const j = api.jscodeshift
+  const root = j(fileInfo.source)
+  let hasChanges = false
+
+  // Detect if this is a TypeScript file
+  const isTypeScript = fileInfo.path.match(/\.tsx?$/)
+
+  // Find all CSS module imports
+  root
+    .find(j.ImportDeclaration, {
+      source: {
+        value: (value) =>
+          value && value.match(/\.module\.(css|scss|sass|less)$/)
+      }
+    })
+    .forEach((path) => {
+      const importDecl = path.node
+
+      // Check if it's a default import (v8 style)
+      const defaultSpecifier = importDecl.specifiers.find(
+        (spec) => spec.type === "ImportDefaultSpecifier"
+      )
+
+      if (!defaultSpecifier) {
+        // Already using named or namespace imports, skip
+        return
+      }
+
+      const defaultImportName = defaultSpecifier.local.name
+
+      if (isTypeScript) {
+        // For TypeScript: Convert to namespace import (import * as styles)
+        const namespaceSpecifier = j.importNamespaceSpecifier(
+          j.identifier(defaultImportName)
+        )
+
+        // Replace the import specifiers
+        importDecl.specifiers = [namespaceSpecifier]
+        hasChanges = true
+      } else {
+        // For JavaScript: Convert to named imports
+        // First, we need to find all usages of the imported object
+        const usages = new Set()
+
+        // Find all member expressions using the imported default
+        root
+          .find(j.MemberExpression, {
+            object: {
+              type: "Identifier",
+              name: defaultImportName
+            }
+          })
+          .forEach((memberPath) => {
+            // Handle both dot notation (styles.className) and bracket notation (styles['class-name'])
+            if (
+              memberPath.node.computed &&
+              memberPath.node.property.type === "Literal"
+            ) {
+              // Computed property access: styles['active-button']
+              const propertyValue = memberPath.node.property.value
+              if (typeof propertyValue === "string") {
+                usages.add(propertyValue)
+              }
+            } else if (
+              !memberPath.node.computed &&
+              memberPath.node.property.type === "Identifier"
+            ) {
+              // Dot notation: styles.activeButton
+              const propertyName = memberPath.node.property.name
+              if (propertyName) {
+                usages.add(propertyName)
+              }
+            }
+          })
+
+        if (usages.size > 0) {
+          // Create named import specifiers
+          const namedSpecifiers = Array.from(usages)
+            .sort()
+            .map((name) => {
+              // Handle kebab-case to camelCase conversion
+              const camelCaseName = name.replace(/-([a-z])/g, (g) =>
+                g[1].toUpperCase()
+              )
+
+              if (camelCaseName !== name) {
+                // If conversion happened, we need to alias it
+                return j.importSpecifier(
+                  j.identifier(camelCaseName),
+                  j.identifier(camelCaseName) // css-loader exports it as camelCase
+                )
+              }
+
+              return j.importSpecifier(j.identifier(name))
+            })
+
+          // Replace the import specifiers
+          importDecl.specifiers = namedSpecifiers
+
+          // Update all usages in the file
+          root
+            .find(j.MemberExpression, {
+              object: {
+                type: "Identifier",
+                name: defaultImportName
+              }
+            })
+            .forEach((memberPath) => {
+              let propertyName
+
+              // Extract property name from both computed and dot notation
+              if (
+                memberPath.node.computed &&
+                memberPath.node.property.type === "Literal"
+              ) {
+                propertyName = memberPath.node.property.value
+              } else if (
+                !memberPath.node.computed &&
+                memberPath.node.property.type === "Identifier"
+              ) {
+                propertyName = memberPath.node.property.name
+              }
+
+              if (propertyName && typeof propertyName === "string") {
+                // Convert kebab-case to camelCase
+                const camelCaseName = propertyName.replace(/-([a-z])/g, (g) =>
+                  g[1].toUpperCase()
+                )
+                // Replace with direct identifier
+                j(memberPath).replaceWith(j.identifier(camelCaseName))
+              }
+            })
+
+          hasChanges = true
+        } else if (usages.size === 0) {
+          // No usages found, might be passed as a whole object
+          // In this case, convert to namespace import for safety
+          const namespaceSpecifier = j.importNamespaceSpecifier(
+            j.identifier(defaultImportName)
+          )
+
+          importDecl.specifiers = [namespaceSpecifier]
+          hasChanges = true
+        }
+      }
+    })
+
+  if (!hasChanges) {
+    return null // No changes made
+  }
+
+  return root.toSource({
+    quote: "single",
+    trailingComma: true,
+    tabWidth: 2
+  })
+}
+
+// Export the parser to use
+module.exports.parser = "tsx"