Category: Learning

Prevent accidental form data loss and enhance user experience — one small, powerful hook at a time.

Introduction

In this article, we’ll walk through the journey of creating, enhancing, testing, and publishing a universally compatible React hook for saving form drafts in the browser: react-usedrafty.

Our goal was to:

• Build a plug-and-play solution for auto-saving and restoring form state.
• Make it framework-agnostic, working with React, Next.js, and React Router projects.
• Keep it lightweight with zero dependencies.
• Add real-world features like route-change warnings and customizable leave prompts.

---

Step 1 — Hook Requirements

From the initial idea, these requirements were set:

• Auto-save form data to localStorage or sessionStorage.
• Restore data on page reload.
• Warn the user before leaving if there are unsaved changes.
• Support Next.js and React Router route change detection.
• Provide clean API and TypeScript types.

---

Step 2 — Core Hook Implementation

We built the useDrafty hook in TypeScript, then configured the build to export both ESM and CJS formats for maximum compatibility.

Key features in the core:

• Storage type selection (local / session).
• Debounce saving.
• Restore on mount.
• Dirty-state detection.
• Configurable warnOnLeave with custom messages.
• Route change prevention via injected router instance.

Example API usage:

tsxCopyEdituseDrafty("contact-form", formState, setFormState, {
  storage: "local",
  delay: 1000,
  warnOnUnload: true,
  unloadMessage: "You have unsaved changes!",
  router: nextRouterOrReactRouter,
  onRestore: (data) => console.log("Draft restored:", data)
});

---

Step 3 — Adding Router Awareness

We avoided hard dependencies on Next.js or React Router by letting the user pass their router object.

Internally:

• For Next.js, we hook into router.events.on("routeChangeStart", cb).
• For React Router, we watch location changes.

This way:

• No extra packages are required.
• The hook works without any router if that feature is not needed.

---

Step 4 — Packaging for the World

We ensured compatibility by:

• Targeting ESNext but compiling to both ESM & CJS.
• Generating .d.ts files for TypeScript users.
• Writing a package.json with proper "exports" mapping.

Example "exports":

jsonCopyEdit"exports": {
  ".": {
    "import": "./dist/index.mjs",
    "require": "./dist/index.js",
    "types": "./dist/index.d.ts"
  }
}

We also configured:

• npm run build → Generates ESM, CJS, DTS.
• .npmignore → Excludes /example from the package.

---

Step 5 — Local Testing

We:

• Added an /example folder using Vite & React for quick testing.
• Made sure the package works by linking locally via:

bashCopyEditnpm link
npm link react-usedrafty

• Verified in plain React, Next.js, and React Router apps.

---

Step 6 — Publishing to npm

Version management steps:

bashCopyEdit# Update version
npm version patch  # or minor/major

# Publish
npm publish --access public

💡 Mistake: If you bump the wrong version, you can revert with:

bashCopyEditnpm version 1.2.2 --no-git-tag-version

---

Step 7 — Documentation

We created a detailed README including:

• Feature list.
• Install instructions.
• Basic & advanced usage.
• API reference.
• Changelog with new features (e.g., warnOnUnload, router support).

---

Step 8 — What’s New in the Latest Version

From this latest dev cycle, we added:

• Router-aware leave warnings (Next.js + React Router).
• Custom restore callback onRestore.
• Universal build that works across major JS environments.
• Debounce control for save frequency.
• Clear API for dirty-state detection (isDirty flag).

---

Conclusion

By following this process, we built a hook that:

• Works in React, Next.js, CRA, and other environments.
• Handles both browser unload and in-app route changes.
• Ships with full TypeScript types.
• Has local examples for quick testing.
• Is ready for npm publication with a clean API and docs.

This approach can be applied to any React utility you want to share with the community while keeping it framework-flexible.

---

Made with ❤️& Fire in heart
PRs and feedback welcome!