Skip to content

Document Turbopack trace viewer #78184

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 15, 2025
Merged

Document Turbopack trace viewer #78184

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion crates/napi/src/next_api/project.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
35 changes: 29 additions & 6 deletions docs/01-app/03-building-your-application/06-optimizing/14-local-development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this still live under the next internal subcommand now that we document it and use a URL that doesn't look as internal?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the intention is to keep low-level tooling that is focused on our own debugging under next internal. This tool is still meant for us to dig into performance/memory, but it's proving to be useful as a last resort.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not following why we document something publicly while calling it internal. Our internal tools shouldn't leak into public docs in my opinion.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This docs page in particular is a bit different than others. It's more like a troubleshooting guide. In my opinion we should document all possible tools for troubleshooting this particular issue (slow compilation). We're going to have higher level tooling for this too but that is not available yet, once that is available this tool might no longer be needed outside of our own use. For now it's important to document it exists.

```

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).
3 changes: 2 additions & 1 deletion packages/next/src/bin/next.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) =>
Expand Down
2 changes: 1 addition & 1 deletion packages/next/src/build/swc/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1250,7 +1250,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)
},
Expand Down
Loading