Unverified Commit b9ec2e4f authored by Jude Gao's avatar Jude Gao Committed by GitHub

[AI] Ship bundled docs in next and generate AGENTS.md in create-next-app (#89850)

AI coding agents often rely on outdated training data when working with
Next.js projects, leading to hallucinated APIs and deprecated patterns.
This PR addresses that by shipping version-matched documentation inside
the `next` npm package and generating agent instruction files during
`create-next-app`.

During `next` build, a new `copy_docs` task copies `docs/` from the repo
root into `dist/docs/`. Since `"dist"` is already in the package's
`files` array, the docs are automatically published at
`node_modules/next/dist/docs/`.

`create-next-app` gains a new `--agents-md` / `--no-agents-md` flag
(defaults to `true`). When enabled it writes two files:

- `AGENTS.md` — instructs agents to read `node_modules/next/dist/docs/`
instead of relying on training data
- `CLAUDE.md` — uses `@AGENTS.md` import syntax for Claude Code

The option appears in the recommended defaults display and is prompted
during the customize flow. Existing tests are updated with
`--no-agents-md` to avoid the new prompt.
parent c49cc9fa
......@@ -17,6 +17,7 @@ import { install } from './helpers/install'
import { isFolderEmpty } from './helpers/is-folder-empty'
import { getOnline } from './helpers/is-online'
import { isWriteable } from './helpers/is-writeable'
import { generateAgentFiles } from './helpers/generate-agent-files'
import { runTypegen } from './helpers/typegen'
import type { Bundler, TemplateMode, TemplateType } from './templates'
......@@ -42,6 +43,7 @@ export async function createApp({
bundler,
disableGit,
reactCompiler,
agentsMd,
}: {
appPath: string
packageManager: PackageManager
......@@ -60,6 +62,7 @@ export async function createApp({
bundler: Bundler
disableGit?: boolean
reactCompiler: boolean
agentsMd: boolean
}): Promise<void> {
let repoInfo: RepoInfo | undefined
const mode: TemplateMode = typescript ? 'ts' : 'js'
......@@ -255,6 +258,10 @@ export async function createApp({
})
}
if (agentsMd) {
generateAgentFiles(root)
}
if (disableGit) {
console.log('Skipping git initialization.')
console.log()
......
import fs from 'fs'
import path from 'path'
/**
* Generate AGENTS.md and CLAUDE.md in the project root.
* AGENTS.md contains the instructions, CLAUDE.md references it using @ syntax.
*/
export function generateAgentFiles(root: string): void {
const agentsMdContent = `<!-- BEGIN:nextjs-agent-rules -->
# Next.js: ALWAYS read docs before coding
Before any Next.js work, find and read the relevant doc in \`node_modules/next/dist/docs/\`. Your training data is outdated — the docs are the source of truth.
<!-- END:nextjs-agent-rules -->
`
const claudeMdContent = `@AGENTS.md
`
const agentsMdPath = path.join(root, 'AGENTS.md')
const claudeMdPath = path.join(root, 'CLAUDE.md')
fs.writeFileSync(agentsMdPath, agentsMdContent, 'utf-8')
fs.writeFileSync(claudeMdPath, claudeMdContent, 'utf-8')
}
......@@ -106,6 +106,10 @@ const program = new Command(packageJson.name)
--example-path foo/bar
`
)
.option(
'--agents-md',
'Include AGENTS.md to guide coding agents to write up-to-date Next.js code. (default)'
)
.option('--disable-git', `Skip initializing a git repository.`)
.action((name) => {
// Commander does not implicitly support negated options. When they are used
......@@ -241,6 +245,7 @@ async function run(): Promise<void> {
empty: false,
disableGit: false,
reactCompiler: false,
agentsMd: true,
}
type DisplayConfigItem = {
......@@ -258,6 +263,7 @@ async function run(): Promise<void> {
{ key: 'tailwind', values: { true: 'Tailwind CSS' } },
{ key: 'srcDir', values: { true: 'src/ dir' } },
{ key: 'app', values: { true: 'App Router', false: 'Pages Router' } },
{ key: 'agentsMd', values: { true: 'AGENTS.md' } },
]
// Helper to format settings for display based on displayConfig
......@@ -586,6 +592,34 @@ async function run(): Promise<void> {
}
}
}
if (args.includes('--no-agents-md')) {
opts.agentsMd = false
} else if (!opts.agentsMd) {
if (skipPrompt) {
opts.agentsMd = getPrefOrDefault('agentsMd')
} else {
const { agentsMd } = await prompts(
{
type: 'toggle',
name: 'agentsMd',
message:
'Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code?',
initial: getPrefOrDefault('agentsMd'),
active: 'Yes',
inactive: 'No',
},
{
onCancel: () => {
console.error('Exiting.')
process.exit(1)
},
}
)
opts.agentsMd = Boolean(agentsMd)
preferences.agentsMd = Boolean(agentsMd)
}
}
}
const bundler: Bundler = opts.rspack ? Bundler.Rspack : Bundler.Turbopack
......@@ -609,6 +643,7 @@ async function run(): Promise<void> {
bundler,
disableGit: opts.disableGit,
reactCompiler: opts.reactCompiler,
agentsMd: opts.agentsMd,
})
} catch (reason) {
if (!(reason instanceof DownloadError)) {
......@@ -643,6 +678,7 @@ async function run(): Promise<void> {
bundler,
disableGit: opts.disableGit,
reactCompiler: opts.reactCompiler,
agentsMd: opts.agentsMd,
})
}
conf.set('preferences', preferences)
......
......@@ -31,6 +31,12 @@ export async function copy_regenerator_runtime(task, opts) {
.target('src/compiled/regenerator-runtime')
}
export async function copy_docs(task, opts) {
// Copy documentation from repo root into the package
const docsSource = join(__dirname, '../../docs')
await task.source(join(docsSource, '**/*')).target('dist/docs')
}
export async function copy_styled_jsx_assets(task, opts) {
// we copy the styled-jsx types so that we can reference them
// in the next-env.d.ts file so it doesn't matter if the styled-jsx
......@@ -2188,7 +2194,7 @@ export async function ncc_safe_stable_stringify(task, opts) {
export async function precompile(task, opts) {
await task.parallel(
['browser_polyfills', 'copy_ncced', 'copy_styled_jsx_assets'],
['browser_polyfills', 'copy_ncced', 'copy_styled_jsx_assets', 'copy_docs'],
opts
)
}
......
......@@ -31,6 +31,7 @@ describe('create-next-app Biome configuration', () => {
'--app',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
'--skip-install',
],
nextTgzFilename,
......@@ -59,6 +60,7 @@ describe('create-next-app Biome configuration', () => {
'--app',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{ cwd }
......@@ -95,6 +97,7 @@ describe('create-next-app Biome configuration', () => {
'--app',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{ cwd }
......@@ -131,6 +134,7 @@ describe('create-next-app Biome configuration', () => {
'--app',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{ cwd }
......@@ -167,6 +171,7 @@ describe('create-next-app Biome configuration', () => {
'--app',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{ cwd }
......
......@@ -29,6 +29,7 @@ describe('create-next-app ESLint configuration', () => {
'--no-tailwind',
'--no-src-dir',
'--no-react-compiler',
'--no-agents-md',
'--app',
'--no-import-alias',
'--skip-install',
......@@ -76,6 +77,7 @@ describe('create-next-app ESLint configuration', () => {
'--no-tailwind',
'--no-src-dir',
'--no-react-compiler',
'--no-agents-md',
'--app',
'--no-import-alias',
'--skip-install',
......
......@@ -39,6 +39,7 @@ describe('create-next-app', () => {
'--no-src-dir',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -81,6 +82,7 @@ describe('create-next-app', () => {
'--no-src-dir',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -98,6 +100,70 @@ describe('create-next-app', () => {
}
})
})
it('should create AGENTS.md and CLAUDE.md with --agents-md flag', async () => {
await useTempDir(async (cwd) => {
const projectName = 'with-agents-md'
const res = await run(
[
projectName,
'--ts',
'--app',
'--no-linter',
'--no-tailwind',
'--no-src-dir',
'--no-import-alias',
'--no-react-compiler',
'--agents-md',
'--skip-install',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
{
cwd,
}
)
expect(res.exitCode).toBe(0)
projectFilesShouldExist({
cwd,
projectName,
files: ['AGENTS.md', 'CLAUDE.md'],
})
})
})
it('should not create AGENTS.md and CLAUDE.md with --no-agents-md flag', async () => {
await useTempDir(async (cwd) => {
const projectName = 'without-agents-md'
const res = await run(
[
projectName,
'--ts',
'--app',
'--no-linter',
'--no-tailwind',
'--no-src-dir',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
'--skip-install',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
{
cwd,
}
)
expect(res.exitCode).toBe(0)
projectFilesShouldNotExist({
cwd,
projectName,
files: ['AGENTS.md', 'CLAUDE.md'],
})
})
})
it('should not install dependencies if --skip-install', async () => {
await useTempDir(async (cwd) => {
const projectName = 'empty-dir'
......@@ -113,6 +179,7 @@ describe('create-next-app', () => {
'--no-import-alias',
'--skip-install',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......
......@@ -49,6 +49,7 @@ describe('create-next-app with package manager bun', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{
......@@ -78,6 +79,7 @@ describe('create-next-app with package manager bun', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{
......
......@@ -38,6 +38,7 @@ describe('create-next-app with package manager npm', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{
......@@ -67,6 +68,7 @@ describe('create-next-app with package manager npm', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{
......
......@@ -39,6 +39,7 @@ describe('create-next-app with package manager pnpm', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{
......@@ -68,6 +69,7 @@ describe('create-next-app with package manager pnpm', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{
......@@ -102,6 +104,7 @@ describe('create-next-app with package manager pnpm', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
'--skip-install',
],
nextTgzFilename,
......@@ -133,6 +136,7 @@ describe('create-next-app with package manager pnpm', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
'--skip-install',
],
nextTgzFilename,
......
......@@ -46,6 +46,7 @@ describe('create-next-app with package manager yarn', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{
......@@ -75,6 +76,7 @@ describe('create-next-app with package manager yarn', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
nextTgzFilename,
{
......
......@@ -29,6 +29,7 @@ describe('create-next-app prompts', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
{
cwd,
......@@ -68,6 +69,7 @@ describe('create-next-app prompts', () => {
'--no-src-dir',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
{
cwd,
......@@ -104,6 +106,7 @@ describe('create-next-app prompts', () => {
'--no-src-dir',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
],
{
cwd,
......@@ -140,6 +143,7 @@ describe('create-next-app prompts', () => {
'--no-tailwind',
'--no-src-dir',
'--no-react-compiler',
'--no-agents-md',
],
{
cwd,
......@@ -197,6 +201,8 @@ describe('create-next-app prompts', () => {
'package.json',
'postcss.config.mjs',
'tsconfig.json',
'AGENTS.md',
'CLAUDE.md',
],
})
resolve()
......@@ -238,6 +244,8 @@ describe('create-next-app prompts', () => {
'package.json',
'postcss.config.mjs', // tailwind
'tsconfig.json', // typescript
'AGENTS.md', // agent files
'CLAUDE.md',
],
})
resolve()
......
......@@ -67,6 +67,7 @@ describe('create-next-app --api (Headless App)', () => {
'--api',
'--no-src-dir',
'--no-import-alias',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -99,6 +100,7 @@ describe('create-next-app --api (Headless App)', () => {
'--api',
'--no-src-dir',
'--no-import-alias',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -128,6 +130,7 @@ describe('create-next-app --api (Headless App)', () => {
'--api',
'--src-dir',
'--no-import-alias',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......
......@@ -34,6 +34,7 @@ describe('create-next-app --app (App Router)', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -64,6 +65,7 @@ describe('create-next-app --app (App Router)', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -92,6 +94,7 @@ describe('create-next-app --app (App Router)', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -129,6 +132,7 @@ describe('create-next-app --app (App Router)', () => {
'--tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -166,6 +170,7 @@ describe('create-next-app --app (App Router)', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -205,6 +210,7 @@ describe('create-next-app --app (App Router)', () => {
'--empty',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......
......@@ -35,8 +35,8 @@ describe.each(['app', 'pages'] as const)(
// srcDir and reactCompiler don't interact so we're testing them together
// instead of all permutations.
srcDirAndCompiler: [
'--src-dir --react-compiler',
'--no-src-dir --no-react-compiler',
'--src-dir --react-compiler --no-agents-md',
'--no-src-dir --no-react-compiler --no-agents-md',
],
tailwind: ['--tailwind', '--no-tailwind'],
......
......@@ -34,6 +34,7 @@ describe('create-next-app --no-app (Pages Router)', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -69,6 +70,7 @@ describe('create-next-app --no-app (Pages Router)', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -101,6 +103,7 @@ describe('create-next-app --no-app (Pages Router)', () => {
'--no-tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -137,6 +140,7 @@ describe('create-next-app --no-app (Pages Router)', () => {
'--tailwind',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -175,6 +179,7 @@ describe('create-next-app --no-app (Pages Router)', () => {
'--empty',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......@@ -215,6 +220,7 @@ describe('create-next-app --no-app (Pages Router)', () => {
'--empty',
'--no-import-alias',
'--no-react-compiler',
'--no-agents-md',
...(process.env.NEXT_RSPACK ? ['--rspack'] : []),
],
nextTgzFilename,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment