[BUG] Can't launch Refine app from `create refine-app@latest` template generated with Next.js + shadcn due to error with `localStorage`

[cpolish]

Describe the bug

When creating an app using pnpm create refine-app@latest, and opting to create a Next.js application with shadcn for UI components, after attempting to start the app via pnpm dev and accessing the homepage at http://localhost:3000, the page fails to load with a 500 server error.

The terminal logs indicate that this is due to a unhandledRejection occurring due to a TypeError being thrown: specifically, the logs indicate this is due to localStorage.getItem not being considered a function ([TypeError: localStorage.getItem is not a function]).

When searching through the generated template codebase, I could only find one instance where localStorage.getItem was referenced: in src/components/refine-ui/theme/theme-provider.tsx. Commenting this usage of localStorage.getItem out does not resolve the issue.

Steps To Reproduce

1. Run pnpm create refine-app@latest to begin the new Refine app template wizard.
2. Select "Next.js" for the project template.
3. Name the project.
4. Select "REST API" as the data provider.
5. Select "shadcn/ui" as the UI framework.
6. Select "Yes" for example pages to be added.
7. Select "None" for the auth provider.
8. Select "pnpm" for the package manager.
9. Skip adding an email.
10. Navigate to the generate project directory, run pnpm dev, and in the browser, navigate to http://localhost:3000.
11. You should see that the page fails to load with a 500 error, and the terminal will show that this is due to a [TypeError: localStorage.getItem is not a function] occurring when compiling pages.
12. Comment out any reference to localStorage in src/components/refine-ui/theme/theme-provider.tsx, and save this file.
13. Close and restart the server (with pnpm dev), and navigate to http://localhost:3000.
14. You should still see the same 500 error page in the browser, and the same error messages in the terminal logs.

Expected behavior

The app should launch without any errors, and I should be able to access the template admin panel in the browser to play around with the app.

Packages

System:

• OS: macOS 15.7.3
• CPU: (14) arm64 Apple M4 Pro

Binaries:

• Node: 25.2.1 - /opt/homebrew/bin/node
• Yarn: Not Found
• npm: 11.6.2 - /opt/homebrew/bin/npm

Browsers:

• Chrome: Not Found
• Firefox: 146.0.1
• Safari: 26.2

Refine Packages:

• @refinedev/cli: 2.16.50
• @refinedev/core: 5.0.7
• @refinedev/devtools: 2.0.3
• @refinedev/kbar: 2.0.1
• @refinedev/nextjs-router: 7.0.4
• @refinedev/react-hook-form: 5.0.3
• @refinedev/react-router: 2.0.3
• @refinedev/react-table: 6.0.1
• @refinedev/simple-rest: 6.0.

Additional Context

The terminal log after running the app with pnpm dev:

✓ Ready in 1959ms
 ○ Compiling / ...
 ✓ Compiled / in 2.2s (1583 modules)
 ⨯ [TypeError: localStorage.getItem is not a function] {
  digest: '9055150'
}
[TypeError: localStorage.getItem is not a function]
 ⨯ [TypeError: localStorage.getItem is not a function] { page: '/' }
(node:91012) Warning: `--localstorage-file` was provided without a valid path
(Use `node --trace-warnings ...` to show where the warning was created)
 ○ Compiling /_error ...
 ✓ Compiled /_error in 1028ms (1917 modules)
[TypeError: localStorage.getItem is not a function]
[TypeError: localStorage.getItem is not a function]
 ⨯ [TypeError: localStorage.getItem is not a function]
 ⨯ [TypeError: localStorage.getItem is not a function]
[TypeError: localStorage.getItem is not a function]
 ⨯ unhandledRejection: [TypeError: localStorage.getItem is not a function]
 ⨯ unhandledRejection:  [TypeError: localStorage.getItem is not a function]
[TypeError: localStorage.getItem is not a function]
[TypeError: localStorage.getItem is not a function]
 ⨯ [TypeError: localStorage.getItem is not a function]
[TypeError: localStorage.getItem is not a function] { page: '/' }
[TypeError: localStorage.getItem is not a function]
 ⨯ unhandledRejection: [TypeError: localStorage.getItem is not a function]
 ⨯ unhandledRejection:  [TypeError: localStorage.getItem is not a function]
 GET / 500 in 5092ms
 GET / 500 in 212ms
 ✓ Compiled /_not-found in 436ms (1907 modules)
 ⨯ [TypeError: localStorage.getItem is not a function] {
  digest: '9055150'
}
[TypeError: localStorage.getItem is not a function]
 ⨯ [TypeError: localStorage.getItem is not a function]
[TypeError: localStorage.getItem is not a function]
[TypeError: localStorage.getItem is not a function]
 ⨯ [TypeError: localStorage.getItem is not a function]
[TypeError: localStorage.getItem is not a function]
[TypeError: localStorage.getItem is not a function]
 ⨯ unhandledRejection: [TypeError: localStorage.getItem is not a function]
 ⨯ unhandledRejection:  [TypeError: localStorage.getItem is not a function]
 GET /init 500 in 1001ms
 GET /init 500 in 239ms
 ✓ Compiled in 194ms (1061 modules)

[itsaryanchauhan]

I followed the exact steps to reproduce the reported issue on my system, but the application works without any errors.

System Configuration

• OS: macOS (MacBook Air M4)
• Node: v24.11.1
• npm: 11.6.2

Steps Followed

pnpm create refine-app@latest
# Selections: Next.js → REST API → shadcn/ui → Yes (examples) → None (auth) → pnpm
cd jjj
pnpm dev

Results

• ✅ App compiled successfully in 4.7s (1583 modules)
• ✅ Homepage loads at http://localhost:3000 without 500 errors
• ✅ No localStorage.getItem is not a function errors in terminal
• ✅ All routes work correctly (including /blog-posts)

Package Versions (Working Setup)

{
  "@refinedev/cli": "^2.16.48",
  "@refinedev/core": "^5.0.1",
  "@refinedev/nextjs-router": "^7.0.0",
  "next": "15.3.1",
  "react": "19.1.0"
}

---

Key Difference Analysis

The error in the original report includes the following line:

(node:91012) Warning: --localstorage-file was provided without a valid path

This warning does not appear in my output. This strongly suggests the issue is environment-specific:

1. Node v25 Specific: The original reporter is using Node v25.2.1, whereas I am using v24.11.1 (LTS).
2. Node v25 Breaking Change: The --localstorage-file flag suggests Node v25 may have introduced changes to how localStorage is polyfilled or mocked in server contexts.
3. Not a Refine Template Issue: Since the template works perfectly on Node v24, the source code itself is likely valid.

Recommendation

Can you test with Node LTS v24 to confirm this is a Node v25 compatibility issue?

# Switch to Node 24
nvm install 24
nvm use 24

# Clean install
rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm dev

If this resolves the issue, it should be reported as a Node v25 compatibility issue rather than a template bug. The Refine team may need to add specific handling for Node v25 or update the documentation regarding supported Node versions (currently listed as "node": ">=20" in package.json).

[rishi8815]

I was able to reproduce this issue on Node v25.x, and confirmed that it does not occur on Node v24 LTS.

This seems related to Node v25’s handling of localStorage in server environments (note the --localstorage-file warning).

I’m happy to work on either:

guarding localStorage usage for SSR, or

updating the template / docs to clarify Node v25 compatibility

Please let me know how you’d like to proceed.

[2200090246]

Hi, I can reproduce this issue on Node v25 as well.
I’d like to work on adding an SSR-safe guard for localStorage or updating the template/docs.
Please let me know if I can take this.