A Typed Repository Layer for SharePoint CRUD in SPFx

Description and use

spfx-data-kit simplifies SharePoint CRUD in SPFx by providing a typed repository layer that abstracts PnPjs details, offers stable error handling, optimistic concurrency, and a local in‑memory adapter for testing.

Problem

Application code becomes repetitive and error‑prone when directly using PnPjs for SharePoint CRUD, as developers must repeatedly reference list names, internal field names, lookup expansions, ETag handling, response mapping, and error translation.

Outcome

spfx-data-kit reduces boilerplate, enforces consistent field mappings, provides typed inputs, stable error handling, and optimistic concurrency, while a local adapter enables unit testing without a tenant.

Workflow

• 1. Install spfx-data-kit and @pnp/sp v4.
• 2. Initialize the repository in SPFx component (e.g., in super.onInit()).
• 3. Use the repository’s CRUD methods (list, get, create, update, remove) with domain‑oriented objects.
• 4. Handle returned ETags for optimistic concurrency.
• 5. For local testing, use the in‑memory adapter to run contract tests without a tenant.
• 6. Deploy to production and connect the repository to real SharePoint lists.
• 7. Use TanStack Query for caching, refetching, and UI state management.
• 8. Validate permissions, field requirements, and live CRUD behavior against a real tenant.

Evidence

spfx-data-kit is not a replacement for PnPjs and does not attempt to cover all SharePoint APIs. It adds application‑level conventions: explicit domain‑to‑SharePoint field mapping; typed create and update inputs; stable error kinds; first‑class optimistic‑concurrency inputs through ETags; update re‑reads after SharePoint's possible 204 No Content response; bounded async paging; a local in‑memory adapter; cloning at local adapter boundaries.

Source

Verified locally: 9 deterministic tests passing; TypeScript build passing; no‑emission type check passing; package dry‑run passing; npm dependency audit reporting zero vulnerabilities; pre‑publish secret scrub passing.

Source