pjdev2d-cli 1.1.3 → 1.2.1

package/README.md

@@ -9,3 +9,9 @@ npx pjdev2d-cli add <name>
 ```bash
 npx pjdev2d-cli add tanstack-query-template
 ```
+
+# To add React Router Template
+
+```bash
+npx pjdev2d-cli add react-router-template
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pjdev2d-cli",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "type": "module",
   "description": "CLI to install reusable React components like shadcn/ui",
   "main": "bin/cli.js",
@@ -30,6 +30,7 @@
     "fs-extra": "^11.3.5",
     "inquirer": "^13.4.3",
     "react": "^19.2.6",
+    "react-router-dom": "^7.16.0",
     "tailwind-merge": "^3.6.0"
   }
 }

package/registry.json

@@ -8,5 +8,10 @@
     "name": "Tanstack Query",
     "category": "tanstack-query",
     "files": ["templates/tanstack-query"]
+  },
+  "react-router-template": {
+    "name": "React Router",
+    "category": "react-router",
+    "files": ["templates/react-router"]
   }
 }

package/templates/react-router/hook/useRouterSearch.ts

@@ -0,0 +1,131 @@
+import { useCallback, useMemo, useRef } from "react";
+import { useSearchParams } from "react-router-dom";
+
+export function useRouterSearch<T extends Record<string, any>>({
+  defaultParams,
+}: {
+  defaultParams: T;
+}) {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const defaultRef = useRef(defaultParams);
+  defaultRef.current = defaultParams;
+
+  const search = useMemo(() => {
+    const result = { ...defaultRef.current };
+    const keys = Object.keys(defaultRef.current);
+
+    for (const key of keys) {
+      const fallback = defaultRef.current[key];
+      if (Array.isArray(fallback)) {
+        const val = searchParams.getAll(key);
+        if (val.length > 0) {
+          result[key as keyof T] = parseValue(val, fallback) as any;
+        }
+      } else {
+        const val = searchParams.get(key);
+        if (val !== null) {
+          result[key as keyof T] = parseValue(val, fallback) as any;
+        }
+      }
+    }
+    return result;
+  }, [searchParams]);
+
+  const setSearch = useCallback(
+    (
+      updates: Partial<Record<keyof T, any>>,
+      options?: { resetPage?: boolean; replace?: boolean }
+    ) => {
+      const next = new URLSearchParams(searchParams);
+      const keys = Object.keys(defaultRef.current);
+
+      for (const key of keys) {
+        const value = updates[key as keyof T];
+        if (value !== undefined) {
+          if (value === null || areEqual(value, defaultRef.current[key])) {
+            next.delete(key);
+          } else if (Array.isArray(value)) {
+            next.delete(key);
+            value.forEach((val) => {
+              if (val !== undefined && val !== null && val !== "") {
+                next.append(key, String(val));
+              }
+            });
+          } else {
+            next.set(key, String(value));
+          }
+        }
+      }
+      /**
+       * Reset pagination
+       * when filters/search changes
+       */
+      if (options?.resetPage && "page" in defaultRef.current) {
+        next.delete("page");
+      }
+
+      setSearchParams(next, {
+        replace: options?.replace,
+      });
+    },
+    [searchParams, setSearchParams]
+  );
+
+  return { search, setSearch };
+}
+
+function areEqual(a: any, b: any) {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.every((val, index) => val === sortedB[index]);
+  }
+  return a === b;
+}
+
+function parseValue(value: string | string[], fallback: any): any {
+  if (Array.isArray(fallback)) {
+    const fallbackVal = fallback[0];
+    const valArray = Array.isArray(value) ? value : [value];
+    return valArray.map((item) => parseSingleValue(item, fallbackVal));
+  }
+  const singleVal = Array.isArray(value) ? value[0] : value;
+  return parseSingleValue(singleVal, fallback);
+}
+
+function parseSingleValue(value: string, fallback: any) {
+  if (typeof fallback === "number") {
+    const parsed = Number(value);
+    return Number.isNaN(parsed) ? fallback : parsed;
+  }
+
+  /**
+   * Boolean parsing
+   */
+  if (typeof fallback === "boolean") {
+    return value === "true";
+  }
+
+  /**
+   * String fallback
+   */
+  return value;
+}
+
+/*
+# NOTE: Array parameter usage example
+
+1. Define the default parameter as an array:
+   export const DefaultSearch = {
+     color: [] as string[],
+   };
+
+2. Set values (e.g., in a component):
+   setSearch({ color: ["red", "blue"] });
+   // Resulting URL query: ?color=red&color=blue
+
+3. Read values (e.g., in a component):
+   const colors = search.color; // Returns ["red", "blue"]
+*/

package/templates/react-router/router/guards/private.route.tsx

@@ -0,0 +1,56 @@
+import { Outlet } from "react-router-dom";
+
+export function PrivateRoute() {
+  return <Outlet />;
+}
+
+/* 
+# NOTE : use this when you want to redirect user to login page if he is already logged out.
+#        Includes the premium "Redirect Back" pattern to preserve user navigation state.
+
+import { Navigate, Outlet, useLocation } from "react-router-dom";
+
+export default function PrivateRoute() {
+  const token = getLocalAuthToken();
+  const location = useLocation();
+
+  if (!token) {
+    // Passes the requested path inside search params so you can redirect back after successful login
+    return (
+      <Navigate 
+        to={`/page_auth?redirectTo=${encodeURIComponent(location.pathname + location.search)}`} 
+        replace 
+      />
+    );
+  }
+  return <Outlet />;
+}
+
+# NOTE: HOW THE LOGIN COMPONENT CONSUMES THE "redirectTo" PARAMETER
+
+### The Bookmarking Lifecycle Flow:
+1. **Bookmarked Access:** A logged-out user tries to access a bookmarked private route directly:
+   `https://your-app.com/page_two`
+2. **Redirect to Auth:** The `PrivateRoute` guard intercepts the request, captures the target pathname (`/page_two`), and redirects them to the login screen with the target appended:
+   `https://your-app.com/page_auth?redirectTo=%2Fpage_two`
+3. **Login:** The user submits their login credentials.
+4. **Target Restoration:** Upon successful authentication, the Login page checks the URL for `redirectTo` and navigates the user straight to `/page_two` instead of the generic homepage `/`.
+
+### Code Implementation Example:
+```typescript
+import { useNavigate, useSearchParams } from "react-router-dom";
+
+export default function LoginPage() {
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+
+  const handleLoginSuccess = () => {
+    // 1. Read the redirectTo value (e.g., "/page_two") or default to "/"
+    const destination = searchParams.get("redirectTo") || "/";
+
+    // 2. Redirect the user back to their bookmarked page instead of the root page!
+    navigate(destination, { replace: true });
+  };
+}
+```
+*/

package/templates/react-router/router/guards/public.route.tsx

@@ -0,0 +1,21 @@
+import { Outlet } from "react-router-dom";
+
+export function PublicRoute() {
+  return <Outlet />;
+}
+
+/* 
+
+# NOTE : use this when you want to redirect user to main page if he is already logged in
+
+import { Navigate, Outlet } from "react-router-dom";
+
+export default function PublicRoute() {
+  const token = getLocalAuthToken();
+  if (token) {
+    return <Navigate to={PATH.desired_path_name} replace />;
+  }
+  return <Outlet />;
+}
+
+*/

package/templates/react-router/router/index.ts

@@ -0,0 +1,186 @@
+import { createBrowserRouter, RouteObject } from "react-router-dom";
+import { PATH } from "./path";
+import { PublicRoute } from "./guards/public.route";
+import { PrivateRoute } from "./guards/private.route";
+import { AuthLayout } from "./layouts/auth.layout";
+import { ErrorLayout } from "./layouts/error.layout";
+import { MainLayout } from "./layouts/main.layout";
+
+const PublicRoutes: RouteObject[] = [
+  {
+    Component: PublicRoute,
+    children: [
+      {
+        Component: AuthLayout,
+        ErrorBoundary: ErrorLayout,
+        children: [
+          {
+            path: PATH.page_auth(),
+            lazy: async () => {
+              const module = await import("../routes/page-auth");
+              return { Component: module.default };
+            },
+          },
+        ],
+      },
+    ],
+  },
+];
+
+const PrivateRoutes: RouteObject[] = [
+  {
+    Component: PrivateRoute,
+    children: [
+      {
+        Component: MainLayout,
+        ErrorBoundary: ErrorLayout,
+        children: [
+          {
+            path: PATH.page_root(),
+            ErrorBoundary: ErrorLayout,
+            lazy: async () => {
+              const module = await import("../routes/page-root");
+              return { Component: module.default };
+            },
+          },
+          {
+            path: PATH.page_one(),
+            ErrorBoundary: ErrorLayout,
+            lazy: async () => {
+              const module = await import("../routes/page-one");
+              return { Component: module.default };
+            },
+          },
+          {
+            path: PATH.page_two(),
+            ErrorBoundary: ErrorLayout,
+            lazy: async () => {
+              const module = await import("../routes/page-two");
+              return { Component: module.default };
+            },
+          },
+        ],
+      },
+    ],
+  },
+];
+
+const NotFoundRoutes: RouteObject[] = [
+  {
+    path: PATH.not_found(), // Wildcard catch-all must be at the end of the root array
+    lazy: async () => {
+      const module = await import("../routes/not-found");
+      return { Component: module.default };
+    },
+  },
+];
+
+export const router = createBrowserRouter([
+  ...PublicRoutes,
+  ...PrivateRoutes,
+  ...NotFoundRoutes,
+]);
+
+/* 
+
+currently i am using new way of using react-router version like
+Component: PrivateLayout,
+lazy: async () => ...
+
+the old way is 
+
+{
+  path: "/",
+  element: (
+    <PublicRoute>
+      <AuthLayout />
+    </PublicRoute>
+  ),
+  children: [
+    {
+      path: PATHS.LOGIN,
+      element: <Login />,
+    },
+  ],
+}
+
+
+
+| Feature              | `errorElement`                    | `ErrorBoundary`            |
+| -------------------- | --------------------------------- | -------------------------- |
+| What you pass        | React Element                     | Component Function         |
+| Syntax               | `errorElement: <ErrorPage />`     | `ErrorBoundary: ErrorPage` |
+| Requires JSX         | Yes                               | No                         |
+| Works in `.ts` file  | No (unless `React.createElement`) | Yes                        |
+| React Router version | v6.4+                             | Newer preferred API        |
+
+
+---------------------------------------------------------------------------
+
+# ANCHOR : 2 ways to show the error boundry page data 
+
+
+# NOTE : WAY-1 inside layout i.e inplace of outlet
+ {
+        path: PATH.page_two(),
+        ErrorBoundary: ErrorLayout,
+        lazy: async () => {
+          const module = await import("../routes/page-two");
+          return { Component: module.default };
+        },
+      },
+
+---------------------------------------------------------------------------
+
+      # NOTE : WAY-2 replace entire layout with error boundary
+       {
+    Component: AuthLayout,
+    ErrorBoundary: ErrorLayout,
+    children: [
+      {
+        path: PATH.page_auth(),
+        lazy: async () => {
+          const module = await import("../routes/page-auth");
+          return { Component: module.default };
+        },
+      },
+    ],
+  },
+
+---------------------------------------------------------------------------
+
+# NOTE : DYNAMIC PAGE TITLES (SEO BEST PRACTICE)
+To set browser tab titles dynamically on page transitions, create a custom hook and call it inside your page route components:
+
+```typescript
+import { useEffect } from "react";
+
+export function useDocumentTitle(title: string) {
+  useEffect(() => {
+    const original = document.title;
+    document.title = `${title} | My App`;
+    return () => {
+      document.title = original;
+    };
+  }, [title]);
+}
+
+// In routes/page-one.tsx:
+// useDocumentTitle("Analytics Page");
+```
+
+---------------------------------------------------------------------------
+
+# NOTE : ROUTE-LEVEL SUSPENSE VS. COMPONENT-LEVEL SKELETONS
+
+1. **Why we place `<Suspense>` at the very top (wrapping `<RouterProvider>`):**
+   - **Code Chunk Loading:** Because we lazy-load routes (`lazy: async () => ...`), React Router has to download the page's `.js` chunk file from the server when navigating.
+   - **Preventing UI Freezes:** If you click a link and do not have a top-level Suspense boundary, the app will freeze or flicker on the old page until the file download finishes. 
+   - **Best Practice:** Wrap the router in `<Suspense fallback={<TopBarProgressBar />} />` so the user gets instant progress feedback when clicking links.
+
+2. **Why we use Component-level skeletons:**
+   - **Data Loading:** Once the page code is downloaded and mounted, your API data fetching starts.
+   - **Interactive UI:** This is where you render custom skeleton loaders inside your page components while waiting for TanStack Query data, offering a premium and localized loading layout.
+ */
+
+

