pjdev2d-cli 1.2.0 → 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.2.0",
+  "version": "1.2.1",
   "type": "module",
   "description": "CLI to install reusable React components like shadcn/ui",
   "main": "bin/cli.js",

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

@@ -5,17 +5,52 @@ export function PrivateRoute() {
 }
 
 /* 
+# 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.
 
-# NOTE : use this when you want to redirect user to login page if he is already logged out
-
-import { Navigate, Outlet } from "react-router-dom";
+import { Navigate, Outlet, useLocation } from "react-router-dom";
 
 export default function PrivateRoute() {
   const token = getLocalAuthToken();
+  const location = useLocation();
+
   if (!token) {
-    return <Navigate to={"/"} replace />;
+    // 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/index.ts

@@ -8,7 +8,6 @@ import { MainLayout } from "./layouts/main.layout";
 
 const PublicRoutes: RouteObject[] = [
   {
-    path: PATH.page_root(),
     Component: PublicRoute,
     children: [
       {
@@ -24,13 +23,6 @@ const PublicRoutes: RouteObject[] = [
           },
         ],
       },
-      {
-        path: PATH.not_found(),
-        lazy: async () => {
-          const module = await import("../routes/not-found");
-          return { Component: module.default };
-        },
-      },
     ],
   },
 ];
@@ -73,7 +65,21 @@ const PrivateRoutes: RouteObject[] = [
   },
 ];
 
-export const router = createBrowserRouter([...PublicRoutes, ...PrivateRoutes]);
+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,
+]);
 
 /* 
 
@@ -141,4 +147,40 @@ the old way is
     ],
   },
 
+---------------------------------------------------------------------------
+
+# 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/error.layout.tsx

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

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

@@ -1,3 +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;
+    }
+}
+```
+*/