nuxt-typed-router 2.0.0-beta.0 → 2.0.0

package/README.md

@@ -1,7 +1,7 @@
-# 🚗🚦 Typed Router for Nuxt
+
 
 <p align="center">
-  <img width='100' src="https://raw.githubusercontent.com/victorgarciaesgi/nuxt-typed-router/master/.github/images/logo.png" alt="nuxt-typed-router logo">
+  <img src="https://raw.githubusercontent.com/victorgarciaesgi/nuxt-typed-router/master/.github/images/cover.png" alt="nuxt-typed-router cover">
 </p>
 
 
@@ -18,26 +18,40 @@
 
 ## Provide a type safe router to Nuxt with auto-generated typed definitions for route names and autocompletion for route params
 
-- 🏎 Provides a hook `useTypedRouter` that returns an alias of `$typedRouter` and also a typed list of your routes
-- 🚚 Expose a global method `$typedRouter` (clone of vue-router), but typed with the routes defined in `pages` directory
-- 🚦 Provides auto-completion and errors for route params in `push` and `replace` methods
+- Automaticaly provides types check and autocomplete to `NuxtLink`
+- Exports a `useTypedRouter` and `useTypedRoute` composable
+- Supports routes defined in `config.extendRoutes`
+- Infer route params based on route name
+- Provide global `$typedRouter` util
+
+<br/>
 
 <br/>
