next.js
Details for Turbopack loaders.
#62300
Merged
Overview
Commits
12
Changes
View On GitHub

Details for Turbopack loaders. #62300

samcx merged 12 commits into canary from turbopack-loader-docs
anthonyshew
anthonyshew1 year ago (edited 1 year ago)

What?

Bringing Turbopack for Next.js documentation from turbo.build to nextjs.org/docs.

Note: After this PR lands, there will be a subsequent PR to vercel/turbo to remove these docs from turbo.build and redirect here.

Why?

Previously, this documentation was on turbo.build. This was confusing because these docs weren't specific to Next.js. Rather, they are for Next.js developers who want to configure their bundler (which happens to be Turbopack under the hood).

We had seen a number of times that folks were unable to find loader and configuration support for the their Next.js + Turbopack applications so this PR should help surface that information better where folks are looking for it.

anthonyshew Details for loaders.
26d65b75
ijjk ijjk added area: documentation
ijjk
ijjk1 year ago (edited 1 year ago)

Allow CI Workflow Run

  • approve CI run for commit: 7b7b363

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

anthonyshew anthonyshew marked this pull request as ready for review 1 year ago
anthonyshew anthonyshew requested a review 1 year ago
anthonyshew anthonyshew requested a review 1 year ago
anthonyshew anthonyshew removed review request 1 year ago
anthonyshew anthonyshew requested a review from jh3y jh3y 1 year ago
anthonyshew anthonyshew requested a review from molebox molebox 1 year ago
ijjk ijjk added examples
anthonyshew Tweaks.
3e4d594f
anthonyshew anthonyshew force pushed from a5afc99d to 3e4d594f 1 year ago
anthonyshew anthonyshew removed examples
delbaoliveira
delbaoliveira commented on 2024-02-26
delbaoliveira1 year ago

Thank you @anthonyshew 馃檹馃徏 Looking great!

