Installation and Package Entrypoints

Purpose and Scope

This page explains how the swr npm package is published and how consumers should choose among its public entrypoints. SWR is distributed as one package named swr, but that package exposes several subpaths for distinct hook families: the core hook, infinite loading, remote mutations, subscriptions, immutable fetching, and an internal helper surface. Understanding those entrypoints helps application authors write stable imports and helps library authors or maintainers reason about CommonJS, ESM, TypeScript declarations, and React Server Component-compatible builds.

The important distinction is that the subpaths are entrypoints inside the same package, not separate public packages to install independently. The root package manifest owns the package name, version, export map, included files, and build scripts. The small package manifests in directories such as infinite and mutation point package managers and bundlers at the built files under dist, while marking those directories as private. In normal application code, you install swr once, then import the subpath that matches the capability you need.

Sources: package.json, infinite/package.json, mutation/package.json, subscription/package.json, immutable/package.json, _internal/package.json

Relevant Source Files

• package.json — Defines the npm package name, version, description, top-level module fields, conditional exports, included package files, build scripts, and package manager metadata.
• _internal/package.json — Provides the private manifest for the internal subpath, pointing main, module, and types to the built _internal artifacts.
• infinite/package.json — Provides the private manifest for the swr/infinite subpath, pointing to the built infinite-loading JavaScript and type declarations.
• mutation/package.json — Provides the private manifest for the swr/mutation subpath, pointing to the built mutation JavaScript and type declarations.
• subscription/package.json — Provides the private manifest for the swr/subscription subpath, pointing to the built subscription JavaScript and type declarations.
• immutable/package.json — Provides the private manifest for the swr/immutable subpath, pointing to the built immutable JavaScript and type declarations.

Installation and Package Metadata

Install SWR as a single dependency. The package manifest identifies the package as swr, version 2.4.2, with the description React Hooks library for remote data fetching. That metadata is the source of truth for package managers and npm registry consumers. The keywords in the manifest also describe the intended search surface: swr, react, hooks, request, cache, and fetch. Those terms match the project’s public role as a React Hooks data-fetching library rather than a framework-specific client.

npm install swr
# or
pnpm add swr
# or
yarn add swr

For maintainers, the package manifest also records the expected package manager as pnpm@10.33.0 and contains scripts for build, type checking, linting, test execution, build tests, E2E tests, and prepublish preparation. Consumers do not need those scripts to import SWR, but they explain how the published artifacts are produced. The prepublishOnly script runs a clean build before publishing, while build uses bunchee to create the dist output referenced by the export map and subpackage manifests.

Sources: package.json

Module Formats and Conditional Exports

SWR supports both modern ESM importers and CommonJS require consumers. The legacy top-level fields map the root package to ./dist/index/index.js for main, ./dist/index/index.mjs for module, and ./dist/index/index.d.ts for types. These fields are still useful for older tooling, but the more precise contract is the exports map. Consumers should rely on package subpath imports such as swr, swr/infinite, and swr/mutation instead of deep-importing files from dist.

The root . export is conditional. For React Server Component-aware tooling, the react-server condition points at ./dist/index/react-server.mjs with matching .d.mts types. ESM importers receive ./dist/index/index.mjs with ./dist/index/index.d.mts, and CommonJS require consumers receive ./dist/index/index.js with ./dist/index/index.d.ts. This gives bundlers and TypeScript resolvers a consistent way to choose the correct artifact without forcing every consumer into the same module format.

Sources: package.json

Public Subpackage Entrypoints

The swr/infinite entrypoint is the public import path for infinite and paginated loading. The root export map sends ESM users to ./dist/infinite/index.mjs, CommonJS users to ./dist/infinite/index.js, and TypeScript users to the matching declaration files. It also has a react-server artifact at ./dist/infinite/react-server.mjs. The local infinite/package.json mirrors the built CommonJS, ESM, and declaration targets with paths relative to the subdirectory and marks the directory private, reinforcing that it is part of the main package rather than a separately installable npm module.

The swr/mutation entrypoint follows the same subpath pattern for remote mutation features. Its export map provides ESM, CommonJS, and type declaration targets under dist/mutation, and mutation/package.json points main, module, and types at those built files. Use this entrypoint when application code needs the mutation hook family rather than the core data-fetching hook alone. Keeping mutation in a subpath lets consumers import the mutation API explicitly while the package still ships as one npm dependency.

The swr/subscription entrypoint is for subscription-style integrations where an external source pushes updates into React state. The package export points to dist/subscription artifacts for ESM, CommonJS, and TypeScript declarations, and the private subscription/package.json repeats those build outputs for subpath compatibility. The examples documentation describes subscriptions as a way to subscribe async observable data into an app; the package layout supports that reader-facing capability through a dedicated import path instead of overloading the root import.

The swr/immutable entrypoint is similarly separated for immutable data-fetching behavior. Its manifest and export map point to dist/immutable JavaScript and declaration outputs. The absence of a react-server condition on this subpath in the supplied manifest is worth noting: the root package, infinite package, and internal package list explicit React Server artifacts, while immutable, subscription, and mutation expose import and require conditions. Consumers should let their bundler resolve the declared conditions instead of assuming every subpath has identical condition sets.

Sources: package.json, infinite/package.json, mutation/package.json, subscription/package.json, immutable/package.json

Internal Entrypoint and Published File Layout

The swr/_internal entrypoint is exported, but its name signals that it is not the primary application API. The export map includes a React Server build at ./dist/_internal/index.react-server.mjs, plus ESM and CommonJS targets with matching declarations. The private _internal/package.json points to ../dist/_internal/index.js, ../dist/_internal/index.mjs, and ../dist/_internal/index.d.ts. This structure supports SWR’s own package organization and advanced ecosystem usage while keeping ordinary application code focused on the documented public hook entrypoints.

The root manifest’s files list is also part of the installation contract. It includes dist, infinite, immutable, subscription, mutation, and _internal, which means the published package contains both the compiled output and the lightweight subpath package directories. The package is marked with sideEffects: false, allowing compatible bundlers to treat modules as tree-shakeable when imports are unused. That flag is a packaging promise, so maintainers should be careful not to add module-level side effects that would invalidate it.

Sources: package.json, _internal/package.json

Compact Reference

Practical Guidance and Next Steps

Application code should start with the root import when using the standard useSWR workflow, then add subpath imports only when a feature requires them. Use swr/infinite for load-more and infinite-scroll interfaces, swr/mutation for explicit remote write triggers, swr/subscription for observable or push-driven data sources, and swr/immutable for data that should be treated as stable after caching. Avoid importing directly from dist; the export map is the stable package boundary and contains the module-format and React Server conditions that tooling needs.

Maintainers changing entrypoints should update the root exports map and the matching private subdirectory manifest together. A mismatch between package.json and a subpath manifest can break consumers using different resolver strategies, especially TypeScript users or CommonJS consumers. After changing package metadata, run the repository’s build and type-oriented checks so the generated declaration files and JavaScript artifacts continue to match the declared entrypoints.

Related pages: quick-start, api-use-swr, api-use-swr-infinite, api-use-swr-mutation, api-use-swr-subscription, api-use-swr-immutable, suspense-ssr-and-rsc.