pathpida

TypeScript friendly internal link client for Next.js, Nuxt.js and Sapper.

Next.js
aspida/pathpidapathpida

README

pathpida



pathpida
npm version npm download Node.js CI Codecov Language grade: JavaScript

TypeScript friendly internal link client for Next.js and Nuxt.js.




Breaking change :warning:


2022/11/25


Since pathpida >= 0.20.0 , removed Sapper support.

2022/02/24


Since pathpida >= 0.18.0 , requires TypeSciprt 3.8 or higher for Type-Only Imports.

Features


- Type safety. Automatically generate type definition files for manipulating internal links in Next.js/Nuxt.js.
- Zero configuration. No configuration required can be used immediately after installation.
- Zero runtime. Lightweight because runtime code is not included in the bundle.
- Support for static files. Static files in public/ are also supported, so static assets can be safely referenced.
- Support for appDir of Next.js 13 Layout.

Table of Contents


- Install
- Command Line Interface Options
- Setup - Next.js
- Usage - Next.js
- Define query - Next.js
- Generate static files path - Next.js
- Setup - Nuxt.js
- Usage - Nuxt.js
- Define query - Nuxt.js
- Generate static files path - Nuxt.js
- License

Install


- Using npm:

  sh
  $ npm install pathpida npm-run-all --save-dev
  

- Using Yarn:

  sh
  $ yarn add pathpida npm-run-all --dev
  


Command Line Interface Options


Option Type Description
--enableStatic
-s		 Generate static files path in $path.ts.
--ignorePath
-p		 string Specify the ignore pattern file path.
--output
-o		 string Specify the output directory for $path.ts.
--watch
-w		 Enable watch mode.
Regenerate $path.ts.
--version
-v		 Print pathpida version.


Setup - Next.js


package.json

  1. ```json
  2. {
  3.   "scripts": {
  4.     "dev": "run-p dev:*",
  5.     "dev:next": "next dev",
  6.     "dev:path": "pathpida --ignorePath .gitignore --watch",
  7.     "build": "pathpida --ignorePath .gitignore && next build"
  8.   }
  9. }
  10. ```


Usage - Next.js


  1. ```
  2. pages/index.tsx
  3. pages/post/create.tsx
  4. pages/post/[pid].tsx
  5. pages/post/[...slug].tsx

  7. lib/$path.ts or utils/$path.ts // Generated automatically by pathpida
  8. ```

or

  1. ```
  2. src/pages/index.tsx
  3. src/pages/post/create.tsx
  4. src/pages/post/[pid].tsx
  5. src/pages/post/[...slug].tsx

  7. src/lib/$path.ts or src/utils/$path.ts // Generated automatically by pathpida
  8. ```

pages/index.tsx

  1. ```tsx
  2. import Link from "next/link"
  3. import { pagesPath } from "../lib/$path"

  5. console.log(pagesPath.post.create.$url()) // { pathname: '/post/create' }
  6. console.log(pagesPath.post._pid(1).$url()) // { pathname: '/post/[pid]', query: { pid: 1 }}
  7. console.log(pagesPath.post._slug(["a", "b", "c"]).$url()) // { pathname: '/post//[...slug]', query: { slug: ['a', 'b', 'c'] }}

  9. export default () => {
  10.   const onClick = useCallback(() => {
  11.     router.push(pagesPath.post._pid(1).$url())
  12.   }, [])

  14.   return (
  15.     <>
  16.       <Link href={pagesPath.post._slug(["a", "b", "c"]).$url()} />
  17.       <div onClick={onClick} />
  18.     </>
  19.   )
  20. }
  21. ```


Define query - Next.js


pages/post/create.tsx

  1. ```tsx
  2. export type Query = {
  3.   userId: number
  4.   name?: string
  5. }

  7. export default () => <div />
  8. ```

pages/post/[pid].tsx

  1. ```tsx
  2. export type OptionalQuery = {
  3.   limit: number
  4.   label?: string
  5. }

  7. export default () => <div />
  8. ```

pages/index.tsx

  1. ```tsx
  2. import Link from "next/link"
  3. import { pagesPath } from "../lib/$path"

  5. console.log(pagesPath.post.create.$url({ query: { userId: 1 } })) // { pathname: '/post/create', query: { userId: 1 }}
  6. console.log(pagesPath.post.create.$url()) // type error
  7. console.log(pagesPath.post._pid(1).$url()) // { pathname: '/post/[pid]', query: { pid: 1 }}
  8. console.log(pagesPath.post._pid(1).$url({ query: { limit: 10 }, hash: "sample" })) // { pathname: '/post/[pid]', query: { pid: 1, limit: 10 }, hash: 'sample' }

  10. export default () => {
  11.   const onClick = useCallback(() => {
  12.     router.push(pagesPath.post._pid(1).$url())
  13.   }, [])

  15.   return (
  16.     <>
  17.       <Link href={pagesPath.post._slug(["a", "b", "c"]).$url()} />
  18.       <div onClick={onClick} />
  19.     </>
  20.   )
  21. }
  22. ```


Generate static files path - Next.js


package.json

  1. ```json
  2. {
  3.   "scripts": {
  4.     "dev": "run-p dev:*",
  5.     "dev:next": "next dev",
  6.     "dev:path": "pathpida --enableStatic --watch",
  7.     "build": "pathpida --enableStatic && next build"
  8.   }
  9. }
  10. ```

  1. ```
  2. pages/index.tsx
  3. pages/post/create.tsx
  4. pages/post/[pid].tsx
  5. pages/post/[...slug].tsx

  7. public/aa.json
  8. public/bb/cc.png

  10. lib/$path.ts or utils/$path.ts // Generated automatically by pathpida
  11. ```

