Fixes #7951: prevent remix.init errors when init script is an ES6 module, update docs to clarify init script requirements

contributors.yml

@@ -323,6 +323,7 @@
 - lensbart
 - leo
 - leon
+- leothorp
 - leovander
 - levippaul
 - LewisArdern

docs/guides/templates.md

@@ -136,7 +136,27 @@ This allows you to not have to regularly update your template to the latest vers
 
 If the template has a `remix.init/index.js` file at the root then that file will be executed after the project has been generated and dependencies have been installed. This gives you a chance to do anything you'd like as part of the initialization of your template. For example, in the blues stack, the `app` property has to be globally unique, so we use the `remix.init/index.js` file to change it to the name of the directory that was created for the project + a couple random characters.
 
-You could even use `remix.init/index.js` to ask further questions to the developer for additional configuration (using something like [inquirer][inquirer]). Sometimes, you'll need dependencies installed to do this, but those deps are only useful during initialization. In that case, you can also create a `remix.init/package.json` with dependencies and the Remix CLI will install those before running your script.
+The `remix.init/index.js` file can contain code to be executed immediately:
+
+```javascript
+console.log('initializing project');
+// further initialization code here
+```
+
+Or can contain a default export of a function that will be invoked. In that case, your init function will be passed the user's selected package manager and the root directory of their project:
+
+```javascript
+export default ({
+    packageManager, // "npm" | "pnpm" | "yarn" | "bun"
+    rootDirectory:  // "path/to/project/root"
+
+}) => {
+    console.log('initializing project');
+    // initialization code here
+};
+```
+
+You could even use `remix.init/index.js` to ask further questions to the developer for additional configuration (using something like [inquirer][inquirer]). Sometimes, you'll need dependencies installed to do this, but those deps are only useful during initialization. In that case, you can also create a `remix.init/package.json` with dependencies and the Remix CLI will install those before running your script. Note: if you wish for your init script to be a commonjs module, and the top-level module of your project is defined as an ES6 module, `remix.init/package.json` will be required.
 
 After the init script has been run, the `remix.init` folder gets deleted, so you don't need to worry about it cluttering up the finished codebase.
 

packages/remix-dev/__tests__/fixtures/es6-remix-init/package.json

@@ -0,0 +1,11 @@
+{
+    "name": "remix-init-as-es6-module-test",
+    "private": true,
+    "type": "module",
+    "scripts": {
+      "remix-init": "remix init"
+    },
+    "devDependencies": {
+      "@remix-run/dev": "latest"
+    }
+  }

packages/remix-dev/__tests__/fixtures/es6-remix-init/remix.init/index.js

@@ -0,0 +1,8 @@
+import fs from "node:fs";
+import path from "node:path";
+export default ({rootDirectory}) => {
+  fs.writeFileSync(
+    path.join(rootDirectory, "es6-remix-init-test.txt"),
+    "added via es6 remix.init"
+  );
+}

packages/remix-dev/__tests__/fixtures/no-export-remix-init/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "no-export-remix-init-test",
+  "private": true,
+  "main": "remix.int/index.js"
+}

packages/remix-dev/__tests__/fixtures/no-export-remix-init/remix.init/index.js

@@ -0,0 +1,6 @@
+const fs = require("node:fs");
+
+fs.writeFileSync(
+  "./no-export-remix-init.txt",
+  "added via remix.init with no export"
+);

packages/remix-dev/__tests__/init-test.ts

@@ -2,6 +2,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import fse from "fs-extra";
 import stripAnsi from "strip-ansi";
+import { execSync } from "node:child_process";
 
 import { run } from "../cli/run";
 
@@ -31,6 +32,31 @@ jest.mock("child_process", () => {
   };
 });
 
