Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Chakra UI v3 does not work in my Vite and React project

ErrorFailed to resolve import "@/components/ui/provider" from "src/main.tsx". Does the file exist?

Short answer

Chakra UI v3 is set up differently from v2. In a Vite app the usual breaks are an @/ alias that Vite cannot resolve, a provider file the CLI never generated, v2 code (the theme prop, extendTheme) that v3 removed, and imports from packages v3 dropped. The first error line tells them apart.

  • Applies to Chakra UI 3, Vite 7, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the first error line in the terminal or the browser console, because it decides the cause. Then check which Chakra version is installed and whether the generated provider file exists.

    npm ls @chakra-ui/react
    ls src/components/ui
  2. 2Match what you see, then jump to its fix

    1. 1Failed to resolve import "@/components/ui/provider" from "src/main.tsx". Does the file exist? (and the file does exist)Vite cannot resolve the @/ alias that the provider import usesFix
    2. 2The same Failed to resolve import error, and src/components/ui has no provider.tsxThe provider file was never generatedFix
    3. 3ChakraProvider receives theme={theme}, or a theme file calls extendThemeThe code still uses the v2 provider and theme APIFix
    4. 4An import of @chakra-ui/icons, useColorMode, ColorModeScript, Modal or StackItem does not resolve or no longer exists in v3Imports from packages and components that v3 removedFix

What does the error look like?

  • Failed to resolve import "@/components/ui/provider" from "src/main.tsx". Does the file exist?
  • An import of extendTheme, @chakra-ui/icons or useColorMode fails after moving a project from Chakra UI v2 to v3

Cause 1 of 4

Vite cannot resolve the @/ alias that the provider import uses

1Check

The setup guide imports the provider through @/. The alias has to exist on two sides: a paths entry in tsconfig.app.json for TypeScript, and a way for Vite to read it. Vite 7 and older need the vite-tsconfig-paths plugin for that second part; newer Vite has the resolve.tsconfigPaths option.

grep -n -A2 '"paths"' tsconfig.app.json
grep -n "tsconfigPaths\|tsconfig-paths" vite.config.ts

2Fix

Add the alias to tsconfig.app.json and connect it to Vite. On Vite 7 or lower install the plugin and add it to the plugin list; on a Vite version that has resolve.tsconfigPaths, set it to true instead.

npm i -D vite-tsconfig-paths

// tsconfig.app.json
"compilerOptions": {
  "paths": { "@/*": ["./src/*"] }
}

// vite.config.ts (Vite 7 or lower)
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [react(), tsconfigPaths()],
})

// vite.config.ts (newer Vite)
export default defineConfig({
  plugins: [react()],
  resolve: { tsconfigPaths: true },
})

3Verify

Restart the dev server and build once. The import must resolve in both.

npm run build

Confirmed by chakra-ui.com

Did this fix it?

Cause 2 of 4

The provider file was never generated

1Check

The provider the guide imports is not shipped in the npm package. The Chakra CLI generates it as a snippet, and the guide lists that step as optional, so it is easy to skip it and still copy the import from the next step.

ls src/components/ui

2Fix

Generate the snippets, or skip them and use ChakraProvider with the default system. The generated Provider also wraps next-themes for color mode; the direct form below has no color mode switching.

npx @chakra-ui/cli snippet add

// or, without snippets: src/main.tsx
import { ChakraProvider, defaultSystem } from '@chakra-ui/react'

<ChakraProvider value={defaultSystem}>
  <App />
</ChakraProvider>

3Verify

Start the dev server and render a Chakra Button on the page.

npm run dev

Confirmed by chakra-ui.com

Did this fix it?

Cause 3 of 4

The code still uses the v2 provider and theme API

1Check

In v3 the theme prop is gone. ChakraProvider takes a system through the value prop, and extendTheme is replaced by createSystem. Search the project for the old names.

grep -rnE "extendTheme|theme=\{" src

2Fix

Build the system with createSystem and defaultConfig, wrap every token value in an object with a value key, and pass the result through value.

// src/theme.ts
import { createSystem, defaultConfig, defineConfig } from '@chakra-ui/react'

const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        brand: { 500: { value: 'tomato' } },
      },
    },
  },
})

export const system = createSystem(defaultConfig, config)

// src/main.tsx
<ChakraProvider value={system}>

3Verify

Build the project and open a page that uses the brand color.

npm run build

Confirmed by chakra-ui.com

Did this fix it?

Cause 4 of 4

Imports from packages and components that v3 removed

1Check

The migration guide lists what was removed: the @chakra-ui/icons package, emotion styled and framer-motion as dependencies, the color mode hooks, Modal (now Dialog) and StackItem (use Box). Search for each name.

grep -rnE "@chakra-ui/icons|useColorMode|ColorModeScript|StackItem|<Modal" src

2Fix

Remove the unused packages, switch icons to react-icons or lucide-react, move color mode to next-themes, and rewrite each Modal with the compound Dialog components.

npm uninstall @emotion/styled framer-motion @chakra-ui/icons
npm i lucide-react

// before: import { SearchIcon } from '@chakra-ui/icons'
import { Search } from 'lucide-react'

3Verify

Run the build and confirm that no removed import is left.

npm run build

Confirmed by chakra-ui.com

Did this fix it?

How do I stop it coming back?

  • Follow the Vite page of the v3 docs from top to bottom, including the tsconfig step, instead of copying only the provider code.
  • Change the @/ alias in tsconfig and in the Vite side together whenever you rename the src folder.
  • Use Node.js 20 or newer; the v3 docs name it as the minimum.
  • When you upgrade a v2 project, search for each removed name from the migration guide before you start the dev server.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.