package/templates/react-router/router/layouts/auth.layout.tsx

@@ -0,0 +1,5 @@
+import { Outlet } from "react-router-dom";
+
+export function AuthLayout() {
+  return <Outlet />;
+}

package/templates/react-router/router/layouts/error.layout.tsx

@@ -0,0 +1,15 @@
+import { Outlet, useRouteError } from "react-router-dom";
+
+export function ErrorLayout() {
+  const error = useRouteError();
+  return (
+    <div>
+      <h1>Something went wrong!</h1>
+      <p>
+        {error instanceof Error
+          ? error.message
+          : "An unexpected error occurred"}
+      </p>
+    </div>
+  );
+}

package/templates/react-router/router/layouts/main.layout.tsx

@@ -0,0 +1,5 @@
+import { Outlet } from "react-router-dom";
+
+export function MainLayout() {
+  return <Outlet />;
+}

package/templates/react-router/router/path.ts

@@ -0,0 +1,7 @@
+export const PATH = {
+  page_root: () => "/" as const,
+  page_one: () => "/page_one" as const,
+  page_two: () => "/page_two" as const,
+  page_auth: () => "/page_auth" as const,
+  not_found: () => "*" as const,
+};

package/templates/react-router/routes/not-found/index.tsx

@@ -0,0 +1,3 @@
+export default function NotFound() {
+  return <div>Not Found</div>;
+}