+// Copy over the current build of @remix-run/dev and execute remix init from the node_modules dir there.
+// Certain bugs only manifest when using this approach.
+const execRemixInitInProject = (projectDir: string) => {
+  execSync(`npm install`, {
+    stdio: "pipe",
+  });
+
+  // overwrite installed @remix-run/dev with the one we just built
+  fse.copySync(
+    path.join(
+      __dirname,
+      "../../../",
+      "build",
+      "node_modules",
+      "@remix-run/dev"
+    ),
+    path.join(projectDir, "node_modules", "@remix-run/dev")
+  );
+
+  fse.chmodSync(path.join(projectDir, "node_modules", ".bin/remix"), 0o755);
+  execSync(`npm run remix-init`, {
+    stdio: "pipe",
+  });
+};
+
 const TEMP_DIR = path.join(
   fse.realpathSync(os.tmpdir()),
   `remix-tests-${Math.random().toString(32).slice(2)}`
@@ -50,6 +76,10 @@ let originalLog = console.log;
 let originalWarn = console.warn;
 let originalError = console.error;
 
+const convertLogToOutputLine = (messageString: string) => {
+  return "\n" + stripAnsi(messageString).replace(TEMP_DIR, "<TEMP_DIR>");
+};
+
 beforeEach(async () => {
   output = "";
   function hijackLog(message: unknown = "", ...rest: Array<unknown>) {
@@ -58,14 +88,15 @@ beforeEach(async () => {
     if (typeof message === "string" && message.startsWith("debug:")) {
       return originalLog(message, ...rest);
     }
+
     let messageString =
       typeof message === "string" ? message : JSON.stringify(message, null, 2);
     if (rest[0]) {
       throw new Error(
         "Our tests are not set up to handle multiple arguments to console.log."
       );
     }
-    output += "\n" + stripAnsi(messageString).replace(TEMP_DIR, "<TEMP_DIR>");
+    output += convertLogToOutputLine(messageString);
   }
   console.log = hijackLog;
   console.warn = hijackLog;
@@ -130,6 +161,41 @@ describe("the init command", () => {
     expect(fse.existsSync(path.join(projectDir, "remix.init"))).toBeTruthy();
   });
 
+  it("succeeds for a remix.init script that doesn't default export a function", async () => {
+    let projectDir = await getProjectDir("remix-init-manual-no-export");
+
+    fse.copySync(
+      path.join(__dirname, "fixtures", "no-export-remix-init"),
+      projectDir
+    );
+    process.chdir(projectDir);
+    await run(["init"]);
+
+    expect(
+      fse.existsSync(path.join(projectDir, "no-export-remix-init.txt"))
+    ).toBeTruthy();
+
+    // expect(output).toBe(convertLogToOutputLine("exportless commonjs remix init with ES6 parent module succeeded"));
+    expect(fse.existsSync(path.join(projectDir, "remix.init"))).toBeFalsy();
+  });
+
+  it("succeeds for remix.init defined as an ES6 module", async () => {
+    let projectDir = await getProjectDir("remix-init-manual-es6");
+
+    fse.copySync(
+      path.join(__dirname, "fixtures", "es6-remix-init"),
+      projectDir
+    );
+    process.chdir(projectDir);
+    execRemixInitInProject(projectDir);
+
+    expect(output).toBe("");
+    expect(
+      fse.existsSync(path.join(projectDir, "es6-remix-init-test.txt"))
+    ).toBeTruthy();
+    expect(fse.existsSync(path.join(projectDir, "remix.init"))).toBeFalsy();
+  });
+
   it("throws an error when invalid remix.init script when manually ran", async () => {
     let projectDir = await getProjectDir("invalid-remix-init-manual");
 

packages/remix-dev/cli/commands.ts

@@ -44,12 +44,15 @@ export async function init(
     });
   }
 
-  let initFn = require(initScript);
+  let initFn = await import(initScript);
+
   if (typeof initFn !== "function" && initFn.default) {
     initFn = initFn.default;
   }
   try {
-    await initFn({ packageManager, rootDirectory: projectDir });
+    if (typeof initFn === "function") {
+      await initFn({ packageManager, rootDirectory: projectDir });
+    }
 
     if (deleteScript) {
       await fse.remove(initScriptDir);

packages/remix-dev/cli/run.ts

@@ -157,7 +157,7 @@ export async function run(argv: string[] = process.argv.slice(2)) {
   }
 
   let command = input[0];
-
+  
   // Note: Keep each case in this switch statement small.
   switch (command) {
     case "init":