+<p align="center">
+  <img src="https://github.com/victorgarciaesgi/nuxt-typed-router/blob/master/.github/images/nuxt-router.gif?raw=true"/>
+</p>
+<br/>
+
+
+# Documentation
+
+[![Open in StackBlitz](https://github.com/victorgarciaesgi/nuxt-typed-router/blob/master/.github/images/redirectDoc.svg?raw=true)](https://nuxt-typed-router.vercel.app/)
 
-Demo 🧪 : [nuxt-typed-router-demo](https://github.com/victorgarciaesgi/nuxt-typed-router-demo)
+# Play with it
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/github-7e4xvw?file=store/testRouter.ts)
 
-## Compatibility:
+Demo repo 🧪 : [nuxt-typed-router-demo](https://github.com/victorgarciaesgi/nuxt-typed-router-demo)
+
+<br/>
+
+# Compatibility:
 
 - Nuxt 3
 - Nuxt 2 (via [`nuxt2` branch](https://github.com/victorgarciaesgi/nuxt-typed-router/tree/nuxt2))
 
-<br/>
-<p align="center">
-  <img src="https://github.com/victorgarciaesgi/nuxt-typed-router/blob/master/.github/images/in-action.gif?raw=true"/>
-</p>
-<br/>
 
-# Installation
+
+# Quick start
 
 ### For Nuxt 3
 
@@ -47,9 +61,10 @@ yarn add -D nuxt-typed-router
 npm install -D nuxt-typed-router
 ```
 
-### For Nuxt 2
+### Nuxt 2 legacy
 
-For Nuxt 2 usage, check out the docs at the [`nuxt2` branch](https://github.com/victorgarciaesgi/nuxt-typed-router/tree/nuxt2)
+Nuxt 2 version is no longer maintained, but still available in [`nuxt2` branch](https://github.com/victorgarciaesgi/nuxt-typed-router/tree/nuxt2)
+It only has route name autocomplete functionnality
 
 ```bash
 yarn add -D nuxt-typed-router@legacy
@@ -58,192 +73,22 @@ npm install -D nuxt-typed-router@legacy
 ```
 
 # Configuration
-
-First, register the module in the `nuxt.config.ts`
+Register the module in the `nuxt.config.ts`, done!
 
 ```ts
 export default defineNuxtConfig({
   modules: ['nuxt-typed-router'],
-  nuxtTypedRouter: {
-    // options
-  },
 });
 ```
 
-## Options:
-
-```ts
-interface ModuleOptions {
-  /** Output directory where you cant the files to be saved
-   * (ex: "./models")
-   * @default "<srcDir>/generated"
-   */
-  outDir?: string;
-  /** Name of the routesNames object (ex: "routesTree")
-   * @default "routerPagesNames"
-   * */
-  routesObjectName?: string;
-  /**
-   * Set to false if you don't want a plugin generated
-   * @default false
-   */
-  plugin?: boolean;
-}
-```
-
-# Generated files
-
-The module will generate 4 files each time you modify the `pages` folder :
-
-- `~/<outDir>/__routes.ts` with the global object of the route names inside.
-- `~/<outDir>/__useTypedRouter.ts` Composable to simply access your typed routes
-- `~/<outDir>/typed-router.d.ts` containing the global typecript definitions and exports
-- `~/plugins/__typed_router.ts` Plugin that will inject `$typedRouter` and `$routesList` (`@nuxt/kit` has problems registering plugin templates so this is a workaround)
-
-# Usage in Vue/Nuxt
-
-<br/>
-
-### **_Requirements_**
-
-You can specify the output dir of the generated files in your configuration. It defaults to `<srcDir>/generated`
-
-```ts
-export default defineNuxtConfig({
-  modules: ['nuxt-typed-router'],
-  nuxtTypedRouter: {
-    outDir: './generated',
-  },
-});
-```
-
-# How it works
-
-Given this structure
-
-        ├── pages
-            ├── index
-                ├── content
-                    ├── [id].vue
-                ├── content.vue
-                ├── index.vue
-                ├── communication.vue
-                ├── statistics.vue
-                ├── [user].vue
-            ├── index.vue
-            ├── forgotpassword.vue
-            ├── reset-password.vue
-        │   └── login.vue
-        └── ...
-
-The generated route list will look like this
-
-```ts
-export const routerPagesNames = {
-  forgotpassword: 'forgotpassword' as const,
-  login: 'login' as const,
-  resetPassword: 'reset-password' as const,
-  index: {
-    index: 'index' as const,
-    communication: 'index-communication' as const,
-    content: {
-      id: 'index-content-id' as const,
-    },
-    statistics: 'index-statistics' as const,
-    user: 'index-user' as const,
-  },
-};
-export type TypedRouteList =
-  | 'forgotpassword'
-  | 'login'
-  | 'reset-password'
-  | 'index'
-  | 'index-communication'
-  | 'index-content-id'
-  | 'index-statistics'
-  | 'index-user';
-```
-
-> nuxt-typed-router will also create a plugin in your `<srcDir>/plugins` folder with the injected `$typedRouter` and `$routesList` helpers
-
-# Usage with `useTypedRouter` hook
-
-`useTypedRouter` is an exported composable from nuxt-typed-router. It contains a clone of `vue-router` but with strictly typed route names and params type-check
-
-```vue
-<script lang="ts">
-// The path here is `~/generated` because I set `outDir: './generated'` in my module options
-import { useTypedRouter } from '~/generated';
-
-export default defineComponent({
-  setup() {
-    // Fully typed
-    const { router, routes } = useTypedRouter();
-
-    function navigate() {
-      // Autocompletes the name and infer the params
-      router.push({ name: routes.index.user, params: { user: 1 } }); // ✅ valid
-      router.push({ name: routes.index.user, params: { foo: 1 } }); // ❌ invalid
-    }
-
-    return { navigate };
-  },
-});
-</script>
-```
-
-# Usage with `$typedRouter` and `$routesList` injected helpers
-
-`$typedRouter` is an injected clone of vue-router `$router`, but fully typed with all your routes.
-It's available anywhere you have access to Nuxt context
-
-```vue
-<script lang="ts">
-import { defineComponent } from 'vue';
-
-export default defineComponent({
-  name: 'Index',
-  setup() {
-    const { $typedRouter, $routesList } = useNuxtApp();
-
-    function navigate() {
-      $typedRouter.push({ name: $routesList.activate });
-    }
-
-    return {
-      navigate,
-    };
-  },
-});
-</script>
-```
-
-# Usage outside Vue component
-
-You can import the `useTypedRouter` composable from where it's generated.
-Exemple with `pinia` store here
-
-```ts
-import pinia from 'pinia';
-import { useTypedRouter } from '~/generated';
-
-export const useFooStore = defineStore('foo', {
-  actions: {
-    bar() {
-      const { router, routes } = useTypedRouter();
-      router.push({ name: routes.index.user, params: { user: 2 } });
-    },
-  },
-});
-```
 
 ## Development
 
 1. Clone this repository
-2. Install dependencies using `yarn`
-3. Build project for local tests `yarn build:local`
-4. Start dev playground `yarn play`
-5. Build project for deploy `yarn prepack`
+2. Install dependencies using `pnpm`
+3. Build project for local tests `pnpm build:local`
+4. Start dev playground `pnpm play`
+5. Build project for deploy `pnpm prepack`
 
 ## 📑 License
 

package/dist/module.json

@@ -5,5 +5,5 @@
     "nuxt": "^3.0.0-rc.1",
     "bridge": false
   },
-  "version": "2.0.0-beta.0"
+  "version": "2.0.0"
 }

package/dist/module.mjs

@@ -120,7 +120,7 @@ declare global {
 }
 
 type TypedNuxtLinkProps = Omit<NuxtLinkProps, 'to'> & {
-  to: Omit<Exclude<RouteLocationRaw, string>, 'name'> & TypedRouteNamedMapper;
+  to: string | Omit<Exclude<RouteLocationRaw, string>, 'name'> & TypedRouteNamedMapper;
 };
 
 type _NuxtLink = DefineComponent<
@@ -171,7 +171,7 @@ function createDeclarationRoutesFile() {
 function createRuntimeIndexFile() {
   return `
   ${watermarkTemplate}
-  export * from './__routes';
+  export {routesNames, TypedRouteList} from './__routes';
   export * from './__useTypedRouter';
   export * from './__useTypedRoute';
   `;
@@ -227,7 +227,9 @@ function createResolvedTypedRouteNamedMapperExport(routesParams) {
   } & (
     ${routesParams.map(
     ({ name, params }) => `{name: "${name}" ${params.length ? `, params: {
-          ${params.map(({ key, type }) => `"${key}": ${type}`).join(",\n")}
+                ${params.map(
+      ({ key, notRequiredOnPage, type }) => `"${key}"${notRequiredOnPage ? "?" : ""}: ${type}`
+    ).join(",\n")}
         }` : ""}}`
   ).join("|\n")}
       )
@@ -307,7 +309,6 @@ function createRuntimeUseTypedRouterFile(routesDeclTemplate) {
   ${watermarkTemplate}
   import { useRouter } from '#app';
   import { TypedRouter } from './typed-router';
-  import { RouteListDecl } from './__routes';
 
   /** Returns instances of $typedRouter and $routesList fully typed to use in your components or your Vuex/Pinia store
    * 
@@ -357,11 +358,12 @@ dirname(fileURLToPath(import.meta.url));
 async function processPathAndWriteFile({
   content,
   fileName,
-  srcDir
+  srcDir,
+  outDir
 }) {
   try {
-    const outDir = `.nuxt/typed-router`;
-    const processedOutDir = resolve(srcDir, outDir);
+    const finalOutDir = outDir ?? `.nuxt/typed-router`;
+    const processedOutDir = resolve(srcDir, finalOutDir);
     const outputFile = resolve(process.cwd(), `${processedOutDir}/${fileName}`);
     const formatedContent = await formatOutputWithPrettier(content);
     if (fs.existsSync(outputFile)) {
@@ -403,6 +405,7 @@ function handlePluginFileSave({
   });
 }
 
+let previousGeneratedRoutes = "";
 async function saveGeneratedFiles({
   srcDir,
   outputData: { routesDeclTemplate, routesList, routesObjectTemplate, routesParams }
@@ -437,22 +440,35 @@ async function saveGeneratedFiles({
   await Promise.all(
     filesMap.map(({ content, fileName }) => processPathAndWriteFile({ srcDir, content, fileName }))
   );
-  console.log(logSymbols.success, `[typed-router] Routes definitions generated`);
+  if (previousGeneratedRoutes !== routesList.join(",")) {
+    previousGeneratedRoutes = routesList.join(",");
+    console.log(logSymbols.success, `[typed-router] Routes definitions generated`);
+  }
 }
 
 function isItemLast(array, index) {
   return array ? index === array.length - 1 : false;
 }
 
-const routeParamExtractRegxp = /:(\w+)/;
+const routeParamExtractRegxp = /(:(\w+)(\?)?)+/g;
 function extractRouteParamsFromPath(path, isIndexFileForRouting, previousParams) {
-  const params = path.match(routeParamExtractRegxp) ?? [];
-  params?.shift();
+  let params = [];
+  let matches;
+  do {
+    matches = routeParamExtractRegxp.exec(path);
+    if (matches) {
+      const [_, mtch, key, optional] = matches;
+      if (mtch) {
+        params.push({ name: key, optional: !!optional });
+      }
+    }
+  } while (matches);
   let allMergedParams = params.map(
-    (m) => ({
-      key: m,
+    ({ name, optional }) => ({
+      key: name,
       type: "string | number",
-      required: true
+      required: !optional,
+      notRequiredOnPage: optional
     })
   );
   if (previousParams?.length) {
@@ -633,6 +649,7 @@ const module = defineNuxtModule({
       )
     };
     nuxt.hook("pages:extend", () => createTypedRouter({ srcDir, nuxt, plugin }));
+    createTypedRouter({ srcDir, nuxt, plugin });
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-typed-router",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0",
   "description": "Provide autocompletion for pages route names generated by Nuxt router",
   "type": "module",
   "main": "./dist/module.cjs",
@@ -24,7 +24,7 @@
     "test": "pnpm run dev:prepare && pnpm run build:test && vitest run",
     "test:watch": "pnpm run build:test && vitest",
     "docs:dev": "cd docs && pnpm run dev",
-    "docs:buid": "(cd docs && nuxi build)"
+    "docs:build": "npm run dev:prepare && cd docs && nuxi generate"
   },
   "publishConfig": {
     "access": "public"
@@ -39,6 +39,7 @@
     "nuxt 3",
     "nuxt 3 router"
   ],
+  "homepage": "https://nuxt-typed-router.vercel.app/",
   "repository": {
     "type": "git",
     "url": "git+https://victorgarciaesgi@github.com/victorgarciaesgi/nuxt-typed-router.git"