Functions

Navi exports two functions for working with routes.

resolve()

resolve(
  urlOrUrls: string | string[],
  options: {
    routes: Matcher<Context>
    basename?: string
    context?: Context

    body?: any,
    headers?: { [name: string]: string },
    method?: string,

    followRedirects?: boolean,
  }
): Promise<Route>

Resolve allows you to find the route that corresponds to a given request. It doesn’t require access to a navigation object, letting you find Route objects on demand. Instead, it requires that you pass it a routes Matcher, and also allows you to set a context and basename — just as you can when creating a Navigation object.

By default, resolve() will not follow redirects, but instead return a Route object with a type of 'redirect'. To make it follow redirects, you can pass it a { followRedirects: true } option.

crawl()

crawl(options: {
  // Configuration for the routes to crawl
  routes: Matcher<Context>
  basename?: string
  context?: Context

  // The bottom-most URL that should be crawled.
  root?: string | URLDescriptor

  // Allows you to specify that some items (and their children) should
  // not be cawled.
  predicate?: (request: CrawlItem) => boolean

  // Allows you to crawl patterns like `/resource/:id` by returning array
  // of URLs to crawl in their place.
  expandPattern?: (
    pattern: string,
  ) => undefined | string[] | Promise<undefined | string[]>

  // Options to set on the default `request` objects.
  headers?: { [name: string]: string }
  hostname?: string
  method?: string

  // Should the output URLs have a trailing slash added or removed?
  // By default, it is removed.
  trailingSlash?: 'add' | 'remove' | null
}): Promise<{
  paths: string[]
  redirects: {
    [name: string]: string
  }
}>

Returns a Promise to an object containing all of the paths within the given routes object.

At a high level, the crawl() function works by generating requests for patterns in each of your mount() matchers. These request objects can be distinguished from standard request objects, as they’ll have a crawler property that contains the function that maps patterns to further requests.

By default, requests generated by crawl() will also have a method of 'HEAD'.

The crawl() function is used by navi-scripts to build the list of URLs that should be statically rendered.

withCrawlerPatterns()

You can also configure the crawler’s behavior for a specific mount() matcher by use of the withCrawlerPatterns() matcher.

To use withCrawlerPatterns(), you should compose it with the mount() that you want to configure, and pass in a list of functions that expand patterns to their available strings. For example:

// 
compose(
  withCrawlerPatterns({
    '/:tag': async ({ context }) => {
      let tags = await context.api.getTags()
      return tags.map(tag => '/'+tag)
    }
  }),
  mount({
    '/:tag': lazy(() => import('./tagRoute'))
  })
)

The functions supplied to withCrawlerPatterns() will only be called during a crawl() — they will not be called during standard routing.