@firtoz/router-toolkit 0.1.1

package/README.md

@@ -0,0 +1,307 @@
+# @firtoz/router-toolkit
+
+Type-safe React Router 7 framework mode helpers with enhanced fetching, form submission, and state management.
+
+## Features
+
+- ✅ **Type-safe routing** - Full TypeScript support with React Router 7 framework mode
+- 🚀 **Enhanced fetching** - Dynamic fetchers with caching and query parameter support
+- 📝 **Form submission** - Type-safe form handling with Zod validation
+- 🔄 **State tracking** - Monitor fetcher state changes with ease
+- 🎯 **Zero configuration** - Works out of the box with React Router 7
+- 📦 **Tree-shakeable** - Import only what you need
+
+## Installation
+
+```bash
+npm install @firtoz/router-toolkit
+# or
+yarn add @firtoz/router-toolkit
+# or
+pnpm add @firtoz/router-toolkit
+# or
+bun add @firtoz/router-toolkit
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```json
+{
+  "react": "^18.0.0 || ^19.0.0",
+  "react-router": "^7.0.0",
+  "zod": "^4.0.0"
+}
+```
+
+## Hooks
+
+### `useDynamicFetcher`
+
+Enhanced version of React Router's `useFetcher` with type safety and additional features.
+
+```tsx
+import { useDynamicFetcher } from '@firtoz/router-toolkit';
+
+function MyComponent() {
+  const fetcher = useDynamicFetcher('/api/users');
+
+  const handleFetch = () => {
+    // Basic fetch
+    fetcher.load();
+    
+    // Fetch with query parameters
+    fetcher.load({ page: '1', limit: '10' });
+  };
+
+  return (
+    <div>
+      {fetcher.state === 'loading' && <p>Loading...</p>}
+      {fetcher.data && <pre>{JSON.stringify(fetcher.data, null, 2)}</pre>}
+      <button onClick={handleFetch}>Fetch Data</button>
+    </div>
+  );
+}
+```
+
+### `useCachedFetch`
+
+Regular fetch-based hook that avoids route invalidation and provides caching.
+
+```tsx
+import { useCachedFetch } from '@firtoz/router-toolkit';
+
+function CachedComponent() {
+  const { data, isLoading, error } = useCachedFetch('/api/static-data');
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return <div>{JSON.stringify(data)}</div>;
+}
+```
+
+### `useDynamicSubmitter`
+
+Type-safe form submission with Zod validation and enhanced submit functionality.
+
+```tsx
+import { useDynamicSubmitter } from '@firtoz/router-toolkit';
+import { z } from 'zod/v4';
+
+const formSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+});
+
+function ContactForm() {
+  const submitter = useDynamicSubmitter('/api/contact');
+
+  const handleSubmit = (formData: z.infer<typeof formSchema>) => {
+    submitter.submit(formData, { method: 'POST' });
+  };
+
+  return (
+    <submitter.Form method="POST">
+      <input name="name" type="text" />
+      <input name="email" type="email" />
+      <button type="submit">Submit</button>
+    </submitter.Form>
+  );
+}
+```
+
+### `useFetcherStateChanged`
+
+Track changes in fetcher state and react to them.
+
+```tsx
+import { useFetcher } from 'react-router';
+import { useFetcherStateChanged } from '@firtoz/router-toolkit';
+
+function StateTracker() {
+  const fetcher = useFetcher();
+
+  useFetcherStateChanged(fetcher, (lastState, newState) => {
+    console.log(`State changed from ${lastState} to ${newState}`);
+    
+    if (newState === 'idle' && lastState === 'submitting') {
+      // Handle successful submission
+      console.log('Form submitted successfully!');
+    }
+  });
+
+  return (
+    <fetcher.Form method="POST" action="/api/submit">
+      <button type="submit">Submit</button>
+      <p>Current state: {fetcher.state}</p>
+    </fetcher.Form>
+  );
+}
+```
+
+## Type Helpers
+
+### `Func`
+
+Generic function type helper for route loaders and actions.
+
+```tsx
+import type { Func } from '@firtoz/router-toolkit/types';
+
+// Usage in route modules
+type RouteModule = {
+  file: keyof Register["pages"];
+  loader: Func;
+};
+```
+
+### `HrefArgs`
+
+Type helper for extracting href arguments from route paths.
+
+```tsx
+import type { HrefArgs } from '@firtoz/router-toolkit/types';
+
+// Usage for type-safe routing
+type ProfileArgs = HrefArgs<'/profile/:id'>;
+// ProfileArgs is [{ id: string }]
+```
+
+## Usage with React Router 7 Framework Mode
+
+This toolkit is specifically designed for React Router 7's framework mode. Make sure your routes are properly typed in your `react-router.config.ts`:
+
+```tsx
+// react-router.config.ts
+import type { Config } from '@react-router/dev/config';
+
+export default {
+  // Your config
+} satisfies Config;
+
+// This will generate the Register types that the toolkit relies on
+```
+
+## Examples
+
+### Complete Form with Validation
+
+```tsx
+import { useDynamicSubmitter } from '@firtoz/router-toolkit';
+import { z } from 'zod/v4';
+
+const userSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.string().email('Invalid email'),
+  age: z.number().min(18, 'Must be 18 or older'),
+});
+
+function UserForm() {
+  const submitter = useDynamicSubmitter('/api/users');
+
+  return (
+    <div>
+      <h2>Create User</h2>
+      
+      <submitter.Form method="POST">
+        <div>
+          <label htmlFor="name">Name:</label>
+          <input name="name" type="text" required />
+        </div>
+        
+        <div>
+          <label htmlFor="email">Email:</label>
+          <input name="email" type="email" required />
+        </div>
+        
+        <div>
+          <label htmlFor="age">Age:</label>
+          <input name="age" type="number" required />
+        </div>
+        
+        <button type="submit" disabled={submitter.state === 'submitting'}>
+          {submitter.state === 'submitting' ? 'Creating...' : 'Create User'}
+        </button>
+      </submitter.Form>
+
+      {submitter.data && (
+        <div>
+          <h3>Success!</h3>
+          <p>User created: {JSON.stringify(submitter.data)}</p>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Data Fetching with Error Handling
+
+```tsx
+import { useDynamicFetcher, useFetcherStateChanged } from '@firtoz/router-toolkit';
+import { useEffect, useState } from 'react';
+
+function UserList() {
+  const fetcher = useDynamicFetcher('/api/users');
+  const [error, setError] = useState<string | null>(null);
+
+  useFetcherStateChanged(fetcher, (lastState, newState) => {
+    if (newState === 'idle' && fetcher.data?.error) {
+      setError(fetcher.data.error);
+    } else if (newState === 'loading') {
+      setError(null);
+    }
+  });
+
+  useEffect(() => {
+    fetcher.load();
+  }, []);
+
+  const refetch = () => {
+    fetcher.load({ refresh: 'true' });
+  };
+
+  return (
+    <div>
+      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+        <h2>Users</h2>
+        <button onClick={refetch} disabled={fetcher.state === 'loading'}>
+          {fetcher.state === 'loading' ? 'Loading...' : 'Refresh'}
+        </button>
+      </div>
+
+      {error && (
+        <div style={{ color: 'red', padding: '10px', background: '#fee' }}>
+          Error: {error}
+        </div>
+      )}
+
+      {fetcher.data?.users && (
+        <ul>
+          {fetcher.data.users.map((user: any) => (
+            <li key={user.id}>
+              {user.name} ({user.email})
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © [Firtina Ozbalikchi](https://github.com/firtoz)
+
+## Links
+
+- [GitHub Repository](https://github.com/firtoz/router-toolkit)
+- [NPM Package](https://npmjs.com/package/@firtoz/router-toolkit)
+- [React Router Documentation](https://reactrouter.com) 

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@firtoz/router-toolkit",
+  "version": "0.1.1",
+  "description": "Type-safe React Router 7 framework mode helpers with enhanced fetching, form submission, and state management",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
+    },
+    "./*": {
+      "types": "./src/*",
+      "import": "./src/*",
+      "require": "./src/*"
+    }
+  },
+  "files": [
+    "src/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "echo 'No build step - using TypeScript source directly'",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "echo 'No tests yet'"
+  },
+  "keywords": [
+    "react-router",
+    "react-router-7",
+    "framework-mode",
+    "hooks",
+    "typescript",
+    "form-submission",
+    "fetching",
+    "type-safe"
+  ],
+  "author": "Firtina Ozbalikchi <firtoz@github.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/firtoz/router-toolkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/firtoz/router-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/firtoz/router-toolkit/issues"
+  },
+  "peerDependencies": {
+    "react": "^19.1.0",
+    "react-router": "^7.6.3",
+    "zod": "^3.25.69"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "react": "^19.1.0",
+    "react-router": "^7.6.3",
+    "typescript": "^5.8.3",
+    "zod": "^3.25.74"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// Hooks
+export { useDynamicFetcher, useCachedFetch } from "./useDynamicFetcher";
+export { useDynamicSubmitter } from "./useDynamicSubmitter";
+export { useFetcherStateChanged } from "./useFetcherStateChanged";
+
+// Types
+export type { Func, HrefArgs, RoutePath } from "./types"; 

package/src/types/Func.ts

@@ -0,0 +1,2 @@
+// biome-ignore lint/suspicious/noExplicitAny: We really want to use any here
+export type Func = (...args: any[]) => unknown; 

package/src/types/HrefArgs.ts

@@ -0,0 +1,18 @@
+import type { href, Register } from "react-router";
+
+type AnyParams = Record<string, string | undefined>;
+type AnyPages = Record<string, {
+    params: AnyParams;
+}>;
+
+export type RegisterPages = Register extends {
+    pages: infer Registered extends AnyPages;
+} ? Registered : AnyPages;
+
+export type HrefArgs<T extends keyof RegisterPages> = Parameters<typeof href<T>> extends [
+	string,
+	...infer Rest,
+]
+	? Rest
+	: [];export type RoutePath<TPath extends keyof RegisterPages> = TPath;
+ 

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export type { Func } from "./Func";
+export type { HrefArgs } from "./HrefArgs";
+export type { RoutePath } from "./RoutePath"; 

package/src/useDynamicFetcher.ts

@@ -0,0 +1,127 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { href, useFetcher, type useLoaderData } from "react-router";
+import type { Func } from "./types/Func";
+import type { HrefArgs, RegisterPages } from "./types/HrefArgs";
+
+type RouteModule = {
+	file: keyof RegisterPages;
+	loader: Func;
+};
+
+export const useDynamicFetcher = <TInfo extends RouteModule>(
+	path: TInfo["file"],
+	...args: TInfo["file"] extends "undefined" ? HrefArgs<"/"> : HrefArgs<TInfo["file"]>
+): Omit<ReturnType<typeof useFetcher<TInfo["loader"]>>, "load" | "submit"> & {
+	load: (queryParams?: Record<string, string>) => Promise<void>;
+} => {
+	const url = useMemo(() => {
+		return href<typeof path>(path, ...args);
+	}, [path, args]);
+
+	const fetcher = useFetcher<TInfo["loader"]>({
+		key: `fetcher-${url}`,
+	});
+
+	const load = useCallback(
+		(queryParams?: Record<string, string>) => {
+			if (!queryParams || Object.keys(queryParams).length === 0) {
+				return fetcher.load(url);
+			}
+
+			// Build URL with query parameters
+			const urlObj = new URL(url, window.location.origin);
+			for (const [key, value] of Object.entries(queryParams)) {
+				urlObj.searchParams.set(key, value);
+			}
+
+			return fetcher.load(urlObj.pathname + urlObj.search);
+		},
+		[fetcher.load, url],
+	);
+
+	return {
+		...fetcher,
+		load,
+	};
+};
+
+// Cache for the useCachedFetch hook (regular fetch, not useFetcher)
+const fetchCache = new Map<string, unknown>();
+
+// Hook that uses regular fetch instead of useFetcher to avoid route invalidation
+export const useCachedFetch = <
+	TInfo extends {
+		file: string;
+		module: RouteModule;
+	},
+>(
+	path: TInfo["file"] extends "undefined"
+		? "/"
+		: `/${TInfo["file"]}` extends keyof RegisterPages
+		? `/${TInfo["file"]}`
+		: never,
+	...args: TInfo["file"] extends "undefined"
+		? HrefArgs<"/">
+		: `/${TInfo["file"]}` extends keyof RegisterPages
+		? HrefArgs<`/${TInfo["file"]}`>
+		: never
+): {
+	data: ReturnType<typeof useLoaderData<TInfo["module"]["loader"]>> | undefined;
+	isLoading: boolean;
+	error: Error | undefined;
+} => {
+	// Generate URL using href, same as useDynamicFetcher
+	const url = useMemo(() => {
+		// biome-ignore lint/suspicious/noExplicitAny: Complex conditional typing prevents TypeScript from inferring args when spreading
+		return href<typeof path>(path, ...(args as any));
+	}, [path, args]);
+
+	// Use the generated URL as the cache key
+	const cacheKey = url;
+
+	// Local state
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState<Error | undefined>(undefined);
+	const [data, setData] = useState<
+		ReturnType<typeof useLoaderData<TInfo["module"]["loader"]>> | undefined
+	>(() =>
+		fetchCache.has(cacheKey)
+			? (fetchCache.get(cacheKey) as ReturnType<typeof useLoaderData<TInfo["module"]["loader"]>>)
+			: undefined,
+	);
+
+	// Auto-fetch on mount or when URL changes, if not in cache
+	useEffect(() => {
+		const fetchData = async () => {
+			// Skip fetch if data is already cached
+			if (fetchCache.has(cacheKey)) {
+				return;
+			}
+
+			setIsLoading(true);
+			setError(undefined);
+
+			try {
+				const response = await fetch(url);
+
+				if (!response.ok) {
+					throw new Error(`HTTP error! Status: ${response.status}`);
+				}
+
+				const result = await response.json();
+
+				// Update cache and state
+				fetchCache.set(cacheKey, result);
+				setData(result as ReturnType<typeof useLoaderData<TInfo["module"]["loader"]>>);
+			} catch (err) {
+				setError(err instanceof Error ? err : new Error(String(err)));
+			} finally {
+				setIsLoading(false);
+			}
+		};
+
+		fetchData();
+	}, [url, cacheKey]);
+
+	return { data, isLoading, error };
+}; 

package/src/useDynamicSubmitter.tsx

@@ -0,0 +1,74 @@
+import { useCallback, useMemo } from "react";
+import {
+	type FetcherFormProps,
+	href,
+	type SubmitOptions,
+	type SubmitTarget,
+	useFetcher,
+} from "react-router";
+import type { z } from "zod/v4";
+import { HrefArgs, RegisterPages } from "./types/HrefArgs";
+import { Func } from "./types";
+
+type RouteModule = {
+	file: keyof RegisterPages;
+	action: Func;
+	formSchema: z.ZodTypeAny;
+};
+
+type SubmitFunc<TModule extends RouteModule> = (
+	target: z.infer<TModule["formSchema"]> & SubmitTarget,
+	options: Omit<SubmitOptions, "action" | "method" | "encType"> & {
+		method: Exclude<SubmitOptions["method"], "GET">;
+	},
+) => Promise<void>;
+
+type SubmitForm = (
+	props: Omit<FetcherFormProps & React.RefAttributes<HTMLFormElement>, "action" | "method"> & {
+		method: Exclude<SubmitOptions["method"], "GET">;
+	},
+) => React.ReactElement;
+
+export const useDynamicSubmitter = <TInfo extends RouteModule>(
+	path: TInfo["file"],
+	...args: TInfo["file"] extends "undefined" ? HrefArgs<"/"> : HrefArgs<TInfo["file"]>
+): Omit<ReturnType<typeof useFetcher<TInfo["action"]>>, "load" | "submit" | "Form"> & {
+	submit: SubmitFunc<TInfo>;
+	Form: SubmitForm;
+} => {
+	const url = useMemo(() => {
+		// biome-ignore lint/suspicious/noExplicitAny: We are sure the args are correct
+		return href<typeof path>(path, ...(args as any));
+	}, [path, args]);
+
+	const fetcher = useFetcher<TInfo["action"]>({
+		key: `submitter-${url}`,
+	});
+
+	const submit: SubmitFunc<TInfo> = useCallback(
+		(target, options) => {
+			// console.log("Submitting form to", url, target, options);
+			return fetcher.submit(target, {
+				...options,
+				action: url,
+				encType: "multipart/form-data",
+			});
+		},
+		[fetcher.submit, url],
+	);
+
+	const OriginalForm = fetcher.Form;
+
+	const Form: SubmitForm = useCallback(
+		(props) => {
+			return <OriginalForm action={url} {...props} />;
+		},
+		[url, OriginalForm],
+	);
+
+	return {
+		...fetcher,
+		submit,
+		Form,
+	};
+};

package/src/useFetcherStateChanged.ts

@@ -0,0 +1,21 @@
+import { useEffect, useRef } from "react";
+import type { useFetcher } from "react-router";
+
+/**
+ * A hook that tracks changes in a fetcher's state and calls a callback when it changes.
+ * @param fetcher The fetcher instance to track
+ * @param onChange Callback that receives the previous state and new state when the state changes
+ */
+export const useFetcherStateChanged = (
+	fetcher: Pick<ReturnType<typeof useFetcher>, "state">,
+	onChange: (lastState: typeof fetcher.state | undefined, newState: typeof fetcher.state) => void,
+) => {
+	const lastStateRef = useRef<typeof fetcher.state>(fetcher.state);
+
+	useEffect(() => {
+		if (lastStateRef.current !== fetcher.state) {
+			onChange(lastStateRef.current, fetcher.state);
+			lastStateRef.current = fetcher.state;
+		}
+	}, [fetcher.state, onChange]);
+};