cyclic-router

6.0.0 verified Fri May 01 auth: no javascript

A routing library for Cycle.js applications, wrapping the main function to provide route matching and navigation. Current stable version is 6.0.0, released sporadically with a focus on incremental improvements. Unlike older versions (V4 and below) that acted as drivers, V5+ uses a `routerify` wrapper that works with `@cycle/history` and supports route parameters, basename configuration, and raw history access. Differentiators include integration with switch-path matcher and explicit route-to-component mapping via `routedComponent()`. Requires peer dependencies `@cycle/history` and `history`.

Common errors

error Cannot find module '@cycle/history' ↓

cause @cycle/history is a peer dependency not automatically installed.

fix

npm install @cycle/history

error TypeError: sources.router.routedComponent is not a function ↓

cause Cycle.js main function not wrapped with routerify, or routerify not called correctly.

fix

Ensure you wrap main: const mainWithRouting = routerify(main, switchPath); and use sources.router in main.

error export 'routerify' was not found in 'cyclic-router' ↓

cause Wrong import syntax or old version of cyclic-router (V4 or earlier).

fix

Update to cyclic-router V5+ and use import { routerify } from 'cyclic-router'.

Warnings

breaking V5 changed from a driver-based architecture to a main wrapper (routerify). Driver patterns from V4 are incompatible. ↓

fix Upgrade to V5+ and wrap your main function with routerify, passing sources.router instead of sources.history.

deprecated V4 and earlier are deprecated; new features and fixes only for V5+. ↓

fix Upgrade to cyclic-router V5+.

gotcha routedComponent expects the full sources object, not just DOM. Passing only DOM will cause nested components to receive undefined sources. ↓

fix Always pass sources (the full sources object) to routedComponent's returned function.

gotcha The router sink is named 'router' by default, but it proxies the history driver. Sinks named 'history' will be hidden unless omitHistory is set to false. ↓

fix Use 'router' for navigation; set omitHistory: false if you need raw history access.

Install

npm install cyclic-router

yarn add cyclic-router

pnpm add cyclic-router

Imports

routerify
wrong
```
const routerify = require('cyclic-router').routerify
```
correct
```
import { routerify } from 'cyclic-router'
```
ESM import preferred; CommonJS require also works with Node.js but may have interop issues.

RouterOptions

wrong

const RouterOptions = require('cyclic-router').RouterOptions

correct

import { RouterOptions } from 'cyclic-router'

TypeScript type export; only available when using TypeScript via 'import type'.

routedComponent
wrong
```
sources.router.routedComponent({...})(sources.DOM)
```
correct
```
sources.router.routedComponent({...})(sources)
```
routedComponent expects the full sources object, not just DOM, to pass to nested components.

Quickstart

Minimal Cycle.js app using routerify to route between Home and Other components.

import xs from 'xstream';
import { run } from '@cycle/run';
import { makeDOMDriver } from '@cycle/dom';
import { routerify } from 'cyclic-router';
import { makeHistoryDriver } from '@cycle/history';
import switchPath from 'switch-path';

function HomeComponent(sources) {
  return {
    DOM: xs.of('<div>Home</div>')
  };
}

function OtherComponent(sources) {
  return {
    DOM: xs.of('<div>Other</div>')
  };
}

function main(sources) {
  const pageSinks$ = sources.router.routedComponent({
    '/': HomeComponent,
    '/other': OtherComponent
  })(sources);

  return {
    DOM: pageSinks$.map(c => c.DOM).flatten(),
    router: xs.of('/other')
  };
}

const mainWithRouting = routerify(main, switchPath);

run(mainWithRouting, {
  DOM: makeDOMDriver('#app'),
  history: makeHistoryDriver()
});