backport(15.3): document turbopack trace viewer (#78184) (#80589)

Backports #78184 (@timneutkens)

User request:
(https://vercel.slack.com/archives/C06CUNEC64D/p1750069211569019)

> could the change from `next internal turbo-trace-server` to `next
internal trace` be backported to a non-canary Next.js version? (to align
with the published docs suggestion)
>
> currently, the docs say "You can interpret the file using `next
internal trace [path-to-file]`:" ... and then further down "On versions
where `trace` is not available, the command was named
`turbo-trace-server`" ... which means that anyone on non-canary versions
following the docs right now will receive `error: unknown command
'trace'`
>
> https://nextjs.org/docs/app/guides/local-development#turbopack-tracing

The `mdx` change here isn't really relevant, since we don't build docs
from this branch, but it merges cleanly, so it's harmless.

Co-authored-by: Tim Neutkens <[email protected]>

Author: bgw

crates/napi/src/next_api/project.rs

@@ -382,7 +382,7 @@ pub async fn project_new(
             thread::spawn(move || {
                 turbopack_trace_server::start_turbopack_trace_server(trace_file);
             });
-            println!("Turbopack trace server started. View trace at https://turbo-trace-viewer.vercel.app/");
+            println!("Turbopack trace server started. View trace at https://trace.nextjs.org");
         }
 
         subscriber.init();

docs/01-app/03-building-your-application/06-optimizing/14-local-development.mdx

@@ -78,6 +78,8 @@ module.exports = {
 }
 ```
 
+Turbopack automatically analyzes imports and optimizes them. It does not require this configuration.
+
 ### 4. Check your Tailwind CSS setup
 
 If you're using Tailwind CSS, make sure it's set up correctly.
@@ -140,15 +142,36 @@ Use this command to see more detailed information about what's happening during
 next dev --verbose
 ```
 
-## Still having problems?
+## Turbopack tracing
 
-If you've tried everything and still have issues:
+Turbopack tracing is a tool that helps you understand the performance of your application during local development.
+It provides detailed information about the time taken for each module to compile and how they are related.
 
-1. Create a simple version of your app that shows the problem.
-2. Generate a special file that shows what's happening:
+1. Make sure you have the latest version of Next.js installed.
+1. Generate a Turbopack trace file:
 
    ```bash
-   NEXT_CPU_PROF=1 npm run dev
+   NEXT_TURBOPACK_TRACING=1 npm run dev
    ```
 
-3. Share this file (found in your project's main folder) and the `.next/trace` file on GitHub as a new issue.
+1. Navigate around your application or make edits to files to reproduce the problem.
+1. Stop the Next.js development server.
+1. A file called `trace-turbopack` will be available in the `.next` folder.
+1. You can interpret the file using `next internal trace [path-to-file]`:
+
+   ```bash
+   next internal trace .next/trace-turbopack
+   ```
+
+   On versions where `trace` is not available, the command was named `turbo-trace-server`:
+
+   ```bash
+   next internal turbo-trace-server .next/trace-turbopack
+   ```
+
+1. Once the trace server is running you can view the trace at https://trace.nextjs.org/.
+1. By default the trace viewer will aggregate timings, in order to see each individual time you can switch from "Aggregated in order" to "Spans in order" at the top right of the viewer.
+
+## Still having problems?
+
+Share the trace file generated in the [Turbopack Tracing](#turbopack-tracing) section and share it on [GitHub Discussions](https://github.com/vercel/next.js/discussions) or [Discord](https://nextjs.org/discord).

packages/next/src/bin/next.ts

@@ -421,7 +421,8 @@ const internal = program
   )
 
 internal
-  .command('turbo-trace-server')
+  .command('trace')
+  .alias('turbo-trace-server')
   .argument('[file]', 'Trace file to serve.')
   .action((file: string) => {
     return import('../cli/internal/turbo-trace-server.js').then((mod) =>

packages/next/src/build/swc/index.ts

@@ -1255,7 +1255,7 @@ function loadNative(importPath?: string) {
         createProject: bindingToApi(customBindings ?? bindings, false),
         startTurbopackTraceServer(traceFilePath) {
           Log.warn(
-            'Turbopack trace server started. View trace at https://turbo-trace-viewer.vercel.app/'
+            'Turbopack trace server started. View trace at https://trace.nextjs.org'
           )
           ;(customBindings ?? bindings).startTurbopackTraceServer(traceFilePath)
         },