next-route-typesafe

next/link, next/router를 빠르게 입력하기위해 타입을 추론해주는 library 이며 pages폴더를 탐색하여 url path를 추출합니다. 상황에 맞게 type safe 하게 사용 할 수 있고 autocomplete을 위한 타입 추론용으로 사용할 수 있습니다.

Install

yarn add next-route-typesafe

Usage

1. root에 route.config.js 추가

   const config = {
     mode: 'single',
     strict: false,
   };

2. generate-routes-type 실행

generate-routes-type를 실행하고나면 root에 next/router, next/link의 type 재정의 파일(next-routes-overriding.d.ts)과 page 하위에서 추출한 전체 url path를 저장하고 있는 type 정의 파일(routes.d.ts)이 하나씩 추가됩니다.

위 사진에서 route.d.ts가 page 하위에서 추출한 전체 url path type이고, next-router-overriding.d.ts가 next/router, next/link의 type 재정의 파일입니다

route.config.js의 mode가 monorepo일때는 달라집니다.

Config(route.config.js) option

Name	Description	Type
basePath	mode가 monorepo일때 사용하며 추출된 url path들의 key값을 제거할때 사용합니다	string(optional)
ignorePath	pages folder가 있지만 link로 추출되길 원하지 않는 directory가 있을때 사용합니다.	string[](optional)
strict	link로 추출된 타입 이외에 string도 허용할지 여부입니다.(default:false)	boolean(optional)
mode	project의 구조형태 입니다.	'monorepo' | 'single'(required)

basePath

mode가 monorepon일때 link의 타입이 {[serivceName]: Links} 형태로 추출되는데 여기서 serviceName의 특정 부분을 제거할때 사용합니다.

• basePath: undefined

  'apps/serviceA':
        | '/a'
        | '/b'
        | '/a/[query]'
  'apps/serviceB': '/' | '/post/[postNo]' | '/search';
  'apps/serviceC':
        | '/demo'
        | '/'
        | '/submit';

• basePath: "apps"

  'serviceA':
        |'/a'
        |'/b'
        |'/a/[query]'
  'serviceB':'/' |'/post/[postNo]' |'/search';
  'serviceC':
        |'/demo'
        |'/'
        |'/submit';

strict

link type으로 string을 허용할지 여부를 결정하는 option 입니다. (autocomplete를 위한 타입 추론용으로 사용할 수 있습니다.)

