Single SPA Dependency Conflict Bug

Single SPA Dependency Conflict Bug

bug

When creating a new Single SPA React + TypeScript application using npx create-single-spa, the generated project has dependency conflicts that prevent npm install from completing successfully. Specifically, there's a version mismatch between React/React-DOM (v19.0.0) and their corresponding TypeScript types (v17.x), causing peer dependency conflicts with @testing-library/react.

Environment Information

• OS: Windows 11
• Node.js Version: v24.9.0
• npm Version: 11.6.0
• create-single-spa Version: 5.0.9
• Date: October 1, 2025

To Reproduce

1. Create a new directory for testing
2. Run npx create-single-spa
3. Select the following options:
   • Directory: test (or any name)
   • Type: single-spa application / parcel
   • Framework: react
   • Package manager: npm
   • TypeScript: Yes
   • Module format: systemjs
   • Organization name: test (or any valid name)
   • Project name: qc (or any valid name)

Expected behavior

The project should be created successfully with all dependencies properly resolved and npm install should complete without errors.

Actual behavior

The project is created, but npm install fails with dependency resolution errors.

Console Output

npm error ERESOLVE could not resolve
npm error
npm error While resolving: @testing-library/[email protected]
npm error Found: @types/[email protected]
npm error node_modules/@types/react
npm error   @types/react@"^17.0.19" from the root project
npm error   peer @types/react@"^17.0.0" from @types/[email protected]
npm error   node_modules/@types/react-dom
npm error     @types/react-dom@"^17.0.9" from the root project
npm error     peerOptional @types/react-dom@"*" from [email protected]
npm error     node_modules/single-spa-react
npm error       single-spa-react@"^6.0.2" from the root project
npm error   1 more (single-spa-react)
npm error
npm error Could not resolve dependency:
npm error peerOptional @types/react@"^18.0.0 || ^19.0.0" from @testing-library/[email protected]
npm error node_modules/@testing-library/react
npm error   dev @testing-library/react@"^16.0.1" from the root project
npm error
npm error Conflicting peer dependency: @types/[email protected]
npm error node_modules/@types/react
npm error   peerOptional @types/react@"^18.0.0 || ^19.0.0" from @testing-library/[email protected]
npm error   node_modules/@testing-library/react
npm error     dev @testing-library/react@"^16.0.1" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.

Root Cause Analysis

The generated package.json contains conflicting dependency versions:

React Dependencies:

"dependencies": {
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "@types/react": "^17.0.19",
  "@types/react-dom": "^17.0.9"
}

Testing Dependencies:

"devDependencies": {
  "@testing-library/react": "^16.0.1"
}

The issue is that:

1. React and React-DOM are set to version 19.0.0
2. @types/react and @types/react-dom are set to version 17.x (outdated)
3. @testing-library/[email protected] expects @types/react versions "^18.0.0 || ^19.0.0"

Proposed Solution

Update the generated package.json template to use compatible versions:

"dependencies": {
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "@types/react": "^19.0.0",
  "@types/react-dom": "^19.0.0"
}

Or alternatively, use React 18.x versions across the board for better stability:

"dependencies": {
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "@types/react": "^18.2.0",
  "@types/react-dom": "^18.2.0"
}

Workaround

Users can currently work around this issue by:

1. Using --legacy-peer-deps flag:

   bash复制

   npm install --legacy-peer-deps

   Result: ✅ This successfully installs all dependencies, though with some deprecation warnings:

   bash复制

   npm warn deprecated [email protected]: This version is no longer supported
   npm warn deprecated [email protected]: This module is not supported, and leaks memory
   added 943 packages, and audited 944 packages in 4m
   1 moderate severity vulnerability

2. Or manually updating the package.json to use compatible versions before running npm install.

Verification Steps Taken

1. ✅ Project creation completes successfully
2. ❌ npm install fails with dependency conflicts
3. ✅ npm install --legacy-peer-deps works as workaround
4. ❌ Project uses outdated ESLint version (7.32.0) which is no longer supported
5. ⚠️ 1 moderate security vulnerability detected

Additional Context

• This affects all new React + TypeScript projects created with create-single-spa
• The issue appears to be in the template generation logic that doesn't ensure version compatibility between React and its TypeScript definitions
• This makes the out-of-box experience poor for new users trying Single SPA for the first time

Files Affected

The issue is likely in the template files used by create-single-spa for React + TypeScript projects, specifically the package.json template generation.