SWR: React Hooks for Data Fetching

Common errors

• Error: useSWR is not a function

  cause Attempting to import `useSWR` as a named export when it is a default export.
  fix Change your import statement from `import { useSWR } from 'swr'` to `import useSWR from 'swr'`.

• TypeError: Cannot read properties of undefined (reading 'name') at Profile

  cause Attempting to access `data` before it's loaded, especially when not using Suspense, or when `data` is `undefined` due to an error or initial loading state.
  fix Always check for `isLoading` or `error` before accessing `data`. Example: `if (isLoading) return <div>loading...</div>; if (error) return <div>failed to load</div>; return <div>hello {data.name}!</div>`.

• Failed to compile. Module parse failed: Cannot assign to read only property 'exports' of object '#<Object>'

  cause Mixing CommonJS `require()` with an ESM-first library like SWR, or incorrect bundler configuration for ESM modules.
  fix Ensure your project uses `import` statements for SWR. If using Node.js, confirm `"type": "module"` is set in your `package.json` or use `.mjs` extensions for files importing SWR. Check bundler configuration (e.g., Webpack, Rollup) to correctly resolve ESM modules.

• Type 'undefined' is not assignable to type '...' when using data from useSWR with TypeScript and Suspense is enabled.

  cause When `suspense: true` is enabled, SWR guarantees `data` will always be defined at the component render point, but TypeScript might still infer it as `data | undefined` without proper configuration.
  fix Configure TypeScript by ensuring `"compilerOptions": { "exactOptionalPropertyTypes": true }` is not set to `false` if it conflicts. More practically, if `suspense: true` is used, TypeScript should infer `data` as non-nullable. If it doesn't, ensure your TypeScript version is compatible and explicitly assert type if necessary (e.g., `data!.name`), though this should ideally be avoided.

Warnings

• breaking SWR v2 introduced breaking changes related to the return shape of the `useSWR` hook, error handling, and `mutate` API. Specifically, `isValidating` was replaced with `isLoading` for initial data fetching state, and the `mutate` function no longer accepts `shouldRevalidate` as a direct boolean argument but as part of an options object.
  Fix: Review the SWR v2 migration guide on the official documentation. Update `isValidating` to `isLoading` for initial load checks. Adjust `mutate` calls to `mutate(key, data, { revalidate: false })` for preventing revalidation.
• breaking SWR transitioned to an ESM-first package distribution starting from v2. While CJS bundles are still provided for backward compatibility, ESM is the recommended way to import. Users with older tooling or specific CommonJS setups might face issues.
  Fix: Ensure your project is configured to handle ESM imports, especially for bundlers like Webpack or Rollup. For Node.js, ensure `"type": "module"` in `package.json` or use `.mjs` extensions. If strictly using CommonJS, explicit `require('swr/dist/index.cjs')` might be necessary, though not officially recommended.
• gotcha When using `useSWRImmutable`, global `refreshInterval` settings might still trigger revalidations. This can lead to unexpected data refreshes for data intended to be static.
  Fix: Ensure `useSWRImmutable` explicitly overrides any global `refreshInterval` via its options: `useSWRImmutable(key, fetcher, { refreshInterval: 0 })`. Version 2.4.0 and later should correctly handle this override, but explicit setting provides clarity and robustness.
• breaking Multiple critical RCE (Remote Code Execution) vulnerabilities (CVE-2025-55182, CVE-2025-55183, CVE-2025-55184) were identified and patched in version 2.3.8. These vulnerabilities could allow an attacker to execute arbitrary code.
  Fix: Immediately upgrade SWR to version 2.3.8 or newer to patch these critical security vulnerabilities. Review any potentially affected deployments for signs of compromise.
• gotcha When `useSWR` is enabled in Suspense mode (`suspense: true`), the `data` property will never be `undefined` (it will throw a Promise instead). Components must be wrapped in `<Suspense>` boundary. Misunderstanding this can lead to 'cannot read properties of undefined' errors.
  Fix: Always wrap components using `useSWR` with `suspense: true` in a `<Suspense>` boundary. Remove `if (isLoading)` or `if (!data)` checks as they are not needed; the component will only render once data is available. Handle errors using `error` boundary components.

Install

• npm install swr npm
• yarn add swr yarn
• pnpm add swr pnpm

Imports

• useSWR
  wrong:

  import { useSWR } from 'swr'

  correct:

  import useSWR from 'swr'

  The primary data fetching hook, `useSWR`, is a default export. Attempting to destructure it as a named export will result in an error.
• SWRConfig
  wrong:

  import SWRConfig from 'swr'

  correct:

  import { SWRConfig } from 'swr'

  `SWRConfig` is a named export used to provide global configurations to all `useSWR` hooks within its scope. Do not attempt to import it as a default export.
• useSWRImmutable
  wrong:

  import useSWRImmutable from 'swr'

  correct:

  import { useSWRImmutable } from 'swr'

  `useSWRImmutable` is a named export, functioning similarly to `useSWR` but for data that should not revalidate. Incorrectly importing it as default will cause issues.
• Key
  wrong:

  import { Key } from 'swr'

  correct:

  import type { Key } from 'swr'

  When importing types like `Key`, `Fetcher`, or `SWRResponse`, ensure to use `import type` for better type safety and to prevent accidental runtime imports.

Quickstart

Demonstrates basic data fetching using `useSWR` with a custom `fetcher` function, handling loading and error states for a user profile.

import useSWR from 'swr';

const fetcher = async (url) => {
  const res = await fetch(url);
  if (!res.ok) {
    const error = new Error('An error occurred while fetching the data.');
    error.info = await res.json();
    error.status = res.status;
    throw error;
  }
  return res.json();
};

function UserProfile() {
  // In a real application, you might use an environment variable for the base URL
  const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? 'https://api.example.com';
  const userId = '123'; // Example user ID
  const { data, error, isLoading } = useSWR(`${API_BASE_URL}/users/${userId}`, fetcher);

  if (error) return <div>Failed to load user data: {error.message}</div>;
  if (isLoading) return <div>Loading user profile...</div>;
  
  return (
    <div>
      <h1>User Profile</h1>
      <p>Name: {data.name}</p>
      <p>Email: {data.email}</p>
    </div>
  );
}

// Example of how to render it (e.g., in a React component tree)
// function App() {
//   return <UserProfile />;
// }
// export default App;