Contributing Workflow

Purpose and Scope

This page explains the contributor path for SWR: when to ask a question, when to open an issue, how to run the library locally against examples, and which package scripts are useful before sending a pull request. SWR is a React Hooks library for remote data fetching, so most code changes should be evaluated both as library changes and as user-facing behavior changes in React examples. The contribution guide emphasizes community discussion, reproducible bug reports, and local development through the repository’s example applications rather than treating the package as an isolated build artifact.

Sources: .github/CONTRIBUTING.md, README.md

SWR’s README frames the project around the stale-while-revalidate model and a single primary hook, useSWR, that returns cached data first, revalidates, and updates React components with fresh data. That framing matters for contributors because fixes and features should preserve speed, correctness, cache behavior, and React rendering semantics. When proposing changes, describe the user problem in terms of the data-fetching experience SWR promises: caching, request deduplication, focus and network revalidation, polling, pagination, SSR or SSG, optimistic mutation, retry behavior, TypeScript, Suspense, or React Native support.

Sources: README.md

Relevant Source Files

• .github/CONTRIBUTING.md — Defines the official contributor workflow for questions, bug reports, feature requests, pull requests, local example development, and documentation updates.
• README.md — Establishes SWR’s public purpose, key behavior, feature areas, quick-start hook shape, authorship, documentation link, and project license.
• package.json — Declares the package manager, package metadata, public package entrypoints, development scripts, test scripts, formatting and linting scripts, and release-adjacent scripts.
• pnpm-workspace.yaml — Defines the pnpm workspace package set used by this repository and records workspace-level build allowances and minimum release age policy.

Before Opening Code Changes

Start with the communication path that matches the work. If you have a usage question, feedback, or an experience to share, the contribution guide points readers to GitHub Discussions. If you found behavior that appears broken, first search the issue tracker to avoid duplicating an existing report. A new bug report should include a detailed description, expected behavior, and a reproduction such as a CodeSandbox link. That expectation is practical for a hooks library: many bugs depend on React rendering timing, cache state, fetcher behavior, or Next.js integration, and a reproduction gives maintainers a concrete scenario to validate.

Sources: .github/CONTRIBUTING.md

Feature work should also begin with discussion. The contribution guide asks contributors to get community feedback before implementing new features, either by opening an issue or starting a Discussions thread. Include context beyond the desired API: explain possible technical approaches, alternatives, and tradeoffs. This is especially important in SWR because an option or hook behavior can affect shared cache semantics, TypeScript inference, React Suspense behavior, server rendering behavior, or the public subpackage entrypoints. A well-scoped proposal helps reviewers decide whether the change belongs in core, middleware, examples, documentation, or a separate integration.

Sources: .github/CONTRIBUTING.md, package.json

Documentation changes have their own destination. The contribution guide says updates to the public SWR documentation site should be contributed to the website repository rather than this package repository. Keep repository changes focused on source, tests, examples, package metadata, and local docs that live here. If a code change requires public documentation, coordinate the code pull request with a corresponding documentation contribution so users can understand new options, changed behavior, migration notes, or newly supported usage patterns.

Sources: .github/CONTRIBUTING.md, README.md

Local Development Workflow

The official local development path runs SWR against one of the applications in the examples folder. The guide says to set up an example and run commands from the repository root so SWR and its dependencies are overridden to local assets. This is a useful pattern because it exercises the package as a consumer would import it, while still letting you iterate on local source changes. Before opening a pull request, use this loop to verify that the changed behavior is visible in a realistic React and Next.js environment instead of relying only on static inspection.

Sources: .github/CONTRIBUTING.md

corepack enable
corepack pnpm install
 
pnpm watch

corepack enable and corepack pnpm install align local installation with the package manager recorded in package.json, which specifies pnpm as the repository package manager. pnpm watch runs the watch build script declared in package.json, using bunchee -w so local package assets continue to update while you work. Keep this process running while using an example app, because the example consumes the locally built SWR assets and should reflect edits without a full manual rebuild after every source change.

