Throw error <a> child in <Link>

errors/manifest.json

@@ -694,6 +694,10 @@
           "title": "nested-styled-jsx-tags",
           "path": "/errors/nested-styled-jsx-tags.md"
         },
+        {
+          "title": "new-link-a-tag",
+          "path": "/errors/new-link-a-tag.md"
+        },
         {
           "title": "returning-response-body-in-middleware",
           "path": "/errors/returning-response-body-in-middleware.md"

errors/new-link-a-tag.md

@@ -0,0 +1,21 @@
+# Invalid <Link> with <a> child
+
+#### Why This Error Occurred
+
+Starting with Next.js 13, `<Link>` renders as `<a>`, so attempting to use `<a>` as a child is invalid.
+
+#### Possible Ways to Fix It
+
+Run the `new-link` codemod to automatically upgrade previous versions of Next.js to the new `<Link>` usage:
+
+```sh
+npx @next/codemod new-link .
+```
+
+This will change `<Link><a id="link">Home<a></Link>` to `<Link id="link">Home</Link>`.
+
+Alternatively, you can add the `legacyBehavior` prop `<Link legacyBehavior><a id="link">Home<a></Link>`.
+
+### Useful Links
+
+- [next/link](https://nextjs.org/docs/api-reference/next/link)

packages/next/client/link.tsx

@@ -408,6 +408,14 @@ const Link = React.forwardRef<HTMLAnchorElement, LinkPropsReal>(
       } else {
         child = React.Children.only(children)
       }
+    } else {
+      if (process.env.NODE_ENV === 'development') {
+        if ((children as any)?.type === 'a') {
+          throw new Error(
+            'Invalid <Link> with <a> child. Please remove <a> or use <Link legacyBehavior>.\nLearn more: https://nextjs.org/docs/messages/new-link-a-tag'
+          )
+        }
+      }
     }
 
     const childRef: any = legacyBehavior

test/e2e/new-link-behavior/child-a-tag-error.test.ts

@@ -0,0 +1,42 @@
+import { createNext, FileRef } from 'e2e-utils'
+import { getRedboxSource, hasRedbox } from 'next-test-utils'
+import { NextInstance } from 'test/lib/next-modes/base'
+import webdriver from 'next-webdriver'
+import path from 'path'
+
+const appDir = path.join(__dirname, 'child-a-tag-error')
+
+describe('New Link Behavior with <a> child', () => {
+  let next: NextInstance
+
+  beforeAll(async () => {
+    next = await createNext({
+      files: {
+        pages: new FileRef(path.join(appDir, 'pages')),
+        'next.config.js': new FileRef(path.join(appDir, 'next.config.js')),
+      },
+      dependencies: {
+        next: 'latest',
+        react: 'latest',
+        'react-dom': 'latest',
+      },
+    })
+  })
+  afterAll(() => next.destroy())
+
+  it('should throw error with <a> child', async () => {
+    const browser = await webdriver(next.url, `/`)
+    const link = await browser.elementsByCss('a[href="/about"]')
+    const msg =
+      'Error: Invalid <Link> with <a> child. Please remove <a> or use <Link legacyBehavior>'
+
+    if ((global as any).isDev) {
+      expect(next.cliOutput).toContain(msg)
+      expect(await hasRedbox(browser, true)).toBe(true)
+      expect(await getRedboxSource(browser)).toContain(msg)
+      expect(link).not.toBeDefined()
+    } else {
+      expect(link).toBeDefined()
+    }
+  })
+})

test/e2e/new-link-behavior/child-a-tag-error/next.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  reactStrictMode: true,
+}

test/e2e/new-link-behavior/child-a-tag-error/pages/about.js

@@ -0,0 +1,12 @@
+import Link from 'next/link'
+
+export default function Page() {
+  return (
+    <>
+      <h1>About Page</h1>
+      <Link href="/">
+        <a>Home</a>
+      </Link>
+    </>
+  )
+}

test/e2e/new-link-behavior/child-a-tag-error/pages/index.js

@@ -0,0 +1,12 @@
+import Link from 'next/link'
+
+export default function Page() {
+  return (
+    <>
+      <h1>Home Page</h1>
+      <Link href="/about">
+        <a>About</a>
+      </Link>
+    </>
+  )
+}