nextjs-route-utils 1.0.0

package/.vscode/settings.json

@@ -0,0 +1,25 @@
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[css]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[html]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

package/README.md

@@ -0,0 +1,36 @@
+# nextjs-route-utils
+
+> A lightweight, type-safe route builder utility for Next.js  
+> Build dynamic and optional routes with ease and full TypeScript support.
+
+<p>
+<a href="https://github.com/wolfdev1337" style="padding-left:5px"><img alt="X platform" src="https://img.shields.io/badge/Github-25292f"></a>
+<a href="https://x.com/WolfDev1337"><img alt="Github platform" src="https://img.shields.io/badge/Twitter-1DA1F2"></a>
+</p>
+
+---
+
+## Why use `nextjs-route-utils`?
+
+In Next.js projects, especially with dynamic routes, managing route strings manually can lead to typos, inconsistencies, and bugs.  
+This package lets you **define your route patterns once** and then **build URLs with typed parameters**, ensuring correctness across your app.
+
+---
+
+## Features
+
+- Define routes with dynamic (`:param`) and optional (`:param?`) segments
+- Type-safe parameter enforcement in TypeScript
+- Automatic URL encoding of parameter values
+- Removes optional params when not provided
+- Lightweight and zero dependencies
+
+---
+
+## Installation
+
+```bash
+npm install nextjs-route-utils
+# or
+yarn add nextjs-route-utils
+```

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+type Params = Record<string, string | number | undefined>;
+/**
+ * Creates a type-safe route builder for dynamic and optional segments
+ * @param pattern A path pattern like "/users/:userId/posts/:postId?"
+ * @returns A function that builds the URL with given params
+ */
+export declare function createRoute<T extends Params>(pattern: string): (params: T) => string;
+export {};

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * Creates a type-safe route builder for dynamic and optional segments
+ * @param pattern A path pattern like "/users/:userId/posts/:postId?"
+ * @returns A function that builds the URL with given params
+ */
+export function createRoute(pattern) {
+    const keys = Array.from(pattern.matchAll(/:([a-zA-Z0-9_]+)\??/g)).map((match) => match[1]);
+    return (params) => {
+        let result = pattern;
+        keys.forEach((key) => {
+            const value = params[key];
+            const optional = result.includes(`:${key}?`);
+            if (value !== undefined) {
+                result = result.replace(`:${key}${optional ? "?" : ""}`, encodeURIComponent(String(value)));
+            }
+            else if (optional) {
+                // Remove optional segment (including optional slash)
+                result = result.replace(new RegExp(`/?:${key}\?`), "");
+            }
+            else {
+                throw new Error(`Missing required route parameter: ${key}`);
+            }
+        });
+        // Remove leftover optional markers (e.g., '/posts?')
+        result = result.replace(/\?(?=\/|$)/g, "");
+        // Cleanup extra slashes
+        return result.replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+    };
+}

package/index.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { createRoute } from "./index";
+
+describe("createRoute", () => {
+  it("builds static routes correctly", () => {
+    const home = createRoute<{}>("/");
+    expect(home({})).toBe("/");
+  });
+
+  it("builds dynamic routes correctly", () => {
+    const user = createRoute<{ userId: string }>("/users/:userId");
+    expect(user({ userId: "abc" })).toBe("/users/abc");
+  });
+
+  it("builds multiple dynamic segments", () => {
+    const post = createRoute<{ userId: string; postId: number }>(
+      "/users/:userId/posts/:postId"
+    );
+    expect(post({ userId: "john", postId: 42 })).toBe("/users/john/posts/42");
+  });
+
+  it("supports optional params", () => {
+    const post = createRoute<{ postId?: string }>("/posts/:postId?");
+    expect(post({})).toBe("/posts");
+    expect(post({ postId: "123" })).toBe("/posts/123");
+  });
+
+  it("throws if required param is missing", () => {
+    const user = createRoute<{ userId: string }>("/users/:userId");
+    // @ts-expect-error intentionally missing param
+    expect(() => user({})).toThrowError(
+      "Missing required route parameter: userId"
+    );
+  });
+
+  it("encodes URI components", () => {
+    const encoded = createRoute<{ name: string }>("/hello/:name");
+    expect(encoded({ name: "John Doe" })).toBe("/hello/John%20Doe");
+  });
+});

package/index.ts

@@ -0,0 +1,39 @@
+type Params = Record<string, string | number | undefined>;
+
+/**
+ * Creates a type-safe route builder for dynamic and optional segments
+ * @param pattern A path pattern like "/users/:userId/posts/:postId?"
+ * @returns A function that builds the URL with given params
+ */
+export function createRoute<T extends Params>(pattern: string) {
+  const keys = Array.from(pattern.matchAll(/:([a-zA-Z0-9_]+)\??/g)).map(
+    (match) => match[1]
+  );
+
+  return (params: T): string => {
+    let result = pattern;
+
+    keys.forEach((key) => {
+      const value = params[key];
+      const optional = result.includes(`:${key}?`);
+
+      if (value !== undefined) {
+        result = result.replace(
+          `:${key}${optional ? "?" : ""}`,
+          encodeURIComponent(String(value))
+        );
+      } else if (optional) {
+        // Remove optional segment (including optional slash)
+        result = result.replace(new RegExp(`/?:${key}\?`), "");
+      } else {
+        throw new Error(`Missing required route parameter: ${key}`);
+      }
+    });
+
+    // Remove leftover optional markers (e.g., '/posts?')
+    result = result.replace(/\?(?=\/|$)/g, "");
+
+    // Cleanup extra slashes
+    return result.replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+  };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "nextjs-route-utils",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prebuild": "npm run test",
+    "prepublishOnly": "npm run build",
+    "dev": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wolfdev1337/nextjs-route-utils.git"
+  },
+  "keywords": [
+    "nextjs",
+    "routes",
+    "utility",
+    "typescript"
+  ],
+  "author": "Wolf Developer",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@types/node": "^24.0.10",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["index.ts"]
+}