Sources: .github/CONTRIBUTING.md, package.json

After the watch process is running, choose a target example. The contribution guide uses examples/basic as the concrete example and runs Next.js from the repository root. By default, the documented command starts the example in development mode. This flow is intentionally example-first: it makes it easy to reproduce a user-facing issue, adjust the library, and verify the fix where a React component calls SWR hooks. Use the same pattern with another example when the change affects pagination, optimistic UI, suspense, preloading, subscriptions, or other specialized behavior.

Sources: .github/CONTRIBUTING.md

pnpm next dev examples/basic

The same guide notes that all examples are built with Next.js, so normal Next.js commands are supported against an example directory. For changes that affect build output, SSR behavior, package exports, or production-only paths, run the build and start commands as part of local verification. Development mode can hide issues that only appear after bundling, so a production build is a useful extra check before asking maintainers to review a change that touches runtime entrypoints or integration behavior.

Sources: .github/CONTRIBUTING.md

pnpm next build examples/basic
pnpm next start examples/basic

Repository Scripts and Checks

package.json is the compact operational reference for contributors. The scripts include watch and build for bundled output, types:check for TypeScript project validation, lint and lint:fix for oxlint, format and format:check for oxfmt, test for Jest, coverage for Jest coverage, test:build for build-configured Jest tests, test:e2e for Playwright, and test-typing for the TypeScript test projects. The aggregate run-all-checks script runs types:check, lint, and test-typing, which makes it a good pre-review baseline when your change touches types or source conventions.

Sources: package.json

pnpm types:check
pnpm lint
pnpm test-typing
pnpm test
pnpm run-all-checks

Choose checks based on the scope of the change, then add broader validation when the change is near public behavior. A documentation-only fix may not need the full suite, but a change to hook behavior should at least run relevant unit tests and type checks. A change that affects package boundaries, generated output, or export conditions should also consider pnpm build, pnpm test:build, and pnpm attw, because package.json exposes multiple import, require, and react-server conditions across core and subpackages. The goal is to give reviewers confidence that the change works for both source-level development and published-package consumers.

Sources: package.json

Workspace and Package Boundaries

The workspace configuration lists package folders for _internal, core, immutable, infinite, and mutation. That means local development is not only about the root package script list; it also depends on pnpm resolving the repository’s package directories consistently. The same workspace file records allowed builds for selected dependencies and a minimum release age policy. Contributors normally do not need to edit these settings, but they should understand that dependency and workspace changes can affect installation behavior for everyone using the repository.

Sources: pnpm-workspace.yaml

package.json also shows the public package shape that code changes must respect. The root package exports the default SWR entrypoint, plus subpaths for swr/infinite, swr/immutable, swr/subscription, swr/mutation, and swr/_internal. Several entries distinguish ESM import, CommonJS require, TypeScript declaration files, and react-server conditions. If a contribution changes a subpackage API or build output, verify the relevant entrypoint rather than testing only import useSWR from 'swr'. This prevents regressions where one consumer path works while another published condition is broken.

Sources: package.json

Pull Request Readiness

A ready pull request should connect the original problem, the implementation, and the verification steps. For a bugfix, reference the issue or reproduction and explain why the new behavior matches expected SWR semantics. For a feature, link the prior discussion and call out API decisions or alternatives considered. Include the example you used for local validation, the scripts you ran, and any targeted tests or type checks. This keeps review focused on correctness and user impact rather than forcing maintainers to infer the scenario from code alone.

Sources: .github/CONTRIBUTING.md, package.json

Before submitting, also consider whether the change belongs in documentation or examples. The README points users to the full documentation and examples, while the contribution guide routes public documentation updates to the SWR website repository. If your code change alters common usage, add or update an example in this repository when appropriate, and open a corresponding documentation-site change for the public guide. Next, read the testing and release operations page for the broader CI expectations, or review the API page for the hook or subpackage your change touches.

Sources: .github/CONTRIBUTING.md, README.md