# Next Rspack

> Mantiene los paquetes @next/rspack-core y @next/rspack-binding: versión npm de @rspack/core, crates rspack_*, toolchain de Rust, compilación local y variable NEXT_RSPACK. No aplica a Turbopack.

Fuente: https://skillsagentes.com/skills/vercel/next.js/next-rspack
Markdown: https://skillsagentes.com/skills/vercel/next.js/next-rspack.md

Repositorio: https://github.com/vercel/next.js
Autor: vercel
Licencia: MIT
Actualizado: hace 2 meses
Coste de contexto: 111 tok instalada, 2k tok al activarse, 2k tok con todos los archivos del bundle
Bundle: 1 archivo, 8 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add vercel/next.js --skill next-rspack --agent claude-code
# Cursor
npx -y skills add vercel/next.js --skill next-rspack --agent cursor
# Codex
npx -y skills add vercel/next.js --skill next-rspack --agent codex
# Gemini CLI
npx -y skills add vercel/next.js --skill next-rspack --agent gemini
# Windsurf
npx -y skills add vercel/next.js --skill next-rspack --agent windsurf
# Cline
npx -y skills add vercel/next.js --skill next-rspack --agent cline
```

## Qué hace

- Mantiene los paquetes `@next/rspack-core` y `@next/rspack-binding`
- Cubre la actualización de la versión npm de `@rspack/core`, de los crates `rspack_*` y de la versión del toolchain de Rust
- Explica cómo compilar y enlazar para probar en local, y el uso de la variable `NEXT_RSPACK`
- Trae una lista de archivos clave, los comandos de test y el proceso de release

## Cuándo usarla

- Se editan `rspack/package.json`, `rspack/crates/binding/Cargo.toml`, `rspack/rust-toolchain.toml` o `packages/next-rspack/package.json`

## Cuándo no

- El `rust-toolchain.toml` de la raíz, que es de Turbopack

## Qué la activa

- "Actualiza la versión de @rspack/core"
- "Compila el binding de rspack en local"
- "¿Qué toolchain de Rust usa rspack?"

## Antes de instalar

- Es un skill interno del repositorio de Next.js.
- Necesita en el PATH: pnpm
- Variables de entorno: NEXT_RSPACK
- reads environment config

## Archivos

- SKILL.md — 8 KB

## SKILL.md

Reproducido tal cual desde vercel/next.js bajo MIT. Esta sección es el documento original y está en inglés.

# Next.js with Rspack

## When to Use

Use this skill when you need to:

- Upgrade `@rspack/core` npm package version
- Upgrade rspack crate dependency versions
- Upgrade Rust version in `rspack/rust-toolchain.toml` (rspack directory only)
- Fix Rspack-related compilation issues
- Develop Rspack-specific features in Next.js

> **⚠️ Scope Limitation**: This skill only applies to code and configuration under the `rspack/` directory. The `rust-toolchain.toml` in the repository root is for Turbopack and is outside the scope of this skill.

## Architecture Overview

### Package Structure

```
rspack/                          # Independent workspace (separate rust toolchain and npm releases)
├── Cargo.toml                   # Rust workspace configuration
├── rust-toolchain.toml          # Rust version configuration
├── package.json                 # @next/rspack-core package definition
├── lib/
│   ├── index.js                 # Exports @rspack/core + custom plugins
│   └── index.d.ts               # Type definitions
└── crates/
    └── binding/
        ├── Cargo.toml           # Rust crate dependencies (rspack_* crates)
        └── package.json         # @next/rspack-binding package definition

packages/
└── next-rspack/
    └── package.json             # References @next/rspack-core
```

### Dependency Graph

```
packages/next-rspack
    └── @next/rspack-core (rspack/package.json)
            ├── @rspack/core (npm dependency)
            └── @next/rspack-binding (rspack/crates/binding)
                    └── rspack_* crates (Cargo.toml dependencies)
