Skip to content

Commit c63224f

Browse files
authored
[backport] feat(turbopack): add LocalPathOrProjectPath PostCSS config resolution (#94284)
Backports [feat(turbopack): add LocalPathOrProjectPath PostCSS config resolution (#91338)](#91338) to `next-16-2`. <!-- NEXT_JS_LLM_PR -->
1 parent 63115c7 commit c63224f

43 files changed

Lines changed: 487 additions & 49 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎crates/next-core/src/next_client/context.rs‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -311,13 +311,21 @@ pub async fn get_client_module_options_context(
311311

312312
next_client_rules.extend(additional_rules);
313313

314+
let local_postcss_config = *next_config
315+
.experimental_turbopack_local_postcss_config()
316+
.await?;
317+
let postcss_config_location = if local_postcss_config == Some(true) {
318+
PostCssConfigLocation::LocalPathOrProjectPath
319+
} else {
320+
PostCssConfigLocation::ProjectPathOrLocalPath
321+
};
314322
let postcss_transform_options = PostCssTransformOptions {
315323
postcss_package: Some(
316324
get_postcss_package_mapping(project_path.clone())
317325
.to_resolved()
318326
.await?,
319327
),
320-
config_location: PostCssConfigLocation::ProjectPathOrLocalPath,
328+
config_location: postcss_config_location,
321329
..Default::default()
322330
};
323331
let postcss_foreign_transform_options = PostCssTransformOptions {

‎crates/next-core/src/next_config.rs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1176,6 +1176,11 @@ pub struct ExperimentalConfig {
11761176
/// present.
11771177
#[serde(default)]
11781178
turbopack_use_builtin_babel: Option<bool>,
1179+
/// Enable per-directory PostCSS config resolution. When true, Turbopack
1180+
/// searches for postcss.config.js starting from the CSS file's parent
1181+
/// directory first, then falls back to the project root.
1182+
#[serde(default)]
1183+
turbopack_local_postcss_config: Option<bool>,
11791184
// Whether to enable the global-not-found convention
11801185
global_not_found: Option<bool>,
11811186
/// Defaults to false in development mode, true in production mode.
@@ -1869,6 +1874,11 @@ impl NextConfig {
18691874
Vc::cell(self.experimental.turbopack_use_builtin_sass)
18701875
}
18711876

1877+
#[turbo_tasks::function]
1878+
pub fn experimental_turbopack_local_postcss_config(&self) -> Vc<Option<bool>> {
1879+
Vc::cell(self.experimental.turbopack_local_postcss_config)
1880+
}
1881+
18721882
#[turbo_tasks::function]
18731883
pub fn react_compiler_options(&self) -> Vc<OptionalReactCompilerOptions> {
18741884
let options = &self.react_compiler;

‎crates/next-core/src/next_server/context.rs‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -446,13 +446,21 @@ pub async fn get_server_module_options_context(
446446

447447
let foreign_code_context_condition =
448448
foreign_code_context_condition(next_config, project_path.clone()).await?;
449+
let local_postcss_config = *next_config
450+
.experimental_turbopack_local_postcss_config()
451+
.await?;
452+
let postcss_config_location = if local_postcss_config == Some(true) {
453+
PostCssConfigLocation::LocalPathOrProjectPath
454+
} else {
455+
PostCssConfigLocation::ProjectPathOrLocalPath
456+
};
449457
let postcss_transform_options = PostCssTransformOptions {
450458
postcss_package: Some(
451459
get_postcss_package_mapping(project_path.clone())
452460
.to_resolved()
453461
.await?,
454462
),
455-
config_location: PostCssConfigLocation::ProjectPathOrLocalPath,
463+
config_location: postcss_config_location,
456464
..Default::default()
457465
};
458466
let postcss_foreign_transform_options = PostCssTransformOptions {
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: turbopackLocalPostcssConfig
3+
description: Enable per-directory PostCSS config resolution in Turbopack so that the config closest to each CSS file takes precedence over the project root config.
4+
---
5+
6+
The `turbopackLocalPostcssConfig` option changes how Turbopack resolves `postcss.config.js` files. When enabled, Turbopack searches for the config starting from the CSS file's own directory first, then falls back to the project root. By default, Turbopack checks the project root first, meaning a root-level `postcss.config.js` always takes precedence over configs in subdirectories.
7+
8+
This option is only relevant when using Turbopack (`next dev` or `next build`).
9+
10+
## Usage
11+
12+
```ts filename="next.config.ts" switcher
13+
import type { NextConfig } from 'next'
14+
15+
const nextConfig: NextConfig = {
16+
experimental: {
17+
turbopackLocalPostcssConfig: true,
18+
},
19+
}
20+
21+
export default nextConfig
22+
```
23+
24+
```js filename="next.config.js" switcher
25+
/** @type {import('next').NextConfig} */
26+
const nextConfig = {
27+
experimental: {
28+
turbopackLocalPostcssConfig: true,
29+
},
30+
}
31+
32+
module.exports = nextConfig
33+
```
34+
35+
## Behavior
36+
37+
| Setting | Config resolution order |
38+
| ----------------- | ----------------------------------- |
39+
| `false` (default) | Project root → CSS file's directory |
40+
| `true` | CSS file's directory → project root |
41+
42+
With the default behavior, a `postcss.config.js` at the project root is used for all CSS files, and per-directory configs are only applied if no root config exists. Enabling `turbopackLocalPostcssConfig` reverses this: per-directory configs take precedence, and the root config serves as the fallback.
43+
44+
## Example
45+
46+
This is useful for projects that need different PostCSS transforms in different directories, such as a monorepo with multiple apps or design system packages:
47+
48+
```
49+
my-app/
50+
├── postcss.config.js ← fallback (applied if no local config is found)
51+
├── app/
52+
│ └── page.module.css ← uses root config
53+
└── packages/
54+
└── ui/
55+
├── postcss.config.js ← takes precedence for files in this directory
56+
└── button.module.css ← uses packages/ui/postcss.config.js
57+
```
58+
59+
## Version History
60+
61+
| Version | Changes |
62+
| --------- | ----------------------------------------- |
63+
| `v16.3.0` | `turbopackLocalPostcssConfig` introduced. |

‎docs/01-app/03-api-reference/08-turbopack.mdx‎

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -254,24 +254,25 @@ Turbopack can be configured via `next.config.js` (or `next.config.ts`) under the
254254

255255
Additionally, the following experimental options are available under `experimental` in `next.config.js`:
256256

257-
| Option | Description | Default (dev) | Default (build) |
258-
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------- | ----------------------------- |
259-
| [`turbopackFileSystemCacheForDev`](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache) | Enable filesystem cache for the dev server. | `true` | N/A |
260-
| [`turbopackFileSystemCacheForBuild`](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache) | Enable filesystem cache for builds. | N/A | `false` |
261-
| `turbopackMinify` | Enable minification. | `false` | `true` |
262-
| `turbopackSourceMaps` | Enable source maps. | `true` | `productionBrowserSourceMaps` |
263-
| `turbopackInputSourceMaps` | Enable extraction of source maps from input files. | `true` | `true` |
264-
| `turbopackTreeShaking` | Use advanced module-fragments tree shaking instead of the default reexports-only mode. | `false` | `false` |
265-
| `turbopackRemoveUnusedImports` | Enable removing unused imports. Requires `turbopackRemoveUnusedExports`. | `false` | `true` |
266-
| `turbopackRemoveUnusedExports` | Enable removing unused exports. | `false` | `true` |
267-
| `turbopackInferModuleSideEffects` | Enable local analysis to infer side-effect-free modules for better tree shaking. | `true` | `true` |
268-
| `turbopackScopeHoisting` | Enable scope hoisting. Always disabled in dev mode. | `false` | `true` |
269-
| `turbopackClientSideNestedAsyncChunking` | Enable nested async chunking for client-side assets. | `false` | `true` |
270-
| `turbopackServerSideNestedAsyncChunking` | Enable nested async chunking for server-side assets. | `false` | `false` |
271-
| `turbopackImportTypeBytes` | Enable support for `with {type: "bytes"}` for ESM imports. | `false` | `false` |
272-
| `turbopackUseBuiltinBabel` | Enable automatic Babel loader configuration when a Babel config file is present. | `true` | `true` |
273-
| `turbopackUseBuiltinSass` | Enable automatic Sass loader configuration. | `true` | `true` |
274-
| `turbopackModuleIds` | Module ID strategy: `'named'` or `'deterministic'`. | `'named'` | `'deterministic'` |
257+
| Option | Description | Default (dev) | Default (build) |
258+
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------- | ----------------------------- |
259+
| [`turbopackFileSystemCacheForDev`](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache) | Enable filesystem cache for the dev server. | `true` | N/A |
260+
| [`turbopackFileSystemCacheForBuild`](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache) | Enable filesystem cache for builds. | N/A | `false` |
261+
| `turbopackMinify` | Enable minification. | `false` | `true` |
262+
| `turbopackSourceMaps` | Enable source maps. | `true` | `productionBrowserSourceMaps` |
263+
| `turbopackInputSourceMaps` | Enable extraction of source maps from input files. | `true` | `true` |
264+
| `turbopackTreeShaking` | Use advanced module-fragments tree shaking instead of the default reexports-only mode. | `false` | `false` |
265+
| `turbopackRemoveUnusedImports` | Enable removing unused imports. Requires `turbopackRemoveUnusedExports`. | `false` | `true` |
266+
| `turbopackRemoveUnusedExports` | Enable removing unused exports. | `false` | `true` |
267+
| `turbopackInferModuleSideEffects` | Enable local analysis to infer side-effect-free modules for better tree shaking. | `true` | `true` |
268+
| `turbopackScopeHoisting` | Enable scope hoisting. Always disabled in dev mode. | `false` | `true` |
269+
| `turbopackClientSideNestedAsyncChunking` | Enable nested async chunking for client-side assets. | `false` | `true` |
270+
| `turbopackServerSideNestedAsyncChunking` | Enable nested async chunking for server-side assets. | `false` | `false` |
271+
| `turbopackImportTypeBytes` | Enable support for `with {type: "bytes"}` for ESM imports. | `false` | `false` |
272+
| `turbopackUseBuiltinBabel` | Enable automatic Babel loader configuration when a Babel config file is present. | `true` | `true` |
273+
| `turbopackUseBuiltinSass` | Enable automatic Sass loader configuration. | `true` | `true` |
274+
| `turbopackModuleIds` | Module ID strategy: `'named'` or `'deterministic'`. | `'named'` | `'deterministic'` |
275+
| [`turbopackLocalPostcssConfig`](/docs/app/api-reference/config/next-config-js/turbopackLocalPostcssConfig) | Resolve `postcss.config.js` from the CSS file's directory first, then the project root. | `false` | `false` |
275276

276277
```js filename="next.config.js"
277278
module.exports = {

‎packages/next/src/server/config-schema.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -353,6 +353,7 @@ export const experimentalSchema = {
353353
turbopackImportTypeText: z.boolean().optional(),
354354
turbopackUseBuiltinBabel: z.boolean().optional(),
355355
turbopackUseBuiltinSass: z.boolean().optional(),
356+
turbopackLocalPostcssConfig: z.boolean().optional(),
356357
turbopackModuleIds: z.enum(['named', 'deterministic']).optional(),
357358
turbopackInferModuleSideEffects: z.boolean().optional(),
358359
turbopackServerFastRefresh: z.boolean().optional(),

‎packages/next/src/server/config-shared.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -667,6 +667,15 @@ export interface ExperimentalConfig {
667667
*/
668668
turbopackUseBuiltinSass?: boolean
669669

670+
/**
671+
* Enable per-directory PostCSS config resolution for Turbopack. When enabled,
672+
* Turbopack searches for `postcss.config.js` starting from the CSS file's
673+
* parent directory first, then falls back to the project root. When disabled
674+
* (default), the project root is checked first, with the CSS file's directory
675+
* as a fallback.
676+
*/
677+
turbopackLocalPostcssConfig?: boolean
678+
670679
/**
671680
* The module ID strategy to use for Turbopack.
672681
* If not set, the default is `'named'` for development and `'deterministic'`
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import s1 from '../../styles/dir1/style01.module.css'
2+
import s2 from '../../styles/dir1/style02.module.css'
3+
import s3 from '../../styles/dir1/style03.module.css'
4+
5+
const styles = [s1, s2, s3]
6+
7+
export default function Dir1() {
8+
return (
9+
<div>
10+
{styles.map((s, i) => (
11+
<p
12+
key={i}
13+
id={`dir1-file${String(i + 1).padStart(2, '0')}`}
14+
className={s.text}
15+
>
16+
dir1 file{String(i + 1).padStart(2, '0')}
17+
</p>
18+
))}
19+
</div>
20+
)
21+
}
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import s1 from '../../styles/dir2/style01.module.css'
2+
import s2 from '../../styles/dir2/style02.module.css'
3+
import s3 from '../../styles/dir2/style03.module.css'
4+
5+
const styles = [s1, s2, s3]
6+
7+
export default function Dir2() {
8+
return (
9+
<div>
10+
{styles.map((s, i) => (
11+
<p
12+
key={i}
13+
id={`dir2-file${String(i + 1).padStart(2, '0')}`}
14+
className={s.text}
15+
>
16+
dir2 file{String(i + 1).padStart(2, '0')}
17+
</p>
18+
))}
19+
</div>
20+
)
21+
}

0 commit comments

Comments
 (0)