Better Nextjs Routes

[jonkwheeler]

Goals

1. Improved Types for API Routes and Page Routes, for both Static and Dynamic.
2. Easier feature opt-in.
3. Easier href creation combining path, params, searchParams, and hash.

Non-Goals

1. Changing the current typedRoutes, which are baked into the next/link component

Background

I believe the current typings for routes in next.js are lacking. I also do not believe they should be baked into the next/link component as they are today. Instead of a feature flag for adoption, import a helper function to opt-in and help build your fully typed route.

Proposal

During dev and build, run a script to scan the app/pages directory. I will show code for the app directory, but adding pages compatibility would be easy.

#!/usr/bin/env node
// gen-route-tree.js

const fs = require('fs')
const path = require('path')

// ------------------------------
// FS helpers
// ------------------------------
function readAllFilesRecursive(dir, out) {
  if (!out) out = []
  const entries = fs.readdirSync(dir)

  for (const entry of entries) {
    if (entry === '.DS_Store') continue

    const fp = path.join(dir, entry)
    const stat = fs.statSync(fp)

    if (stat.isDirectory()) {
      readAllFilesRecursive(fp, out)
    } else {
      out.push(fp)
    }
  }
  return out
}

// ------------------------------
// Path transforms
// ------------------------------
function isPageFile(relPath) {
  return relPath.endsWith('/page.tsx') || relPath.endsWith('/route.ts')
}

function containsDynamicParam(input) {
  // any [param], [...param], or [[...param]]
  return /\[[^\]]+\]/.test(input)
}

function removeSrcAppPrefix(relPath) {
  // Normalize to forward slashes before replacing
  const norm = relPath.replace(/\\/g, '/')
  if (norm.startsWith('src/app/')) return norm.slice('src/app/'.length)
  if (norm === 'src/app') return ''
  return norm
}

function stripTrailingPageTsx(appRel) {
  if (appRel.endsWith('/page.tsx')) return appRel.slice(0, -'/page.tsx'.length)
  if (appRel.endsWith('/route.ts')) return appRel.slice(0, -'/route.ts'.length)
  if (appRel === 'page.tsx') return ''
  if (appRel === 'route.ts') return ''
  return appRel
}

function isGroupSegment(seg) {
  // Remove any Next.js route group segments like (marketing), (portal), etc.
  return seg.length >= 2 && seg.startsWith('(') && seg.endsWith(')')
}

function normalizeRoutePath(appRelNoPage) {
  // Split, drop empty pieces and group segments, join back
  const parts = appRelNoPage
    .split('/')
    .filter(function keep(p) {
      return p.length > 0
    })
    .filter(function dropGroups(p) {
      return !isGroupSegment(p)
    })

  if (parts.length === 0) return '/'

  const joined = '/' + parts.join('/')
  // Ensure no trailing slash (except root)
  return joined !== '/' && joined.endsWith('/') ? joined.slice(0, -1) : joined
}

function toProjectRelative(absPath, projectRoot) {
  return path.relative(projectRoot, absPath).replace(/\\/g, '/')
}

// ------------------------------
// Param extraction
// ------------------------------
function extractParamsFromRoute(routePath) {
  // Finds bracketed segments: [id], [...slug], [[...slug]]
  // Then normalizes to bare param names: 'id', 'slug'
  // Dedupes and preserves order of first appearance.
  const params = []
  const seen = new Set()

  // Match every [ ... ] group, including the inner one of [[...slug]]
  const re = /\[([^[\]]+)\]/g
  let match
  while ((match = re.exec(routePath)) !== null) {
    /** raw might be: "id", "...slug", "[...slug" (rare malformed), etc. */
    let raw = match[1]

    // If optional catch-all like [[...slug]], inner match is "...slug"
    // Normalize any leading/trailing brackets (defensive)
    raw = raw.replace(/^\[+|\]+$/g, '')

    // Remove catch-all prefix "..."
    if (raw.startsWith('...')) {
      raw = raw.slice(3)
    }

    // Basic sanity: allow a-z, 0-9, _ only in final param name
    const clean = raw.replace(/[^a-zA-Z0-9_]/g, '')
    if (clean.length > 0 && !seen.has(clean)) {
      seen.add(clean)
      params.push(clean)
    }
  }

  return params
}

// ------------------------------
// Emit
// ------------------------------
function writeOutput(outputFile, staticRoutes, dynamicRouteObjects) {
  const banner = `// AUTO-GENERATED FILE - DO NOT EDIT
// Generated by scripts/gen-route-tree.js

`
  const body = `${banner}export const staticPageRoutes = ${JSON.stringify(staticRoutes, null, 2)} as const;

export const dynamicPageRoutes = ${JSON.stringify(dynamicRouteObjects, null, 2)} as const;

export type StaticPageRoute = typeof staticPageRoutes[number];
export type DynamicPageRoute = (typeof dynamicPageRoutes)[number];
`

  fs.writeFileSync(outputFile, body)
}

