Quick Start instructions - vite@latest uses a newer version of React than inst-ui allows

[tylerclair]

Important note: if you are an Instructure employee please use Slack for bug reports/questions/feature requests. We can assist you much quicker and easier that way. If you are a third party user please ignore this message.

Background Information

Package Version(s):

@instructure/ui@10.19.0

Browser:

any

OS:

any

Device:

any

Component:

ui meta-package

Describe the Bug

The quick start instructions indicate to use npm create vite@latest my-cool-app. This results in an error where the ui meta-package, and I suspect all other packages, are only compatible with React 18.

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: version2@0.0.0
npm ERR! Found: react@19.1.0
npm ERR! node_modules/react
npm ERR!   react@"^19.1.0" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@">= 16.14 <= 18" from @instructure/ui@10.19.0
npm ERR! node_modules/@instructure/ui
npm ERR!   dev @instructure/ui@"^10" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 
npm ERR! 
npm ERR! For a full report see:
npm ERR! /home/user/.npm/_logs/2025-06-03T17_03_20_631Z-eresolve-report.txt

Steps To Reproduce

Follow the Quick Start here: https://instructure.design/#usage

1. Create a new react app npm create vite@latest my-cool-app
2. Select react as the framework and JavaScript as the variant
3. Add InstUI dependency "@instructure/ui": "^10" to package.json
4. Change the directory to the app cd my-cool-app
5. Run npm install

Expected Behavior

The npm install process should complete successfully

Screenshots

None

Additional Information

Current Workaround(s):

There are 2 workarounds I have found

1. Run npm with --force: npm install --force which produces lots of warnings
2. Specify the last Vite version that is compatible with react 18: npm create vite@6.0 my-cool-app

Products Affected:

Just any React apps we create with the latest version of React

Are you willing to submit a PR to fix?

• Yes, I'm willing to submit a PR

Requested Priority:

Normal

[matyasf]

hi!

Thanks for the report, we will fix this issue. We are actively working on supporting React 19, it should come out this summer.