Skip to content

Commit e4f9a30

Browse files
lukesandbergclaude
lukesandberg
and
claude
committed
docs: update guides and migration docs for Turbopack as default
Phase 2: Guides and Migration Documentation Updates - Update Local Development Guide to show Turbopack as default - Update Custom Server docs for turbo option behavior - Update Create Next App CLI documentation - Update CRA migration guide with new defaults and examples - Replace --turbopack examples with --webpack opt-in patterns 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
1 parent 1c80166 commit e4f9a30

File tree

4 files changed

+58
-45
lines changed

4 files changed

+58
-45
lines changed

‎docs/01-app/02-guides/custom-server.mdx‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -87,16 +87,17 @@ const app = next({})
8787

8888
The above `next` import is a function that receives an object with the following options:
8989

90-
| Option | Type | Description |
91-
| ------------ | ------------------ | ----------------------------------------------------------------------------------- |
92-
| `conf` | `Object` | The same object you would use in `next.config.js`. Defaults to `{}` |
93-
| `dev` | `Boolean` | (_Optional_) Whether or not to launch Next.js in dev mode. Defaults to `false` |
94-
| `dir` | `String` | (_Optional_) Location of the Next.js project. Defaults to `'.'` |
95-
| `quiet` | `Boolean` | (_Optional_) Hide error messages containing server information. Defaults to `false` |
96-
| `hostname` | `String` | (_Optional_) The hostname the server is running behind |
97-
| `port` | `Number` | (_Optional_) The port the server is running behind |
98-
| `httpServer` | `node:http#Server` | (_Optional_) The HTTP Server that Next.js is running behind |
99-
| `turbo` | `Boolean` | (_Optional_) Enable Turbopack |
90+
| Option | Type | Description |
91+
| ------------------- | ------------------ | ----------------------------------------------------------------------------------- |
92+
| `conf` | `Object` | The same object you would use in `next.config.js`. Defaults to `{}` |
93+
| `dev` | `Boolean` | (_Optional_) Whether or not to launch Next.js in dev mode. Defaults to `false` |
94+
| `dir` | `String` | (_Optional_) Location of the Next.js project. Defaults to `'.'` |
95+
| `quiet` | `Boolean` | (_Optional_) Hide error messages containing server information. Defaults to `false` |
96+
| `hostname` | `String` | (_Optional_) The hostname the server is running behind |
97+
| `port` | `Number` | (_Optional_) The port the server is running behind |
98+
| `httpServer` | `node:http#Server` | (_Optional_) The HTTP Server that Next.js is running behind |
99+
| `turbopack`/`turbo` | `Boolean` | (_Optional_) Enable Turbopack (enabled by default) |
100+
| `webpack` | `Boolean` | (_Optional_) Enable webpack |
100101

101102
The returned `app` can then be used to let Next.js handle requests as required.
102103