or

  1. ```
  2. src/pages/index.tsx
  3. src/pages/post/create.tsx
  4. src/pages/post/[pid].tsx
  5. src/pages/post/[...slug].tsx

  7. public/aa.json
  8. public/bb/cc.png

  10. src/lib/$path.ts or src/utils/$path.ts // Generated automatically by pathpida
  11. ```

pages/index.tsx

  1. ```tsx
  2. import Link from "next/link"
  3. import { pagesPath, staticPath } from "../lib/$path"

  5. console.log(staticPath.aa_json) // /aa.json

  7. export default () => {
  8.   return (
  9.     <>
  10.       <Link href={pagesPath.post._slug(["a", "b", "c"]).$url()} />
  11.       <img src={staticPath.bb.cc_png} />
  12.     </>
  13.   )
  14. }
  15. ```


Setup - Nuxt.js


package.json

  1. ```json
  2. {
  3.   "scripts": {
  4.     "dev": "run-p dev:*",
  5.     "dev:nuxt": "nuxt-ts",
  6.     "dev:path": "pathpida --ignorePath .gitignore --watch",
  7.     "build": "pathpida --ignorePath .gitignore && nuxt-ts build"
  8.   }
  9. }
  10. ```

nuxt.config.js or nuxt.config.ts

  1. ```js
  2. {
  3.   plugins: ['~/plugins/$path'],
  4.   srcDir: 'client', // optional
  5.   router: {
  6.     trailingSlash: true // optional
  7.   }
  8. }
  9. ```


Usage - Nuxt.js


  1. ```
  2. pages/index.vue
  3. pages/post/create.vue
  4. pages/post/_pid.tsx

  6. plugins/$path.ts // Generated automatically by pathpida
  7. ```

pages/index.vue

  1. ```vue
  2. <template>
  3.   <div>
  4.     <nuxt-link :to="$pagesPath.post._pid(1).$url()" />
  5.     <div @click="onClick" />
  6.   </div>
  7. </template>

  9. <script lang="ts">
  10. import Vue from "vue"

  12. export default Vue.extend({
  13.   methods: {
  14.     onClick() {
  15.       this.$router.push(this.$pagesPath.post._pid(1).$url())
  16.     }
  17.   }
  18. })
  19. </script>
  20. ```


Define query - Nuxt.js


pages/post/create.vue

  1. ```vue
  2. <script lang="ts">
  3. import Vue from "vue"

  5. export type Query = {
  6.   userId: number
  7.   name?: string
  8. }

  10. export default Vue.extend({})
  11. </script>
  12. ```

pages/post/_pid.vue

  1. ```vue
  2. <script lang="ts">
  3. import Vue from "vue"

  5. export type OptionalQuery = {
  6.   limit: number
  7.   label?: string
  8. }

  10. export default Vue.extend({})
  11. </script>
  12. ```

pages/index.vue

  1. ```vue
  2. <template>
  3.   <div>
  4.     <nuxt-link :to="$pagesPath.post.create.$url({ query: { userId: 1 } })" />
  5.     <div @click="onClick" />
  6.   </div>
  7. </template>

  9. <script lang="ts">
  10. import Vue from "vue"

  12. export default Vue.extend({
  13.   methods: {
  14.     onClick() {
  15.       this.$router.push(this.$pagesPath.post._pid(1).$url())
  16.       this.$router.push(this.$pagesPath.post._pid(1).$url({ query: { limit: 10 }, hash: "sample" }))
  17.     }
  18.   }
  19. })
  20. </script>
  21. ```

:warning: In the case of .vue file, Query/OptionalQuery type must not contain any reference types.


This is because due to typescript restrictions, types exported from .vue files cannot be imported in plugins/$path.ts.
If you want to import types from other files, please use import types with absolute paths.

types/users.ts

  1. ```ts
  2. export type UserId = number
  3. ```

pages/post/create.vue

  1. ```vue
  2. <script lang="ts">
  3. import Vue from "vue"

  5. export type Query = {
  6.   userId: import("~/types/users").UserId
  7.   name?: string
  8. }

  10. export default Vue.extend({})
  11. </script>
  12. ```


Generate static files path - Nuxt.js


package.json

  1. ```json
  2. {
  3.   "scripts": {
  4.     "dev": "run-p dev:*",
  5.     "dev:nuxt": "nuxt-ts",
  6.     "dev:path": "pathpida --enableStatic --watch",
  7.     "build": "pathpida --enableStatic && nuxt-ts build"
  8.   }
  9. }
  10. ```

  1. ```
  2. pages/index.vue
  3. pages/post/create.vue
  4. pages/post/_pid.vue

  6. static/aa.json
  7. static/bb/cc.png

  9. plugins/$path.ts // Generated automatically by pathpida
  10. ```

pages/index.vue

  1. ```vue
  2. <template>
  3.   <div>
  4.     <nuxt-link :to="$pagesPath.post.create.$url({ query: { userId: 1 } })" />
  5.     <img :src="$staticPath.bb.cc_png" />
  6.   </div>
  7. </template>

  9. <script lang="ts">
  10. import Vue from "vue"

  12. export default Vue.extend({})
  13. </script>
  14. ```

License


pathpida is licensed under a MIT License.