```

### Version Mapping Rules

| @rspack/core npm version | rspack crate version | Notes                                             |
| ------------------------ | -------------------- | ------------------------------------------------- |
| `2.0.0-rc.0`             | `0.100.0-rc.0`       | npm major.minor maps to crate 0.(major\*50+minor) |
| `1.3.x`                  | `0.53.x`             | e.g., 1.3 → 0.53                                  |
| `1.2.x`                  | `0.52.x`             | e.g., 1.2 → 0.52                                  |

## Upgrade Process

### Step 1: Get Upstream Version Information

Query https://github.com/web-infra-dev/rspack to obtain:

- Target `@rspack/core` npm version
- Corresponding rspack crate version
- Rust channel version from `rust-toolchain.toml`

### Step 2: Update npm Dependencies

Edit `rspack/package.json`:

```json
{
  "dependencies": {
    "@rspack/core": "<new version>",
    "@next/rspack-binding": "workspace:*"
  }
}
```

### Step 3: Update Cargo.toml

Edit `rspack/crates/binding/Cargo.toml`, update all rspack crate versions:

```toml
[dependencies]
rspack_binding_builder        = { version = "=<new crate version>" }
rspack_binding_builder_macros = { version = "=<new crate version>" }
rspack_core                   = { version = "=<new crate version>" }
rspack_error                  = { version = "=<new crate version>" }
rspack_hook                   = { version = "=<new crate version>" }
rspack_plugin_externals       = { version = "=<new crate version>" }
rspack_regex                  = { version = "=<new crate version>" }
# rspack_sources version is managed separately, may not follow the main version

[target.'cfg(...)'.dependencies]
rspack_binding_builder = { version = "=<new crate version>", features = ["plugin"] }

[build-dependencies]
rspack_binding_build = { version = "=<new crate version>" }
```

### Step 4: Update Rust Toolchain

Edit `rspack/rust-toolchain.toml`:

```toml
[toolchain]
profile = "default"
components = ["rust-src"]
channel = "<nightly version matching upstream rspack>"
```

### Step 5: Verify Build

```bash
# Execute in rspack directory
cd rspack

# Check Rust code
cargo check

# Build binding (requires Rust installed)
pnpm build
```

### Step 6: Link to packages/next-rspack

`rspack/` is an independent workspace not included in the root pnpm-workspace, manual linking is required:

```bash
# Execute from repository root
cd packages/next-rspack

# Link locally built @next/rspack-core
pnpm link ../../rspack
```

Or modify `packages/next-rspack/package.json` to use local path (for local testing only, do not commit):

```json
{
  "dependencies": {
    "@next/rspack-core": "link:../../rspack"
  }
}
```

> **Important**: After linking, run `pnpm install` in the root directory to update dependency relationships.

### Step 7: Run Tests

```bash
# Execute from repository root
pnpm test-rspack
```

## Key Files Checklist

Files to check/modify during upgrade:

| File Path                            | Modification                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------- |
| `rspack/package.json`                | `@rspack/core` version, package version                                               |
| `rspack/crates/binding/Cargo.toml`   | rspack\_\* crate versions                                                             |
| `rspack/crates/binding/package.json` | binding package version                                                               |
| `rspack/rust-toolchain.toml`         | Rust nightly version                                                                  |
| `packages/next-rspack/package.json`  | `@next/rspack-core` version reference (update on release, use link for local testing) |

## Pre-requisites for Local Testing

Before running `pnpm test-rspack`, you must build and link `@next/rspack-core`:

```bash
# 1. Build @next/rspack-core
cd rspack
pnpm install
pnpm build

# 2. Link to packages/next-rspack
cd ../packages/next-rspack
pnpm link ../../rspack

# 3. Return to root and update dependencies
cd ../..
pnpm install

# 4. Run tests
pnpm test-rspack
```

> **Note**: After modifying Rust code under `rspack/`, you need to re-run `pnpm build` from step 1.

## Test Commands

```bash
# Full test suite (using Rspack compiler)
pnpm test-rspack

# Development mode tests
pnpm test-dev-rspack

# Production mode tests
pnpm test-start-rspack

# Run specific tests only
pnpm run with-rspack pnpm testonly -- <test-pattern>
```

All test commands set environment variables via `with-rspack`:

```bash
cross-env NEXT_RSPACK=1 NEXT_TEST_USE_RSPACK=1
```

## Development Notes

### Environment Variable Differentiation

Use the `NEXT_RSPACK` environment variable to differentiate compilers in `packages/next/` code:

```typescript
// Check if using Rspack
const isRspack = Boolean(process.env.NEXT_RSPACK)