‎docs/01-app/02-guides/local-development.mdx‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,15 +48,21 @@ On macOS, you can disable [Gatekeeper](https://support.apple.com/guide/security/
4848

4949
If you or your employer have configured any other Antivirus solutions on your system, you should inspect the relevant settings for those products.
5050

51-
### 2. Update Next.js and enable Turbopack
51+
### 2. Update Next.js and use Turbopack
5252

5353
Make sure you're using the latest version of Next.js. Each new version often includes performance improvements.
5454

55-
Turbopack is a new bundler integrated into Next.js that can improve local performance.
55+
Turbopack is now the default bundler for Next.js development and provides significant performance improvements over webpack.
5656

5757
```bash
5858
npm install next@latest
59-
npm run dev --turbopack
59+
npm run dev # Turbopack is used by default
60+
```
61+
62+
If you need to use Webpack instead of Turbopack, you can opt-in:
63+
64+
```bash
65+
npm run dev --webpack
6066
```
6167

6268
[Learn more about Turbopack](/blog/turbopack-for-development-stable). See our [upgrade guides](/docs/app/guides/upgrading) and codemods for more information.
@@ -146,7 +152,7 @@ Tailwind CSS version 3.4.8 or newer will warn you about settings that might slow
146152

147153
If you've added custom webpack settings, they might be slowing down compilation.
148154

149-
Consider if you really need them for local development. You can optionally only include certain tools for production builds, or explore moving to Turbopack and using [loaders](/docs/app/api-reference/config/next-config-js/turbopack#supported-loaders).
155+
Consider if you really need them for local development. You can optionally only include certain tools for production builds, or explore using the default Turbopack bundler and configuring [loaders](/docs/app/api-reference/config/next-config-js/turbopack#supported-loaders) instead.
150156

151157
### 6. Optimize memory usage
152158

‎docs/01-app/02-guides/migrating/from-create-react-app.mdx‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -455,7 +455,7 @@ Update your `package.json` scripts to use Next.js commands. Also, add `.next` an
455455
```json filename="package.json"
456456
{
457457
"scripts": {
458-
"dev": "next dev --turbopack",
458+
"dev": "next dev",
459459
"build": "next build",
460460
"start": "npx serve@latest ./build"
461461
}
@@ -543,7 +543,7 @@ const nextConfig: NextConfig = {
543543
export default nextConfig
544544
```
545545

546-
> **Note**: This will require disabling Turbopack by removing `--turbopack` from your `dev` script.
546+
> **Note**: This will require using Webpack by adding `--webpack` to your `dev` script.
547547
548548
### TypeScript Setup
549549

@@ -557,10 +557,16 @@ Next.js automatically sets up TypeScript if you have a `tsconfig.json`. Make sur
557557

558558
## Bundler Compatibility
559559

560-
Both Create React App and Next.js default to webpack for bundling. Next.js also offers [Turbopack](/docs/app/api-reference/config/next-config-js/turbopack) for faster local development with:
560+
Create React App uses webpack for bundling. Next.js now defaults to [Turbopack](/docs/app/api-reference/config/next-config-js/turbopack) for faster local development:
561561

562562
```bash
563-
next dev --turbopack
563+
next dev # Uses Turbopack by default
564+
```
565+
566+
To use Webpack instead (similar to CRA):
567+
568+
```bash
569+
next dev --webpack
564570
```
565571

566572
You can still provide a [custom webpack configuration](/docs/app/api-reference/config/next-config-js/webpack) if you need to migrate advanced webpack settings from CRA.

‎docs/01-app/03-api-reference/06-cli/create-next-app.mdx‎

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -17,33 +17,33 @@ npx create-next-app@latest [project-name] [options]
1717

1818
The following options are available:
1919

20-
| Options | Description |
21-
| --------------------------------------- | --------------------------------------------------------------- |
22-
| `-h` or `--help` | Show all available options |
23-
| `-v` or `--version` | Output the version number |
24-
| `--no-*` | Negate default options. E.g. `--no-ts` |
25-
| `--ts` or `--typescript` | Initialize as a TypeScript project (default) |
26-
| `--js` or `--javascript` | Initialize as a JavaScript project |
27-
| `--tailwind` | Initialize with Tailwind CSS config (default) |
28-
| `--eslint` | Initialize with ESLint config |
29-
| `--biome` | Initialize with Biome config |
30-
| `--no-linter` | Skip linter configuration |
31-
| `--app` | Initialize as an App Router project |
32-
| `--api` | Initialize a project with only route handlers |
33-
| `--src-dir` | Initialize inside a `src/` directory |
34-
| `--turbopack` | Enable Turbopack by default for development |
35-
| `--import-alias <alias-to-configure>` | Specify import alias to use (default "@/\*") |
36-
| `--empty` | Initialize an empty project |
37-
| `--use-npm` | Explicitly tell the CLI to bootstrap the application using npm |
38-
| `--use-pnpm` | Explicitly tell the CLI to bootstrap the application using pnpm |
39-
| `--use-yarn` | Explicitly tell the CLI to bootstrap the application using Yarn |
40-
| `--use-bun` | Explicitly tell the CLI to bootstrap the application using Bun |
41-
| `-e` or `--example [name] [github-url]` | An example to bootstrap the app with |
42-
| `--example-path <path-to-example>` | Specify the path to the example separately |
43-
| `--reset-preferences` | Explicitly tell the CLI to reset any stored preferences |
44-
| `--skip-install` | Explicitly tell the CLI to skip installing packages |
45-
| `--disable-git` | Explicitly tell the CLI to disable git initialization |
46-
| `--yes` | Use previous preferences or defaults for all options |
20+
| Options | Description |
21+
| --------------------------------------- | --------------------------------------------------------------------- |
22+
| `-h` or `--help` | Show all available options |
23+
| `-v` or `--version` | Output the version number |
24+
| `--no-*` | Negate default options. E.g. `--no-ts` |
25+
| `--ts` or `--typescript` | Initialize as a TypeScript project (default) |
26+
| `--js` or `--javascript` | Initialize as a JavaScript project |
27+
| `--tailwind` | Initialize with Tailwind CSS config (default) |
28+
| `--eslint` | Initialize with ESLint config |
29+
| `--biome` | Initialize with Biome config |
30+
| `--no-linter` | Skip linter configuration |
31+
| `--app` | Initialize as an App Router project |
32+
| `--api` | Initialize a project with only route handlers |
33+
| `--src-dir` | Initialize inside a `src/` directory |
34+
| `--turbopack` | Force enable Turbopack in generated package.json (enabled by default) |
35+
| `--import-alias <alias-to-configure>` | Specify import alias to use (default "@/\*") |
36+
| `--empty` | Initialize an empty project |
37+
| `--use-npm` | Explicitly tell the CLI to bootstrap the application using npm |
38+
| `--use-pnpm` | Explicitly tell the CLI to bootstrap the application using pnpm |
39+
| `--use-yarn` | Explicitly tell the CLI to bootstrap the application using Yarn |
40+
| `--use-bun` | Explicitly tell the CLI to bootstrap the application using Bun |
41+
| `-e` or `--example [name] [github-url]` | An example to bootstrap the app with |
42+
| `--example-path <path-to-example>` | Specify the path to the example separately |
43+
| `--reset-preferences` | Explicitly tell the CLI to reset any stored preferences |
44+
| `--skip-install` | Explicitly tell the CLI to skip installing packages |
45+
| `--disable-git` | Explicitly tell the CLI to disable git initialization |
46+
| `--yes` | Use previous preferences or defaults for all options |
4747

4848
## Examples
4949

0 commit comments

Comments
 (0)