package/templates/react-router/routes/page-auth/index.tsx

@@ -0,0 +1,3 @@
+export default function PageAuth() {
+  return <div>Page Auth</div>;
+}

package/templates/react-router/routes/page-one/index.tsx

@@ -0,0 +1,85 @@
+export default function PageOne() {
+  return <div>Page One</div>;
+}
+
+/*
+# NOTE: FRAMEWORK-LEVEL META & PRERENDERING CONFIGURATION (SEO)
+
+If you are using React Router v7 and want static HTML files compiled for SEO search crawlers, follow these steps:
+
+-------------------------------------------------------------------------------------
+
+1. ROUTE META EXPORT (Add this inside this page file):
+```typescript
+import type { MetaFunction } from "react-router-dom";
+
+export const meta: MetaFunction = () => {
+  return [
+    { title: "Page One Analytics | My App" },
+    { name: "description", content: "Analyze product sales and user logs." },
+  ];
+};
+```
+
+-------------------------------------------------------------------------------------
+
+2. PRERENDER SETTINGS (Add this in your react-router.config.ts / vite.config.ts):
+```typescript
+export default {
+  async prerender() {
+    return ["/", "/page_one", "/page_two"]; // Routes to generate as static HTML pages
+  },
+};
+```
+
+-------------------------------------------------------------------------------------
+
+3. HOW THE BUILD CHANGES (Build output comparison):
+
+OLD BUILD (Standard Single Page Application):
+- Outputs only a single empty "index.html" page.
+- Crawlers see no initial page HTML or titles when visiting "/page_one" until JS loads.
+
+NEW BUILD (Prerendered SPA):
+- Outputs directory folders containing index.html files:
+  dist/
+    ├── index.html            <- for "/"
+    ├── page_one/
+    │   └── index.html        <- for "/page_one" (contains pre-rendered metadata)
+    └── page_two/
+        └── index.html        <- for "/page_two" (contains pre-rendered metadata)
+
+-------------------------------------------------------------------------------------
+
+4. SERVER SETTINGS (VPS Deployment):
+
+For a standard VPS server (like Nginx), configure it to serve static files from your build directory. 
+Nginx will look for the folder-based index files (e.g., /page_one/index.html) first.
+
+NGINX VPS CONFIGURATION EXAMPLE (/etc/nginx/sites-available/default):
+```nginx
+server {
+    listen 80;
+    server_name your-app.com;
+
+    # Point to your build distribution directory on the VPS
+    root /var/www/your-app/dist; 
+
+    index index.html;
+
+    location / {
+        # 1. Checks if exact file exists ($uri)
+        # 2. Checks if a directory index.html exists ($uri/) -> Serves pre-rendered SEO pages!
+        # 3. Falls back to root index.html if route is handled client-side
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Optional: Proxy API requests directly to your Laravel Backend
+    location /api/ {
+        proxy_pass http://127.0.0.1:8000; # Address where your Laravel backend runs
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+*/

package/templates/react-router/routes/page-one/search.page-one.ts

@@ -0,0 +1,5 @@
+export const PageOneDefaultSearchParam = {
+  param_one: "",
+  param_two: "",
+  param_three: "",
+};

package/templates/react-router/routes/page-root/index.tsx

@@ -0,0 +1,3 @@
+export default function PageRoot() {
+  return <div>Page Root</div>;
+}

package/templates/react-router/routes/page-two/index.tsx

@@ -0,0 +1,3 @@
+export default function PageTwo() {
+  return <div>Page Two</div>;
+}

package/templates/react-router/routes/page-two/search.page-two.ts

@@ -0,0 +1,5 @@
+export const PageTwoDefaultSearchParam = {
+  param_one: "",
+  param_two: "",
+  param_three: "",
+};