pathpida

The generated helpers for App Router routes follow a specific pattern to ensure type safety for both the path and the query parameters.

For a route with dynamic segments, the helper is generated as a function. The signature depends on whether a Query type was detected in the source file:

1. With Query Type: If pathpida detects a query type in the page.tsx file, the helper accepts a url object containing both the query and an optional hash.
2. Without Query Type: The helper accepts the dynamic segments directly as arguments and returns an object containing the pathname, query, hash, and path.

Dynamic Segment Types:

• [slug]: Generates a string | number type.
• [...slug]: Generates a string[] type.
• [[...slug]]: Generates an optional parameter.

Returned Object Shape: Every helper returns an object with:

• pathname: The static string representation of the route.
• query: An object containing the parsed query parameters.
• hash: The URL hash.
• path: A template string (e.g., /${slug}) used for actual navigation.

// Example of what the generated code looks like for a route like /blog/[slug]
$blog_slug: (slug: string) => ({
  pathname: '/blog/[slug]' as const,
  query: { ... },
  hash: url.hash,
  path: `/blog/${slug}`
});

// Example for a route with a Query type
$blog_slug: (url: { query: BlogQuery, hash?: string }) => ({
  pathname: '/blog/[slug]' as const,
  query: { ...url.query },
  hash: url.hash,
  path: `/blog/${slug}`
});

pathpida uses the parsePagesDir function to scan a directory (typically a Next.js pages directory) and generate a type-safe object representing the available routes.

Key Behaviors

• File Filtering: It ignores files starting with _, .d.ts files, and the /api route. It also respects an ignorePath via an ignore utility.
• Dynamic Routes:
  • Single dynamic segments like [id].tsx are converted into functions that accept a string | number slug.
  • Catch-all routes like [[...slug]].tsx are converted into functions that accept an optional string[] slug.
  • Nested catch-all routes like [...slug].tsx are converted into functions that accept a required string[] slug.
• Index Files: Files named index.tsx (or other supported extensions) are treated as the base route for a directory.
• Query Type Extraction: The parser attempts to extract query types from TypeScript files using parseQueryFromTS to provide type safety for the query object in the generated route methods.
• Output: It returns an object containing an array of imports required for the generated file and the generated text (the route object string).

// The core function used by the CLI/generator to process the pages directory
const { imports, text } = parsePagesDir(
  inputDir,
  outputDir,
  ignorePath,
  ['tsx', 'ts', 'jsx', 'js']
);

When using pathpida with the Next.js App Router, the tool scans your directory structure to generate type-safe URL helpers. It applies specific transformation rules to handle Next.js-specific routing features:

• Route Groups: Directories wrapped in parentheses, e.g., (marketing), are ignored in the resulting URL path.
• Parallel Routes: Directories starting with @, e.g., @modal, are ignored in the resulting URL path.
• Dynamic Segments: Segments like [slug] are converted into function parameters in the generated code.
• Catch-all Segments: Segments like [...slug] are converted into parameters that accept an array (e.g., string[]).
• Optional Catch-all Segments: Segments like [[...slug]] are treated as optional parameters.

The final url generated for a route is the combination of the directory structure after stripping route groups and parallel routes.

After running pathpida, a $path.ts file is generated in lib/ or utils/. You can import pagesPath to generate URLs for your Next.js pages. This ensures that dynamic segments (like [pid] or [...slug]) and required query parameters are type-checked.

import Link from 'next/link';
import { pagesPath } from '../lib/$path';

// Static path
console.log(pagesPath.post.create.$url()); // { pathname: '/post/create' }

// Dynamic segment [pid]
console.log(pagesPath.post._pid(1).$url()); // { pathname: '/post/[pid]', query: { pid: 1 }}

// Catch-all segment [...slug]
console.log(pagesPath.post._slug(['a', 'b', 'c']).$url()); // { pathname: '/post//[...slug]', query: { slug: ['a', 'b', 'c'] }}

// With query parameters
console.log(pagesPath.post._pid(1).$url({ query: { limit: 10 }, hash: 'sample' })); 
// { pathname: '/post/[pid]', query: { pid: 1, limit: 10 }, hash: 'sample' }

export default () => {
  return (
    <>
      <Link href={pagesPath.post._slug(['a', 'b', 'c']).$url()} />
    </>
  );
};

The parseQueryFromTS function is a utility used to identify and extract type definitions for queries (specifically Query or OptionalQuery interfaces/types) from a TypeScript file. It generates a unique, hashed import name to prevent naming collisions when these types are imported into generated static files.

Behavior:

1. It searches the provided file for an exported interface Query, interface OptionalQuery, type Query, or type OptionalQuery.
2. If found, it calculates a relative importPath from the output directory to the source file.
3. It generates a unique importName by combining the type name with a hash of the import path.
4. It returns an object containing the importName and a formatted importString statement.

Returns: An object containing:

• importName: The aliased name (e.g., Query_abc123).
• importString: A valid TypeScript import statement (e.g., import type { Query as Query_abc123 } from './path/to/file';).

Returns undefined if no matching Query or OptionalQuery type is found in the file.

// Example usage (conceptual):
const result = parseQueryFromTS('./generated/output', './src/api/user.ts');

if (result) {
  console.log(result.importName);   // e.g., "Query_hash"
  console.log(result.importString); // e.g., "import type { Query as Query_hash } from './user';"
}