Add --api Flag to Create Headless API App with create-next-app (#68130)

### What?

Added a new option for `create-next-app` to create a headless API app.
This includes:
- Adding a `--api` flag for `create-next-app` to create a headless app.
- Modifying the template to include only the required assets (no
`public/`, `app/page.*`, etc.).
- Ensuring the app includes only the required dependencies (no
`@types/react`, `react`, etc.).

### Why?

This feature allows users to initialize projects with headless API
templates, making it easier to set up projects that require backend
functionality without frontend components.

### How?

- Added the `--api` flag to the `create-next-app` command.
- Modified the template to exclude unnecessary assets and dependencies.
- Included exemplary usage of `route.js` features with comments for user
guidance.
- Implemented HTTP Methods and Parameters for request validation.

Closes #68118
Closes NEXT-3633
Closes NDX-120

---------

Signed-off-by: Arindam Majumder <arindammajumder2020@gmail.com>
Co-authored-by: Mert Can Altin <mertgold60@gmail.com>
Co-authored-by: Jiwon Choi <devjiwonchoi@gmail.com>
Co-authored-by: Tim_Z <z22zhong@uwaterloo.ca>
Co-authored-by: Tim_Z <43297139+Tim-Zj@users.noreply.github.com>
Co-authored-by: Ahmed Abdelbaset <A7med3bdulBaset@gmail.com>
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: Ephraim Atta-Duncan <ephraimduncan68@gmail.com>
Co-authored-by: Zack Tanner <1939140+ztanner@users.noreply.github.com>

packages/create-next-app/create-app.ts

@@ -36,6 +36,7 @@ export async function createApp({
   importAlias,
   skipInstall,
   empty,
+  api,
   turbopack,
   disableGit,
 }: {
@@ -51,6 +52,7 @@ export async function createApp({
   importAlias: string
   skipInstall: boolean
   empty: boolean
+  api?: boolean
   turbopack: boolean
   disableGit?: boolean
 }): Promise<void> {
@@ -224,7 +226,7 @@ export async function createApp({
     await installTemplate({
       appName,
       root,
-      template,
+      template: api ? 'app-api' : template,
       mode,
       packageManager,
       isOnline,

packages/create-next-app/index.ts

@@ -57,6 +57,7 @@ const program = new Command(packageJson.name)
     '--import-alias <prefix/*>',
     'Specify import alias to use (default "@/*").'
   )
+  .option('--api', 'Initialize a headless API using the App Router.')
   .option('--empty', 'Initialize an empty project.')
   .option(
     '--use-npm',
@@ -275,7 +276,7 @@ async function run(): Promise<void> {
       }
     }
 
-    if (!opts.eslint && !args.includes('--no-eslint')) {
+    if (!opts.eslint && !args.includes('--no-eslint') && !opts.api) {
       if (skipPrompt) {
         opts.eslint = getPrefOrDefault('eslint')
       } else {
@@ -294,7 +295,7 @@ async function run(): Promise<void> {
       }
     }
 
-    if (!opts.tailwind && !args.includes('--no-tailwind')) {
+    if (!opts.tailwind && !args.includes('--no-tailwind') && !opts.api) {
       if (skipPrompt) {
         opts.tailwind = getPrefOrDefault('tailwind')
       } else {
@@ -332,7 +333,7 @@ async function run(): Promise<void> {
       }
     }
 
-    if (!opts.app && !args.includes('--no-app')) {
+    if (!opts.app && !args.includes('--no-app') && !opts.api) {
       if (skipPrompt) {
         opts.app = getPrefOrDefault('app')
       } else {
@@ -429,6 +430,7 @@ async function run(): Promise<void> {
       importAlias: opts.importAlias,
       skipInstall: opts.skipInstall,
       empty: opts.empty,
+      api: opts.api,
       turbopack: opts.turbopack,
       disableGit: opts.disableGit,
     })

packages/create-next-app/templates/app-api/js/README-template.md

@@ -0,0 +1,40 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/route.ts`. The page auto-updates as you edit the file.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+
+## API Routes
+
+This directory contains example API routes for the headless API app.
+
+For more details, see [route.js file convention](https://nextjs.org/docs/app/api-reference/file-conventions/route).

packages/create-next-app/templates/app-api/js/app/[slug]/route.js

@@ -0,0 +1,6 @@
+import { NextResponse } from "next/server";
+
+export async function GET(request, { params }) {
+  const { slug } = await params;
+  return NextResponse.json({ message: `Hello ${slug}!` });
+}

packages/create-next-app/templates/app-api/js/app/route.js

@@ -0,0 +1,5 @@
+import { NextResponse } from "next/server";
+
+export async function GET() {
+  return NextResponse.json({ message: "Hello world!" });
+}

packages/create-next-app/templates/app-api/js/gitignore

@@ -0,0 +1,40 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

packages/create-next-app/templates/app-api/js/jsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./*"]
+    }
+  }
+}

packages/create-next-app/templates/app-api/js/next.config.mjs

@@ -0,0 +1,4 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;

packages/create-next-app/templates/app-api/ts/README-template.md

@@ -0,0 +1,40 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/route.ts`. The page auto-updates as you edit the file.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+
+## API Routes
+
+This directory contains example API routes for the headless API app.
+
+For more details, see [route.js file convention](https://nextjs.org/docs/app/api-reference/file-conventions/route).

packages/create-next-app/templates/app-api/ts/app/[slug]/route.ts

@@ -0,0 +1,9 @@
+import { NextRequest, NextResponse } from "next/server";
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ slug: string }> },
+) {
+  const { slug } = await params;
+  return NextResponse.json({ message: `Hello ${slug}!` });
+}

packages/create-next-app/templates/app-api/ts/app/route.ts

@@ -0,0 +1,5 @@
+import { NextResponse } from "next/server";
+
+export async function GET() {
+  return NextResponse.json({ message: "Hello world!" });
+}

packages/create-next-app/templates/app-api/ts/gitignore

@@ -0,0 +1,40 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env files (can opt-in for commiting if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

packages/create-next-app/templates/app-api/ts/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.

packages/create-next-app/templates/app-api/ts/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;

packages/create-next-app/templates/app-api/ts/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}