fog/.agents/skills/nx-import/references/TURBOREPO.md

Turborepo

• Nx replaces Turborepo task orchestration, but a clean migration requires handling Turborepo's config packages.
• Migration guide: https://nx.dev/docs/guides/adopting-nx/from-turborepo#easy-automated-migration-example
• Since Nx replaces Turborepo, all turbo config files and config packages become dead code and should be removed.

The Config-as-Package Pattern

Turborepo monorepos ship with internal workspace packages that share configuration:

• @repo/typescript-config (or similar) — tsconfig files (base.json, nextjs.json, react-library.json, etc.)
• @repo/eslint-config (or similar) — ESLint config files and all ESLint plugin dependencies

These are not code libraries. They distribute config via Node module resolution (e.g., "extends": "@repo/typescript-config/nextjs.json"). This is the default Turborepo pattern — expect it in virtually every Turborepo import. Package names vary — check package.json files to identify the actual names.

Check for Root Config Files First

Before doing any config merging, check whether the destination workspace uses shared root configuration. This decides how to handle the config packages.

• If the workspace has a root tsconfig.base.json and/or root eslint.config.mjs that projects extend, merge the config packages into these root configs (see steps below).
• If the workspace does NOT have root config files — each project manages its own configuration independently (similar to Turborepo). In this case, do not create root config files or merge into them. Just remove turbo-specific parts (turbo.json, eslint-plugin-turbo) and leave the config packages in place, or ask the user how they want to handle them.

If unclear, check for the presence of tsconfig.base.json at the root or ask the user.

Merging TypeScript Config (Only When Root tsconfig.base.json Exists)

The config package contains a hierarchy of tsconfig files. Each project extends one via package name.

1. Read the config package — trace the full inheritance chain (e.g., nextjs.json extends base.json).
2. Update root tsconfig.base.json — absorb compilerOptions from the base config. Add Nx paths for cross-project imports (Turborepo doesn't use path aliases, Nx relies on them).
3. Update each project's tsconfig.json:
   • Change "extends" from "@repo/typescript-config/<variant>.json" to the relative path to root tsconfig.base.json.
   • Inline variant-specific overrides from the intermediate config (e.g., Next.js: "module": "ESNext", "moduleResolution": "Bundler", "jsx": "preserve", "noEmit": true; React library: "jsx": "react-jsx").
   • Preserve project-specific settings (outDir, include, exclude, etc.).
4. Delete the config package and remove it from all devDependencies.

Merging ESLint Config (Only When Root eslint.config Exists)

The config package centralizes ESLint plugin dependencies and exports composable flat configs.

1. Read the config package — identify exported configs, plugin dependencies, and inheritance.
2. Update root eslint.config.mjs — absorb base rules (JS recommended, TypeScript-ESLint, Prettier, etc.). Drop eslint-plugin-turbo.
3. Update each project's eslint.config.mjs — switch from importing @repo/eslint-config/<variant> to extending the root config, adding framework-specific plugins inline.
4. Move ESLint plugin dependencies from the config package to root devDependencies.
5. If @nx/eslint plugin is configured with inferred targets, remove "lint" scripts from project package.json files.
6. Delete the config package and remove it from all devDependencies.

General Cleanup

• Remove turbo-specific dependencies: turbo, eslint-plugin-turbo.
• Delete all turbo.json files (root and per-package).
• Run workspace validation (nx run-many -t build lint test typecheck) to confirm nothing broke.

Key Pitfalls

• Trace the full inheritance chain before inlining — check what each variant inherits from the base.
• Module resolution changes — from Node package resolution (@repo/...) to relative paths (../../tsconfig.base.json).
• ESLint configs are JavaScript, not JSON — handle JS imports, array spreading, and plugin objects when merging.

Helpful docs:

• https://nx.dev/docs/guides/adopting-nx/from-turborepo