Routify 3

!IMPORTANT!

**This repo is under heavy development and everything from code to documentation is far from complete.

DOCS - work in progress

If you have questions about how to use Routify 3, please see the docs or visit us on Discord.

Install

Create a new Routify project with

npx @roxi/routify@next create myapp

Using Routify

Creating a router

Basic

<script>
    import { Router } from '@roxi/routify'
    import routes from '../.routify/routes.default.js'
</script>

<Router {routes} />

Create instance manually

<script>
    import { Routify, Router } from '@roxi/routify'
    import routes from '../.routify/routes.default.js'
    const instance = new Routify({ routes, /* options */ })
</script>

<Router {instance} />

Creating nodes

// create a root node
const rootNode = instance.superNode.createChild('my-root-node')

// create a page node
rootNode.createChild('im-page-1', module)
rootNode.createChild('im-page-2', module)

// Note: module can be a module or its path

Appending nodes

// create a root node
const rootNode = instance.createNode('my-root-node')
instance.superNode.appendChild(rootNode)

// create a page node
const childNode = instance.createNode('my-child-node')
rootNode.appendChild(childNode)

Structure (draft)

• Global (class)
  • Instance (class)
    • nodeIndex (array)
    • superNode (class)
    • Router* (module)
      • Router (class)
        • params
        • activeUrl** (ActiveUrl)
        • activeRoute** (Route)
          • fragments (RouteFragment[])
      • module* (module)
        • module* (module)
          • module* (module) ...

*: module

**: Store

API

Table of Contents

• RoutifyBuildtimePayload
• RoutifyCallback
  • Parameters
• RoutifyBuildtimeOptions
  • Properties
• RoutifyRuntimeOptions
  • Properties
• TransformFragmentsCallback
• RoutifyExternalMetaHelper
  • Properties
• RoutifyLoadReturn
  • Parameters
  • Properties
• RoutifyBuildtimeRuntimePlugin
  • Properties
• RoutifyRuntimePlugin
• RoutifyBasePlugin
  • Properties
• RoutifyBuildtimePluginType
  • Properties
• MetaContextSplit
  • Parameters
• MetaContext
  • Properties
• UrlRewriteFn
  • Parameters
• UrlRewrite
  • Properties
• QueryHandler
  • Properties
• QueryHandlerParse
  • Parameters
• QueryHandlerStringify
  • Parameters
• ComponentGuardFn
  • Parameters
  • Properties
• PathNode
  • Properties
• UrlState
• FragmentContext
  • Properties
• NodeTreeExport
  • Properties
• BrowserAdapter

RoutifyBuildtimePayload

COMMON

Type: {instance: RoutifyBuildtime, tools: any}

RoutifyCallback

Type: Function

Parameters

• first {instance: Routify}

Returns (T | Promise<T>)

RoutifyBuildtimeOptions

Type: Object

Properties

• Node RNodeBuildtime

• routifyDir string defaults to '.routify'

• clearRoutifyDir boolean

• filemapper object

  • filemapper.moduleFiles Array<string> defaults to ['_module.svelte', '_reset.svelte']
  • filemapper.resetFiles Array<string> defaults to ['_reset.svelte']
  • filemapper.fallbackFiles Array<string> defaults to ['_reset.svelte']

• routesDir (string | Object<string, string>) defaults to { default: 'src/routes' }

• extensions Array<(string | RegExp)> defaults to ['.svelte', '.html', '.md', '.svx'],

• plugins (Array<string> | Array<Object>)

• watch boolean rebuild Routify routes on changes

RoutifyRuntimeOptions

Type: Object

Properties

• instance RoutifyRuntime instance to use. Uses global by default
• rootNode RNodeRuntime
• routes any the routes tree
• name string name of router - leave blank if only only one router is used
• urlRewrite (UrlRewrite | Array<UrlRewrite>) hook: transforms paths to and from router and browser
• url string? initial url - "/" by default
• passthrough (Boolean | Router) ignore clicks
• beforeRouterInit MaybeArray<RouterInitCallback> hook: runs before each router initiation
• afterRouterInit MaybeArray<RouterInitCallback> hook: runs after each router initiation
• beforeUrlChange MaybeArray<BeforeUrlChangeCallback> hook: guard that runs before url changes
• afterUrlChange MaybeArray<AfterUrlChangeCallback> hook: runs after url has changed
• transformFragments MaybeArray<TransformFragmentsCallback> hook: transform route fragments after navigation
• onDestroy MaybeArray<OnDestroyRouterCallback> hook: runs before router is destroyed
• queryHandler QueryHandler
• plugins Array<Partial<RoutifyRuntimeOptions>>

TransformFragmentsCallback

Type: function (Array<RouteFragment>): Array<RouteFragment>

RoutifyExternalMetaHelper

Type: Object

Properties

• instance RoutifyRuntime
• options any //todo
• tempPath string

RoutifyLoadReturn

Type: object

Parameters

• context RoutifyLoadContext

Properties

• route Route
• node RNodeRuntime
• status number
• error (string | Error)
• redirect string
• maxage number
• props object

Returns MaybePromise<(Partial<RoutifyLoadReturn> | null)>

RoutifyBuildtimeRuntimePlugin

Type: object

Properties

• path string example: '@roxi/routify/plugins/reset'
• importee string the imported name from the path, defaults to "default"
• options object options passed to the runtime plugin

RoutifyRuntimePlugin

Type: Partial<RoutifyRuntimeOptions>

RoutifyBasePlugin

Type: Object

Properties

• name string? name of plugin
• before (string | Array<string>)? name of plugin(s) to run before
• after (string | Array<string>)? name of plugin(s) to run after
• options function (Partial<RoutifyBuildtimeOptions>): Partial<RoutifyBuildtimeOptions> runs before "build"

RoutifyBuildtimePluginType

Type: Object

Properties

• build function (RoutifyBuildtimePayload): (Promise<any> | any)? runs after "options"
• path string?
• meta RoutifyExternalMetaHelper?
• runtimePlugins Array<RoutifyBuildtimeRuntimePlugin>

MetaContextSplit

Type: Function

Parameters

• value any the value to be split
• name string? defaults to hashed value

MetaContext

Modify the context available to meta files

Type: Object

Properties

• instance RoutifyBuildtime
• node RNodeBuildtime
• options Partial<RoutifyBuildtimeOptions>
• split MetaContextSplit? dynamically import the value
• tempPath string temporary path for the respective file, eg. ./.routify/cached/src/routes/index.svelte/

UrlRewriteFn

Type: Function

Parameters

• url string
• ctx {router: Router}

Returns string

UrlRewrite

Type: Object

Properties

• toInternal UrlRewriteFn
• toExternal UrlRewriteFn

QueryHandler

Type: Object

Properties

• parse QueryHandlerParse
• stringify QueryHandlerStringify

QueryHandlerParse

Type: Function

Parameters

• search string
• route Route

Returns Object<string, string>

QueryHandlerStringify

Type: Function

Parameters

• search Object<string, string>
• route Route

Returns string

ComponentGuardFn

Type: Function

Parameters

• route Route

Properties

• guard ComponentGuardFn?
• load RoutifyLoad?

PathNode

Type: Object

Properties

• urlFragment string
• node RNodeRuntime

UrlState

Type: ("pushState" | "replaceState" | "popState")

FragmentContext

Type: Object

Properties

• route Route
• node RNodeRuntime
• load function? preload functionality for pages and modules
• localParams Object<string, any>

NodeTreeExport

Type: Object

Properties

• id string
• name string?
• module any
• rootName string?
• file any?
• children Array<NodeTreeExport>

BrowserAdapter

Type: Object