• strict:true
  • Link component href prop에 오로지 추출된 url path만 전달할 수 있습니다.
    • <Link href="string" /> 형태로 사용시 path param이 없는 path만 전달할 수 있습니다
      • <Link href="/a/b" />(✅ correct)
      • <Link href="/a/[b]" />(❌ error)
    • <Link href={{pathname:"string", query:{...}}} /> 형태로 사용시 pathname에 path param여부에 따라 query값의 필수 여부가 결정되고, path param이외의 값을 query에 전달할시 모두 query string 으로 바뀝니다.
      • <Link href={{pathname:"/a/b"}} />(✅ correct)
      • <Link href={{pathname:"/a/b", query:{qs:22} }} />(✅ correct)
      • <Link href={{pathname:"/a/[b], query:{b:"required", token:"it is query string" }}} />(✅ correct)
      • <Link href={{pathname:"/a/[b]}} />(❌ error query에 b값을 필수로 전달 해줘야 합니다)
• strict:false
  • Link component href prop의 값으로 추출된 url path과 string type모두를 전달할 수 있습니다
    • <Link href={{pathname:"/a/b"}} />(✅ correct)
    • <Link href={{pathname:"/a/[b]"}} />(✅ correct)
    • <Link href="/a/b" />(✅ correct)
    • <Link href="/a/[b]" />(✅ correct)
    • <Link href={44} />(❌ error)

next/link, next/router, generateLink api에서도 똑같은 rule이 적용됩니다.

mode

monorepo일때와 single일때 생성되는 파일의 위치가 달라집니다.

monorepo

프로젝트 구조가 다음과 같을때

  apps
    - serviveA
      - ...
      - pages
        - a
          - c
            - [userId]
        - b
          - [token]
        - ...
      - package.json
    - serviceB
      - ...
      - pages
        - ....
      - package.json
  package.json
  ...

타입은 다음과같이 만들어집니다.

  serviceA:
    |'/'
    |'/a'
    |'/a/c'
    |'/a/c/[userId]'
    |'/b/[token]',
  serviceB:
    |'/'
    | ...

type이 만들어 지는 위치는 root에 전체 url path type(route.d.ts)파일 하나가 추가되고, ignore에 포함되지않은 Next.js의 각 root에 next/link, next/router의 type을 overriding하는 타입파일(routes-overriding.d.ts)하나가 추가됩니다

```ts
apps
  - serviceA
    - ...
    - package.json
    - `routes-overriding.d.ts(+)`
  - serviceB
    - ...
    - package.json
    - `routes-overriding.d.ts(+)`
package.json
`routes.d.ts(+)`
```

single

프로젝트 구조가 다음과 같을때

  src
    - pages
      - a
        - c
          - [userId]
      - b
        - [token]
      - ...
  package.json
  ...

타입은 다음과같이 만들어집니다.

  type LinkType =
    | '/'
    | '/a'
    | '/a/c'
    | '/a/c/[userId]'
    | '/b/[token]'
    | ...

root에 url path type(routes.d.ts)과 next/link, next/router의 type을 overriding하는 타입파일(next-router-overriding.d.t)들이 추가됩니다.

```ts
- ...
- package.json
- `routes.d.ts(+)`
- `next-router-overriding.d.ts(+)`
```

API

link를 만들어주는 함수이며 generate함수 모두 parameter로 url path가 기본적으로 추론이되고 strict 값에 따라 type이 달라집니다

• isStrict:false
  • 추론된 값 이외의 string type도 전달할 수 있습니다
• isStrict:true
  • 추론된 값만 사용이 가능하며 path param([id]의 형태])가 있을시에는 {pathname:string, query:{}} 의 형태로만 사용해야 합니다

Name	Description
generateServiceLink	mode가 monorepo일때 사용하며 추출된 다른 Next.js package의 link를 만들때 사용합니다
generateInternalLink	현재위치의 package에 해당하는 link를 만들때 사용합니다.

generateServiceLink

mode가 monorepo일때 사용하며 추출된 다른 Next.js package의 link를 만들때 사용합니다

Usage

import {generateServiceLink} from 'next-route-typesafe';

const generateLink = generateServiceLink({serviceA: "https://www.serviceA.com", ...})
function ReactElement() {

  return (
     // generateLink("serviceA", "/a") = "https://www.serviceA.com/a/test?qa=55"
    <Link href={generateLink("serviceA", {pathname:"/a/[id]", query:{id:"test", qs:55}})}>
      <div>move</div>
    </div>
  );
}

API

generateServiceLink(originMapping): (link: string | {pathname:string, query?:{}} ) => string

• parameters
  • originMapping
    • 전체 package들의 origin 값 입니다. (ex, {serviceA:"https://www.serviceA.com", serviceB:"https..." ...})
• return
  • (link: string | {pathname:string, query?:{}} ) => string
    • link
      • 추출된 url path이 추론되며 {pathname:string, query?:{}}형태로도 사용할수 있습니다(<Link/>의 href, router.push()의 parameter type과 동일합니다)

generateInternalLink

현재위치의 package에 해당하는 link를 만들때 사용합니다.

Usage

import {generateInternalLink} from 'next-route-typesafe';
function ReactElement() {

  return (
    // generateInternalLink({pathname:"/a/[id]", query: {id:22}}) = "/a/22
    <Link href={generateInternalLink({pathname:"/a/[id]", query: {id:22}})}>
      <a>move</a>
    </div>
  );
}

API

generateInternalLink(link: string | {pathname:string, query?:{}} ): string

• parameters
  • link
    • 추출된 url path가 추론되며 {pathname:string, query?:{}}형태로도 사용할수 있습니다(<Link/>의 href, router.push()의 parameter type과 동일합니다)