if (process.env.NEXT_RSPACK) {
  // Rspack-specific logic
} else {
  // Webpack logic
}
```

### Common Code Locations

- Compiler selection logic: `packages/next/src/lib/bundler.ts`
- Webpack configuration: `packages/next/src/build/webpack-config.ts`
- Loader adaptations: `packages/next/src/build/webpack/loaders/`

### Custom Plugins

`@next/rspack-core` exports = `@rspack/core` + custom plugins:

- `NextExternalsPlugin` - externals handling plugin implemented in Rust

## Release Process

Release via GitHub Actions workflow:

- Workflow: `.github/workflows/release-next-rspack.yml`
- Supports dry-run mode
- Supports multiple npm tags (latest, alpha, beta, canary)

## References

- Upstream Rspack repository: https://github.com/web-infra-dev/rspack
- Rspack documentation: https://rspack.rs
- Next.js with Rspack example: `examples/with-rspack/`

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [vercel](https://skillsagentes.com/creators/vercel.md) — 36 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Next Cache Components Adoption](https://skillsagentes.com/skills/vercel/next.js/next-cache-components-adoption.md): Activa Cache Components en una app de Next.js y resuelve las rutas bloqueantes que aparecen. Úsalo para adoptar o migrar, activar el flag cacheComponents o decidir entre excluir rutas y arreglarlas.
- [Next Cache Components Optimizer](https://skillsagentes.com/skills/vercel/next.js/next-cache-components-optimizer.md): Lleva una ruta de Next.js a navegación instantánea bajo Cache Components o PPR mediante un bucle agéntico: codifica el objetivo como un e2e instant() en rojo y lo trabaja hasta verde, ruta a ruta.
- [Next Partial Prefetching Adoption](https://skillsagentes.com/skills/vercel/next.js/next-partial-prefetching-adoption.md): Activa Partial Prefetching en una app de Next.js y resuelve las insights que surgen: audita los Link con prefetch, activa partialPrefetching y opta por rutas con prefetch = 'partial'.
- [Next Dev Loop](https://skillsagentes.com/skills/vercel/next.js/next-dev-loop.md): Verifica el comportamiento en runtime de Next.js tras editar código de la aplicación. Combina /_next/mcp, la visión de Next.js, con agent-browser, la del navegador. Requiere un next dev en marcha.
- [Gh Stack](https://skillsagentes.com/skills/vercel/next.js/gh-stack.md): Gestiona PRs apilados y parte el trabajo en ramas revisables con gh-stack: creación, visualización, edición, push, envío, sincronización, rebase, merge y checkout.

## Skills relacionadas

- [Authoring Skills](https://skillsagentes.com/skills/vercel/next.js/authoring-skills.md): Cómo crear y mantener skills de agente en .agents/skills/. Úsalo al crear un SKILL.md, escribir descripciones, elegir campos de frontmatter o decidir qué va en un skill y qué en AGENTS.md.
- [Backport Pr](https://skillsagentes.com/skills/vercel/next.js/backport-pr.md): Lleva un pull request fusionado de Next.js desde canary a una rama de release anterior como next-16-2: localiza el commit, crea la rama, hace cherry-pick, valida y abre el PR.
- [Create Pr](https://skillsagentes.com/skills/vercel/next.js/create-pr.md): Crea ramas, commits, pushes y pull requests de GitHub para Next.js. Cubre la plantilla de PR, el formato de --body, las ramas codex/ y las directivas de git de la app Codex.
- [Dce Edge](https://skillsagentes.com/skills/vercel/next.js/dce-edge.md): Patrones de require() seguros para eliminación de código muerto y restricciones del runtime edge. Úsalo al escribir require condicionales, proteger imports de Node o editar define-env-plugin.ts.
- [Flags](https://skillsagentes.com/skills/vercel/next.js/flags.md): Cómo añadir o modificar flags experimentales de Next.js de principio a fin: tipo, esquema zod, inyección en build, paso de variables en runtime y elección entre ramificar o generar variantes.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)