I'm sure you have checked already, but is there anything on this page that needs updating?
https://nextjs.org/docs/app/api-reference/next-config-js/turbo

Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
2222
2323## Supported Features
2424
25To learn more about the currently supported features for Turbopack, view the [documentation](https://turbo.build/pack/docs/features).
25
Turbopack can be customized to transform different files and change how modules are resolved. It supports a subset of webpack's loader API and offers similar configuration aliasing module resolution.
delbaoliveira1 year ago

Does this help improve clarity?

Suggested change
Turbopack can be customized to transform different files and change how modules are resolved. It supports a subset of webpack's loader API and offers similar configuration aliasing module resolution.
Turbopack can be customized to transform different files and change how modules are resolved. It supports a subset of webpack's loader API and offers a similar aliasing module resolution configuration.
Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
26
27> **Good to know**:
28>
29
> Turbopack for Next.js does not require loaders nor loader configuration for
30
> built-in functionality, just as they aren't required for Next.js. Turbopack
31
> has built-in support for css and compiling modern JavaScript, so there's no
32
> need for `css-loader`, `postcss-loader`, or `babel-loader` if you're just
33
> using `@babel/preset-env`.
delbaoliveira1 year ago

Formatting:

Suggested change
> Turbopack for Next.js does not require loaders nor loader configuration for
> built-in functionality, just as they aren't required for Next.js. Turbopack
> has built-in support for css and compiling modern JavaScript, so there's no
> need for `css-loader`, `postcss-loader`, or `babel-loader` if you're just
> using `@babel/preset-env`.
> - Turbopack for Next.js does not require loaders nor loader configuration for built-in functionality, just as they aren't required for Next.js. Turbopack has built-in support for css and compiling modern JavaScript, so there's no need for `css-loader`, `postcss-loader`, or `babel-loader` if you're using `@babel/preset-env`.
Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
32> need for `css-loader`, `postcss-loader`, or `babel-loader` if you're just
33> using `@babel/preset-env`.
34
35
If you need loader support beyond what's built in, many webpack loaders already work with Turbopack. There are currently some limitations:
delbaoliveira1 year ago

Where can users find out what's built-in? Is it the ones listed above?

delbaoliveira1 year ago

I see, there's a list further down. Let's link to it, or maybe move the list to the top.

Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
36
37- Only a core subset of the webpack loader API is implemented. This is enough for some popular loaders, and we'll expand our support for this API in the future.
38- Only loaders that return JavaScript code are supported. Loaders that transform files like stylesheets or images are not currently supported.
39
- Options passed to webpack loaders must be plain JavaScript primitives, objects, and arrays. For example, it's not possible to pass `require()`d plugin modules as option values.
delbaoliveira1 year ago

Does this apply to JavaScript functions in general? Or was required() picked for a specific purpose?
Maybe you could say functions if it's general?

Also, minor typo.

Suggested change
- Options passed to webpack loaders must be plain JavaScript primitives, objects, and arrays. For example, it's not possible to pass `require()`d plugin modules as option values.
- Options passed to webpack loaders must be plain JavaScript primitives, objects, and arrays. For example, it's not possible to pass `require()` plugin modules as option values.
delbaoliveira1 year ago

Ah, I see. It's mentioned further down. Maybe you can add a heading and link to it from here. E.g. ## Importing packages as loader option

Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
38- Only loaders that return JavaScript code are supported. Loaders that transform files like stylesheets or images are not currently supported.
39- Options passed to webpack loaders must be plain JavaScript primitives, objects, and arrays. For example, it's not possible to pass `require()`d plugin modules as option values.
40
41
As of Next 13.2, configuring webpack loaders is possible for Next.js apps through an experimental option in `next.config.js`. `turbo.rules` can be set as a mapping of file globs to a list of package names or `{loader, options}` pairs:
delbaoliveira1 year ago

We should also document this option in the next.config.js API reference

Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
61 },
62}
63```
64
65
> **Good to know**:
66
>
67
> Note: Prior to Next.js version 13.4.4, `experimental.turbo.rules` was named
68
> `experimental.turbo.loaders` and only accepted file extensions like `.mdx`
69
> instead of `*.mdx`.
delbaoliveira1 year ago
Suggested change
> **Good to know**:
>
> Note: Prior to Next.js version 13.4.4, `experimental.turbo.rules` was named
> `experimental.turbo.loaders` and only accepted file extensions like `.mdx`
> instead of `*.mdx`.
> **Good to know**: Prior to Next.js version 13.4.4, `experimental.turbo.rules` was named `experimental.turbo.loaders` and only accepted file extensions like `.mdx` instead of `*.mdx`.
Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
67> Note: Prior to Next.js version 13.4.4, `experimental.turbo.rules` was named
68> `experimental.turbo.loaders` and only accepted file extensions like `.mdx`
69> instead of `*.mdx`.
70
delbaoliveira1 year ago (edited 1 year ago)

New example, add heading

Suggested change
### Importing packages as a loader option
Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
103}
104```
105
106
### Supported loaders
107
108
The following loaders have been tested to work with Turbopack's webpack loader implementation:
109
110
- [`babel-loader`](https://www.npmjs.com/package/babel-loader)
111
- [`@mdx-js/loader`](https://www.npmjs.com/package/@mdx-js/loader)
112
- [`@svgr/webpack`](https://www.npmjs.com/package/@svgr/webpack)
113
- [`svg-inline-loader`](https://www.npmjs.com/package/svg-inline-loader)
114
- [`yaml-loader`](https://www.npmjs.com/package/yaml-loader)
115
- [`string-replace-loader`](https://www.npmjs.com/package/string-replace-loader)
116
- [`raw-loader`](https://www.npmjs.com/package/raw-loader)
delbaoliveira1 year ago

The list of supported loaders seems very important, should we move it further up?

Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
132}
133```
134
135
This aliases imports of the `underscore` package to the `lodash` package so that `import underscore from 'underscore'` will load the `lodash` module instead of `underscore`.
delbaoliveira1 year ago

Nit, for clarity.

Suggested change
This aliases imports of the `underscore` package to the `lodash` package so that `import underscore from 'underscore'` will load the `lodash` module instead of `underscore`.
For example, this aliases the `underscore` package to the `lodash` package so that `import underscore from 'underscore'` will load the `lodash` module instead of `underscore`.
anthonyshew Update docs/04-architecture/turbopack.mdx
df68f913
anthonyshew Update docs/04-architecture/turbopack.mdx
d859ef68
anthonyshew Update docs/04-architecture/turbopack.mdx
4ef16e9a
anthonyshew Update docs/04-architecture/turbopack.mdx
f76aa015
anthonyshew Rework.
1c8f7ac6
anthonyshew Tweaks.
c80035b0
anthonyshew
anthonyshew1 year ago

Gave things a rework now that I know that page exists! 馃槢

delbaoliveira
delbaoliveira approved these changes on 2024-03-07
Conversation is marked as resolved
Show resolved
docs/02-app/02-api-reference/05-next-config-js/turbo.mdx
88
99
> **Warning**: These features are experimental and will only work with `next --turbo`.
1010
11
Turbopack can be customized to transform different files and change how modules are resolved.
12
13
> **Good to know**:
14
>
15
> - Turbopack for Next.js does not require loaders nor loader configuration for built-in functionality. Turbopack has built-in support for css and compiling modern JavaScript, so there's no need for `css-loader`, `postcss-loader`, or `babel-loader` if you're using `@babel/preset-env`.
16
delbaoliveira1 year ago (edited 1 year ago)

We could probably combine warning, and good to know sections. wdyt?

Suggested change
> **Warning**: These features are experimental and will only work with `next --turbo`.
Turbopack can be customized to transform different files and change how modules are resolved.
> **Good to know**:
>
> - Turbopack for Next.js does not require loaders nor loader configuration for built-in functionality. Turbopack has built-in support for css and compiling modern JavaScript, so there's no need for `css-loader`, `postcss-loader`, or `babel-loader` if you're using `@babel/preset-env`.
Turbopack can be customized to transform different files and change how modules are resolved.
> **Good to know**:
>
> - These features are experimental and will only work with `next --turbo`.
> - Turbopack for Next.js does not require loaders nor loader configuration for built-in functionality. Turbopack has built-in support for css and compiling modern JavaScript, so there's no need for `css-loader`, `postcss-loader`, or `babel-loader` if you're using `@babel/preset-env`.
anthonyshew1 year ago

馃挴

Conversation is marked as resolved
Show resolved
docs/04-architecture/turbopack.mdx
23## Supported features
2424
25To learn more about the currently supported features for Turbopack, view the [documentation](https://turbo.build/pack/docs/features).
25
Turbopack in Next.js requires zero-configuration for most users and can be extended for more advanced use cases. To learn more about the currently supported features for Turbopack, view the [API Reference](/docs/architecture/turbopack).
delbaoliveira1 year ago
Suggested change
Turbopack in Next.js requires zero-configuration for most users and can be extended for more advanced use cases. To learn more about the currently supported features for Turbopack, view the [API Reference](/docs/architecture/turbopack).
Turbopack in Next.js requires zero-configuration for most users and can be extended for more advanced use cases. To learn more about the currently supported features for Turbopack, view the [API Reference](/docs/app/api-reference/next-config-js/turbo).
anthonyshew1 year ago

D'oh!

anthonyshew Update docs/02-app/02-api-reference/05-next-config-js/turbo.mdx
f5c5f770
anthonyshew Update docs/04-architecture/turbopack.mdx
ddcb4b5f
anthonyshew Merge branch 'canary' into turbopack-loader-docs
7b7b363e
anthonyshew
anthonyshew1 year ago (edited 1 year ago)

@delbaoliveira Am I able to ship this with some of the checks in their current state (read: failing)? I don't know what's safe to push through on this side of the house. 馃槃

delbaoliveira Merge branch 'canary' into turbopack-loader-docs
f39a600a
samcx
samcx1 year ago

@anthonyshew Only failing because we have to manually approve commits in order for it to run the test suite!

samcx samcx merged de5d1c3f into canary 1 year ago
samcx samcx deleted the turbopack-loader-docs branch 1 year ago
github-actions github-actions added locked
github-actions github-actions locked as resolved and limited conversation to collaborators 1 year ago

Login to write a write a comment.

Login via GitHub

Reviewers
Assignees
No one assigned
Labels
locked
Milestone
No milestone
Terms Of Use Privacy Policy Refund Policy Impressum