// ------------------------------
// Main
// ------------------------------
function main() {
  const projectRoot = path.resolve(__dirname, '../')
  const appDir = path.join(projectRoot, 'src/app')
  const genDir = path.join(projectRoot, 'src/gen')
  const outputFile = path.join(genDir, 'routeTree.gen.ts')

  if (!fs.existsSync(appDir)) {
    console.error('❌ src/app directory not found')
    process.exit(1)
  }

  fs.mkdirSync(genDir, { recursive: true })

  // 1) gather all files
  const allAbs = readAllFilesRecursive(appDir, [])
  const allRel = allAbs.map(function mapRel(p) {
    return toProjectRelative(p, projectRoot)
  })

  // 2) only page.tsx
  const pageRel = allRel.filter(isPageFile)

  // 3) transform to clean route paths
  const routePaths = pageRel.map(function toRoute(rel) {
    const appRel = removeSrcAppPrefix(rel) // drop "src/app/"
    const noPage = stripTrailingPageTsx(appRel) // drop "page.tsx"
    return normalizeRoutePath(noPage) // split, drop (groups), rejoin
  })

  // Optional: keep output stable for diffs
  routePaths.sort()

  // 4) split static vs dynamic; build dynamic objects with params
  const staticRoutes = []
  const dynamicRouteObjects = []

  for (let i = 0; i < routePaths.length; i++) {
    const p = routePaths[i]
    if (containsDynamicParam(p)) {
      const params = extractParamsFromRoute(p)
      dynamicRouteObjects.push({ path: p, params })
    } else {
      staticRoutes.push(p)
    }
  }

  writeOutput(outputFile, staticRoutes, dynamicRouteObjects)
  console.log(`✅ Route tree generated at ${outputFile}`)
}

main()

This simple script makes an array of static and dynamic routes. Here is an example output for the routeTree.gen.ts file.

// routeTree.gen.ts
// AUTO-GENERATED FILE - DO NOT EDIT
// Generated by scripts/gen-route-tree.js

export const staticPageRoutes = [
  '/a',
  '/a/c/accounts/bank-accounts',
  '/a/c/accounts/bank-accounts/add',
  '/a/c/accounts/blockchain-addresses',
  '/a/c/accounts/instant-liquidity-addresses/add',
  '/a/c/accounts/recipient-addresses/add',
  '/a/c/get-started',
  '/a/c/invite-team-members',
  '/a/c/issuances',
  '/a/c/issuances/add',
  '/a/c/mint/connections',
  '/a/c/mint/connections/add',
  '/a/c/organization',
  '/a/c/profile',
  '/a/c/redeem/connections',
  '/a/c/redeem/connections/add',
  '/a/i/invite-team-members',
  '/a/i/organization',
  '/a/i/profile',
  '/a/i/swap-pair-management',
  '/a/v/designated-addresses',
  '/a/v/designated-addresses/add',
  '/a/v/invite-team-members',
  '/a/v/organization',
  '/a/v/profile',
  '/api/block-explorer-proxy',
  '/api/internal/swap-pair-management-logging',
  '/api/v1/metrics/circulating-supply',
  '/login',
  '/logout',
  '/maintenance',
  '/onboarding',
  '/onboarding/persona',
] as const

export const dynamicPageRoutes = [
  {
    path: '/a/c/[feature]',
    params: ['feature'],
  },
  {
    path: '/a/c/accounts/bank-accounts/[pk]',
    params: ['pk'],
  },
  {
    path: '/a/c/accounts/instant-liquidity-addresses/[pk]',
    params: ['pk'],
  },
  {
    path: '/a/c/accounts/recipient-addresses/[pk]',
    params: ['pk'],
  },
  {
    path: '/a/c/issuances/[pk]',
    params: ['pk'],
  },
  {
    path: '/a/c/mint/connections/[pk]',
    params: ['pk'],
  },
  {
    path: '/a/c/redeem/connections/[pk]',
    params: ['pk'],
  },
  {
    path: '/a/v/designated-addresses/[pk]',
    params: ['pk'],
  },
  {
    path: '/api/rpc-proxy/[chainId]',
    params: ['chainId'],
  },
  {
    path: '/api/subgraph-proxy/chains/[chain]/subgraphs/[subgraph]',
    params: ['chain', 'subgraph'],
  },
  {
    path: '/api/webplatform-proxy/[...path]',
    params: ['path'],
  }
] as const

export type StaticPageRoute = (typeof staticPageRoutes)[number]
export type DynamicPageRoute = (typeof dynamicPageRoutes)[number]

Lastly, this is utilized in a new route function which can accept path, params, searchParams, and hash. path and params are fully typed.

function Component() {
  return (
    <Link
      href={route({
        path: "/a/c/[feature]",
        params: {
          feature: "instant-liquidity",
        },
        searchParams: {
          intent: "mint",
          send: "USDC",
          receive: "AUSD",
        },
      })}
    >
      Instant Liquidity
    </Link>
  );
}

Forward Thinking

Add pages compatibility.

A future improvement could be to allow a passed type from the user for params, searchParams, and hash. Meaning, if you have /product/[productType], you could create

const productRoute = (config) => route<PassedTypeForParams>(config)