diff --git a/docs/01-app/03-api-reference/08-turbopack.mdx b/docs/01-app/03-api-reference/08-turbopack.mdx index 2b47fb0b11297e..7f774415011ae2 100644 --- a/docs/01-app/03-api-reference/08-turbopack.mdx +++ b/docs/01-app/03-api-reference/08-turbopack.mdx @@ -132,6 +132,34 @@ Webpack generally does this as well, but there are cases where it will ignore JS This can lead to subtle rendering changes when adopting Turbopack, if applications have come to rely on an arbitrary ordering. Generally, the solution is easy, e.g. have `button.module.css` `@import utils.module.css` to force the ordering, or identify the conflicting rules and change them to not target the same properties. +### Sass node_modules imports + +Turbopack supports importing `node_modules` Sass files out of the box. Webpack supports a legacy tilde `~` syntax for this, which is not supported by Turbopack. + +From: + +```scss filename="styles/globals.scss" +@import '~bootstrap/dist/css/bootstrap.min.css'; +``` + +To: + +```scss filename="styles/globals.scss" +@import 'bootstrap/dist/css/bootstrap.min.css'; +``` + +If you can't update the imports, you can add a `turbopack.resolveAlias` configuration to map the `~` syntax to the actual path: + +```js filename="next.config.js" +module.exports = { + turbopack: { + resolveAlias: { + '~*': '*', + }, + }, +} +``` + ### Bundle Sizes From our testing on production applications, we observed that Turbopack generally produces bundles that are similar in size to Webpack. However, the comparison can be difficult since turbopack tends to produce fewer but larger chunks. Our advice is to focus on higher level metrics like [Core Web Vitals](https://web.dev/articles/vitals) or your own application level metrics to compare performance across the two bundlers. We are however aware of one gap that can occasionally cause a large regression.