Unverified Commit 44722b80 authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

Turbopack: import.meta.glob docs + edge case support (#92729)

## What?

Adds documentation and TypeScript types for `import.meta.glob` in
Turbopack, and implements additional edge cases for Vite compatibility.

### Documentation
- New `## import.meta.glob` section in the [Turbopack reference
page](/docs/app/api-reference/turbopack) covering: lazy/eager loading,
named imports, query strings (including the object form), multiple
patterns, negation, TypeScript types, and a full options table.
- `import.meta.glob` row added to the Module Resolution feature table.
- Migration note added to the [from-Vite
guide](/docs/app/guides/migrating/from-vite) explaining that
`import.meta.glob` works out of the box with Turbopack, with
before/after for the deprecated `as` → `query` migration.

### TypeScript types
- Added `ImportMetaGlobOptions` interface and overloaded `glob()`
signatures to `ImportMeta` in `packages/next/types/global.d.ts`.
- The overloads return `Record<string, unknown>` when `eager: true` is
passed and `Record<string, () => Promise<unknown>>` otherwise.

### Implementation (edge cases)
- **`import: '*'`** (namespace import): Treated the same as omitting the
`import` option (returns the whole module namespace), matching Vite
semantics. Previously would have generated broken `module["*"]` access.
- **`query` as object literal**: `{ query: { bar: 'foo', raw: true } }`
is now supported. Keys and values are URL-encoded and joined into a
query string (`?bar=foo&raw=true`).
- **Stricter option validation**: A non-object-literal second argument
(e.g. `import.meta.glob('./*.js', 'eager')`) is now a compile-time error
instead of a warning, since the options cannot be safely defaulted.

### Tests
- Execution tests for new features: namespace `import: '*'`, query
object, combining query with negation, explicit dotfile patterns.
- New `import-meta-glob-errors` execution test with issue snapshots
covering: too many arguments, non-string pattern, and non-object options
argument.

## Why?

1. The feature shipped in #92640 but had no user-facing documentation
and no TypeScript types.
2. Several Vite-compatible edge cases were not handled: namespace
imports (`import: '*'`) and query objects. These gaps would cause subtle
behavioral differences for users migrating from Vite.
3. Option validation was too lenient — invalid second arguments fell
through to defaults silently.

## How?

### Docs & types
- `docs/01-app/03-api-reference/08-turbopack.mdx` — new section, table
row, TypeScript subsection
- `docs/01-app/02-guides/migrating/from-vite.mdx` — migration note
- `packages/next/types/global.d.ts` — `ImportMetaGlobOptions` +
`ImportMeta.glob()` overloads

### Implementation
-
`turbopack/crates/turbopack-ecmascript/src/references/import_meta_glob.rs`:
- `parse_import_meta_glob()`: `import: '*'` normalized to `None`; query
object parsing via `urlencoding::encode()`; non-object options argument
now emits an error and returns `None`.
- `turbopack/crates/turbopack-ecmascript/Cargo.toml`: added
`urlencoding` workspace dep.

Note: dotfile/dot-directory filtering is not needed in
`import.meta.glob` itself — the underlying `Glob` pattern engine and
`read_glob_internal` already handle dotfile semantics correctly
(explicit `./.foo/*.js` matches, wildcards include them).

### Tests
-
`turbopack-tests/tests/execution/turbopack/resolving/import-meta-glob/`
— new cases for `import: '*'`, query object, query + negation, explicit
dotfile pattern, wildcard including dotfiles
-
`turbopack-tests/tests/execution/turbopack/resolving/import-meta-glob-errors/`
— new test suite for fatal parse errors with issue snapshots

### Checklist
- [x] `pnpm prettier-fix` / `cargo fmt` run
- [x] Documentation follows the [docs contribution
guide](https://nextjs.org/docs/community/contribution-guide)
- [x] Execution tests pass (`cargo test -p turbopack-tests --test
execution -- "import_meta_glob"`)
- [x] `cargo clippy` clean
- [x] `pnpm --filter=next types` passes

<!-- NEXT_JS_LLM_PR -->

---------
Co-authored-by: 's avatarTobias Koppers <sokra@users.noreply.github.com>
Co-authored-by: 's avatarClaude <noreply@anthropic.com>
parent e7bcba89
...@@ -10496,6 +10496,7 @@ dependencies = [ ...@@ -10496,6 +10496,7 @@ dependencies = [
"turbopack-swc-utils", "turbopack-swc-utils",
"turbopack-test-utils", "turbopack-test-utils",
"url", "url",
"urlencoding",
] ]
[[package]] [[package]]
......
...@@ -533,6 +533,18 @@ aren’t supported by Next.js. You need to update their usage as follows: ...@@ -533,6 +533,18 @@ aren’t supported by Next.js. You need to update their usage as follows:
- `import.meta.env.DEV` ⇒ `process.env.NODE_ENV !== 'production'` - `import.meta.env.DEV` ⇒ `process.env.NODE_ENV !== 'production'`
- `import.meta.env.SSR` ⇒ `typeof window !== 'undefined'` - `import.meta.env.SSR` ⇒ `typeof window !== 'undefined'`
**`import.meta.glob`** is supported by Turbopack (the default Next.js bundler) with no changes needed. If you were using the `as` option (deprecated in Vite 5), replace it with `query`:
```js
// Before (Vite)
const modules = import.meta.glob('./dir/*.txt', { as: 'raw' })
// After (Next.js / Turbopack)
const modules = import.meta.glob('./dir/*.txt', { query: '?raw' })
```
See the [import.meta.glob docs](/docs/app/api-reference/turbopack#importmetaglob) for the full API.
Next.js also doesn't provide a built-in `BASE_URL` environment variable. However, you can still Next.js also doesn't provide a built-in `BASE_URL` environment variable. However, you can still
configure one, if you need it: configure one, if you need it:
......
...@@ -137,6 +137,112 @@ Turbopack supports webpack-compatible magic comments for controlling import beha ...@@ -137,6 +137,112 @@ Turbopack supports webpack-compatible magic comments for controlling import beha
See [Lazy Loading](/docs/app/guides/lazy-loading#magic-comments) for usage examples. See [Lazy Loading](/docs/app/guides/lazy-loading#magic-comments) for usage examples.
## import.meta.glob
Turbopack supports `import.meta.glob()`, a Vite-compatible API for importing multiple modules at once using glob patterns. The result is an object keyed by the file path relative to the calling file.
```js
const modules = import.meta.glob('./dir/*.js')
// {
// './dir/foo.js': () => import('./dir/foo.js'),
// './dir/bar.js': () => import('./dir/bar.js'),
// }
```
> **Good to know:** `import.meta.glob` requires Turbopack. It is not available when using webpack.
### Lazy loading (default)
By default, each value in the result object is a thunk — a function that returns a `Promise` for the module. This enables lazy loading:
```js
const modules = import.meta.glob('./dir/*.js')
for (const path in modules) {
const module = await modules[path]()
console.log(path, module)
}
```
### Eager loading
Pass `{ eager: true }` to import all matching modules up front. Each value is the module object directly instead of a thunk:
```js
const modules = import.meta.glob('./dir/*.js', { eager: true })
for (const path in modules) {
console.log(path, modules[path].default)
}
```
### Named imports
Use the `import` option to select a specific named export from each matched module. This works in both lazy and eager modes:
```js
// Lazy: each value is () => Promise<exportValue>
const defaults = import.meta.glob('./dir/*.js', { import: 'default' })
// Eager: each value is the export value directly
const setups = import.meta.glob('./dir/*.js', { import: 'setup', eager: true })
```
### Query strings
Use the `query` option to append a query string to every import request. This is useful for loading files as raw strings or URLs:
```js
const rawFiles = import.meta.glob('./dir/*.txt', { query: '?raw' })
const urls = import.meta.glob('./dir/*.png', { query: '?url' })
```
The `query` option also accepts an object. Keys and values are URL-encoded and joined into a query string:
```js
const modules = import.meta.glob('./*.ts', {
query: { bar: 'foo', raw: true },
})
// equivalent to: { query: '?bar=foo&raw=true' }
```
### Multiple patterns and negation
Pass an array of glob patterns as the first argument. Prefix a pattern with `!` to exclude matching files:
```js
// Combine multiple directories
const modules = import.meta.glob(['./dir/*.js', './other/*.js'])
// Exclude specific files
const withoutTests = import.meta.glob(['./src/**/*.js', '!**/*.test.js'])
```
### TypeScript
TypeScript types for `import.meta.glob` are included in Next.js. They are available automatically when `"moduleResolution": "bundler"` (or `"node16"` / `"nodenext"`) is set in your `tsconfig.json`, which is the default for new Next.js projects.
The return type differs based on the `eager` option:
```ts
// Lazy (default) — Record<string, () => Promise<unknown>>
const lazy = import.meta.glob('./dir/*.ts')
// Eager — Record<string, unknown>
const eager = import.meta.glob('./dir/*.ts', { eager: true })
```
### Options reference
| Option | Type | Default | Description |
| -------- | --------------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| `eager` | `boolean` | `false` | Import modules synchronously instead of returning thunks. |
| `import` | `string` | `undefined` | Named export to select from each matched module (e.g. `'default'`). |
| `query` | `string \| Record<string, string \| boolean>` | `undefined` | Query string (or object) to append to each import. |
| `base` | `string` | `undefined` | Override the base path used for resolving patterns and keying results. |
> **Note:** The `as` option (deprecated in Vite 5) is not supported. Use `query: '?raw'` or `query: '?url'` instead. The legacy `import.meta.globEager()` API is also not supported — use `import.meta.glob('...', { eager: true })` instead.
## Known gaps with webpack ## Known gaps with webpack
There are a number of non-trivial behavior differences between webpack and Turbopack that are important to be aware of when migrating an application. Generally, these are less of a concern for new applications. There are a number of non-trivial behavior differences between webpack and Turbopack that are important to be aware of when migrating an application. Generally, these are less of a concern for new applications.
......
...@@ -81,6 +81,23 @@ interface TurbopackHotApi { ...@@ -81,6 +81,23 @@ interface TurbopackHotApi {
readonly data: Record<string, unknown> readonly data: Record<string, unknown>
} }
interface ImportMetaGlobOptions {
/** Import modules eagerly (synchronously). Default: `false`. */
eager?: boolean
/**
* Named export to select from each matched module.
* Use `'default'` for the default export, or `'*'` for the full namespace.
*/
import?: string
/**
* Query string to append to each import request (e.g. `'?raw'`, `'?url'`).
* Can also be an object whose key-value pairs are serialized to a query string.
*/
query?: string | Record<string, string | boolean>
/** Override the base path used for resolving patterns and keying results. */
base?: string
}
interface ImportMeta { interface ImportMeta {
/** /**
* The HMR API for ESM modules when using Turbopack. * The HMR API for ESM modules when using Turbopack.
...@@ -88,6 +105,29 @@ interface ImportMeta { ...@@ -88,6 +105,29 @@ interface ImportMeta {
* Only available in development mode. * Only available in development mode.
*/ */
turbopackHot?: TurbopackHotApi turbopackHot?: TurbopackHotApi
/**
* Import multiple modules at once using glob patterns (Turbopack only).
*
* @example
* // Lazy (default) — values are thunks: () => Promise<Module>
* const modules = import.meta.glob('./dir/*.js')
*
* // Eager — values are module objects
* const modules = import.meta.glob('./dir/*.js', { eager: true })
*/
glob(
pattern: string | string[],
options: ImportMetaGlobOptions & { eager: true }
): Record<string, unknown>
glob(
pattern: string | string[],
options?: ImportMetaGlobOptions & { eager?: false | undefined }
): Record<string, () => Promise<unknown>>
glob(
pattern: string | string[],
options?: ImportMetaGlobOptions
): Record<string, unknown> | Record<string, () => Promise<unknown>>
} }
interface Window { interface Window {
......
...@@ -58,6 +58,7 @@ turbopack-core = { workspace = true } ...@@ -58,6 +58,7 @@ turbopack-core = { workspace = true }
turbopack-resolve = { workspace = true } turbopack-resolve = { workspace = true }
turbopack-swc-utils = { workspace = true } turbopack-swc-utils = { workspace = true }
url = { workspace = true } url = { workspace = true }
urlencoding = { workspace = true }
swc_core = { workspace = true, features = [ swc_core = { workspace = true, features = [
"ecma_ast", "ecma_ast",
......
...@@ -172,7 +172,11 @@ pub fn parse_import_meta_glob( ...@@ -172,7 +172,11 @@ pub fn parse_import_meta_glob(
} }
Some("import") => { Some("import") => {
if let Some(s) = val.as_str() { if let Some(s) = val.as_str() {
// `import: '*'` means namespace import (whole module),
// which is the default behavior — no need to store it.
if s != "*" {
import = Some(s.into()); import = Some(s.into());
}
} else { } else {
handler.span_warn_with_code( handler.span_warn_with_code(
span, span,
...@@ -191,6 +195,51 @@ pub fn parse_import_meta_glob( ...@@ -191,6 +195,51 @@ pub fn parse_import_meta_glob(
format!("?{s}").into() format!("?{s}").into()
}; };
query = Some(q); query = Some(q);
} else if let JsValue::Object { parts, .. } = val {
// Support object form: { query: { bar: 'foo', raw: true } }
// Serializes to "?bar=foo&raw=true" with URL-encoding.
use crate::analyzer::ObjectPart;
let mut pairs: Vec<String> = Vec::new();
for part in parts {
if let ObjectPart::KeyValue(k, v) = part {
if let Some(k_str) = k.as_str() {
let enc_key = urlencoding::encode(k_str);
if let Some(v_str) = v.as_str() {
let enc_val = urlencoding::encode(v_str);
pairs.push(format!("{enc_key}={enc_val}"));
} else if let Some(v_bool) = v.as_bool() {
pairs.push(format!("{enc_key}={v_bool}"));
} else {
handler.span_warn_with_code(
span,
&format!(
"import.meta.glob() 'query' object \
value for key '{k_str}' must be a \
constant string or boolean, ignoring"
),
diagnostic_id.clone(),
);
}
} else {
handler.span_warn_with_code(
span,
"import.meta.glob() 'query' object keys must \
be constant strings",
diagnostic_id.clone(),
);
}
} else {
handler.span_warn_with_code(
span,
"import.meta.glob() 'query' object must only \
contain constant key-value pairs",
diagnostic_id.clone(),
);
}
}
if !pairs.is_empty() {
query = Some(format!("?{}", pairs.join("&")).into());
}
} else { } else {
handler.span_warn_with_code( handler.span_warn_with_code(
span, span,
...@@ -244,11 +293,12 @@ pub fn parse_import_meta_glob( ...@@ -244,11 +293,12 @@ pub fn parse_import_meta_glob(
} }
} }
_ => { _ => {
handler.span_warn_with_code( handler.span_err_with_code(
span, span,
"import.meta.glob() second argument must be an object literal", "import.meta.glob() second argument must be an object literal",
diagnostic_id.clone(), diagnostic_id.clone(),
); );
return None;
} }
} }
} }
...@@ -305,7 +355,7 @@ async fn flatten_read_glob(result: &ReadGlobResult) -> Result<Vec<(RcStr, FileSy ...@@ -305,7 +355,7 @@ async fn flatten_read_glob(result: &ReadGlobResult) -> Result<Vec<(RcStr, FileSy
let mut pending: Vec<(String, turbo_tasks::ReadRef<ReadGlobResult>)> = Vec::new(); let mut pending: Vec<(String, turbo_tasks::ReadRef<ReadGlobResult>)> = Vec::new();
collect_files(result, "", &mut files); collect_files(result, "", &mut files);
// Resolve child directories // Resolve child directories (skip dot-directories like .git, .next, etc.)
for (segment, inner_vc) in &result.inner { for (segment, inner_vc) in &result.inner {
let child_prefix = segment.to_string(); let child_prefix = segment.to_string();
let inner = inner_vc.await?; let inner = inner_vc.await?;
......
// These calls trigger compile-time errors (verified via issue snapshots).
// They are wrapped in functions to avoid runtime evaluation errors, since
// invalid glob calls are not transformed and would throw at runtime.
function getTooMany() {
return import.meta.glob('./dir/*.js', {}, {})
}
function getNumPattern() {
return import.meta.glob(123)
}
function getNonObjOptions() {
return import.meta.glob('./dir/*.js', 'eager')
}
it('should emit errors for invalid glob calls', () => {
// The compile-time errors are the main verification (issue snapshots).
// At runtime, these untransformed calls would throw.
expect(() => getTooMany()).toThrow()
expect(() => getNumPattern()).toThrow()
expect(() => getNonObjOptions()).toThrow()
})
warning - [analysis] /turbopack/crates/turbopack-tests/tests/execution/turbopack/resolving/import-meta-glob-errors/input/index.js:10:9 TP1008 import.meta.glob() first argument must be a string literal or array of string literals
6 | return import.meta.glob('./dir/*.js', {}, {})
7 | }
8 |
9 | function getNumPattern() {
+ v-------------------v
10 + return import.meta.glob(123)
+ ^-------------------^
11 | }
12 |
13 | function getNonObjOptions() {
14 | return import.meta.glob('./dir/*.js', 'eager')
\ No newline at end of file
warning - [analysis] /turbopack/crates/turbopack-tests/tests/execution/turbopack/resolving/import-meta-glob-errors/input/index.js:6:9 TP1008 import.meta.glob() requires 1 or 2 arguments
2 | // They are wrapped in functions to avoid runtime evaluation errors, since
3 | // invalid glob calls are not transformed and would throw at runtime.
4 |
5 | function getTooMany() {
+ v------------------------------------v
6 + return import.meta.glob('./dir/*.js', {}, {})
+ ^------------------------------------^
7 | }
8 |
9 | function getNumPattern() {
10 | return import.meta.glob(123)
\ No newline at end of file
error - [analysis] /turbopack/crates/turbopack-tests/tests/execution/turbopack/resolving/import-meta-glob-errors/input/index.js:14:9 TP1008 import.meta.glob() second argument must be an object literal
10 | return import.meta.glob(123)
11 | }
12 |
13 | function getNonObjOptions() {
+ v-------------------------------------v
14 + return import.meta.glob('./dir/*.js', 'eager')
+ ^-------------------------------------^
15 | }
16 |
17 | it('should emit errors for invalid glob calls', () => {
18 | // The compile-time errors are the main verification (issue snapshots).
\ No newline at end of file
...@@ -62,3 +62,66 @@ it('should support multiple patterns across directories', () => { ...@@ -62,3 +62,66 @@ it('should support multiple patterns across directories', () => {
expect(keys).toEqual(['./dir/bar.js', './dir/foo.js', './other/baz.js']) expect(keys).toEqual(['./dir/bar.js', './dir/foo.js', './other/baz.js'])
expect(multiModules['./other/baz.js'].default).toBe('baz') expect(multiModules['./other/baz.js'].default).toBe('baz')
}) })
// import: '*' (namespace import) — should return the whole module namespace
// Uses ./other/*.js to avoid colliding with the eager test above (same pattern + eager + no import)
const namespaceModules = import.meta.glob('./other/*.js', {
import: '*',
eager: true,
})
it('should return the whole module namespace with import: "*"', () => {
const keys = Object.keys(namespaceModules).sort()
expect(keys).toEqual(['./other/baz.js'])
// Each value is the full module namespace object
expect(namespaceModules['./other/baz.js'].default).toBe('baz')
expect(namespaceModules['./other/baz.js'].value).toBe(7)
})
// Negative pattern combined with query
const queryWithNeg = import.meta.glob(['./dir/*.js', '!**/bar.js'], {
query: '?raw',
import: '*',
})
it('should support query option with negative patterns', () => {
const keys = Object.keys(queryWithNeg)
expect(keys).toEqual(['./dir/foo.js'])
// Values are thunks (lazy mode)
expect(typeof queryWithNeg['./dir/foo.js']).toBe('function')
})
// query as object literal — serialized to query string
const queryObjModules = import.meta.glob('./dir/*.js', {
query: { bar: 'foo', raw: true },
})
it('should support query as object literal', () => {
const keys = Object.keys(queryObjModules).sort()
expect(keys).toEqual(['./dir/bar.js', './dir/foo.js'])
// Values are thunks (lazy)
expect(typeof queryObjModules['./dir/foo.js']).toBe('function')
})
// Dotfile directories are matched by wildcards (not excluded)
const dotfileGlob = import.meta.glob(['./**/*.js', '!./index.js'], {
eager: true,
})
it('should include dotfile directories with wildcard patterns', () => {
const keys = Object.keys(dotfileGlob).sort()
expect(keys).toEqual([
'./.foo/hidden.js',
'./dir/bar.js',
'./dir/foo.js',
'./other/baz.js',
])
})
// Dotfile directories targeted explicitly should be included
const dotfileExplicit = import.meta.glob('./.foo/*.js', { eager: true })
it('should include dotfile directories when explicitly targeted', () => {
const keys = Object.keys(dotfileExplicit)
expect(keys).toEqual(['./.foo/hidden.js'])
})
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment