feat(init): opt yarn projects out of plug'n'play

Author: danielroe

packages/nuxt-cli/src/commands/init.ts

@@ -5,6 +5,7 @@ import type { InstallResult } from '../utils/install'
 import type { TemplateData } from '../utils/starter-templates'
 
 import { existsSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
 import process from 'node:process'
 import { Writable } from 'node:stream'
 
@@ -85,6 +86,27 @@ async function reportMissingNonInteractiveArgs<T extends ArgsDef>(
     .join(', ')}`)
 }
 
+const YARN_NODE_LINKER = `# Nuxt cannot resolve its modules under Yarn's default Plug'n'Play linker.
+# See https://github.com/nuxt/nuxt/issues/26750
+nodeLinker: node-modules
+`
+
+/**
+ * Opt a scaffolded project out of Yarn's Plug'n'Play linker, under which
+ * `nuxt prepare` cannot resolve `@nuxt/kit` and the project will not build.
+ *
+ * Templates that ship any Yarn configuration of their own are left alone, so a
+ * template can still choose Plug'n'Play. Yarn 1 ignores `.yarnrc.yml`, so
+ * writing it there is harmless.
+ */
+export async function useYarnNodeModulesLinker(dir: string): Promise<boolean> {
+  if (existsSync(join(dir, '.yarnrc.yml')) || existsSync(join(dir, '.yarnrc'))) {
+    return false
+  }
+  await writeFile(join(dir, '.yarnrc.yml'), YARN_NODE_LINKER, 'utf8')
+  return true
+}
+
 /**
  * Commands to print in the closing 'Next steps' box, in the order to run them.
  *
@@ -505,6 +527,10 @@ export default defineCommand({
       selectedPackageManager = result
     }
 
+    if (selectedPackageManager === 'yarn' && await useYarnNodeModulesLinker(template.dir)) {
+      logger.info(`Created ${colors.cyan('.yarnrc.yml')} with ${colors.cyan('nodeLinker: node-modules')}, as Nuxt cannot resolve its modules under Yarn's Plug'n'Play linker.`)
+    }
+
     // Determine if we should init git
     let gitInit: boolean | undefined = ctx.args.gitInit === 'false' as unknown ? false : ctx.args.gitInit
     if (gitInit === undefined) {

packages/nuxt-cli/test/unit/commands/init.spec.ts

@@ -1,9 +1,39 @@
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
-import { detectTemplatePackageManager, getNextSteps } from '../../../src/commands/init'
+import { detectTemplatePackageManager, getNextSteps, useYarnNodeModulesLinker } from '../../../src/commands/init'
+
+describe('useYarnNodeModulesLinker', () => {
+  let dir: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'nuxt-init-yarn-'))
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('should opt a fresh project out of plug\'n\'play', async () => {
+    expect(await useYarnNodeModulesLinker(dir)).toBe(true)
+    expect(await readFile(join(dir, '.yarnrc.yml'), 'utf8')).toContain('nodeLinker: node-modules')
+  })
+
+  it('should not overwrite yarn configuration from a template', async () => {
+    await writeFile(join(dir, '.yarnrc.yml'), 'nodeLinker: pnp\n')
+    expect(await useYarnNodeModulesLinker(dir)).toBe(false)
+    expect(await readFile(join(dir, '.yarnrc.yml'), 'utf8')).toBe('nodeLinker: pnp\n')
+  })
+
+  it('should not add yarn 2+ configuration alongside a yarn 1 config', async () => {
+    await writeFile(join(dir, '.yarnrc'), 'registry "https://example.com"\n')
+    expect(await useYarnNodeModulesLinker(dir)).toBe(false)
+    expect(existsSync(join(dir, '.yarnrc.yml'))).toBe(false)
+  })
+})
 
 describe('getNextSteps', () => {
   const base = { shell: false, recoveryCommands: [] as string[], packageManager: 'npm' as const }