# @sanity/state-router

> A path pattern => state object bidirectional mapper

Latest version **2.35.3** (published 2022-12-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install @sanity/state-router
pnpm add @sanity/state-router
yarn add @sanity/state-router
bun add @sanity/state-router
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 2.35.3 |
| Published | 2022-12-21 |
| First published | 2016-09-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 208.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6377 |
| Author | Sanity.io |
| Maintainers | svirs, josh_sanity_io, joneidejohnsen, nina.andal, rankers, snorreeb, mattcraig, vincentquigley, stipsan, michael-sanity, rubioz, tonina, ritasdias, simeonsanity, kmelve, bjoerge, rexxars, skogsmaskin, simenss, robinpyon, mariuslundgard, sanity-io, evenw, radhe_sanity, rbotten, vicbergquist, judofyr, obliadp, dcilke, fredcarlsen, jorn_georg, hermanw, mikolajsanity, sgulseth, atombender |
| Keywords | sanity, cms, headless, realtime, content, state-router |

## Links

- npm: https://www.npmjs.com/package/@sanity/state-router
- Repository: https://github.com/sanity-io/sanity
- Homepage: https://www.sanity.io/
- Issues: https://github.com/sanity-io/sanity/issues
- npm.io page: https://npm.io/package/@sanity/state-router

## Dependencies (3)

- [debug](https://npm.io/package/debug.md) ^3.2.7
- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [nano-pubsub](https://npm.io/package/nano-pubsub.md) ^2.0.1

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 2.35.3 (latest) — 2022-12-21
- 2.36.6 (v2) — 2024-11-07
- 2.36.2-weighted-search.16 (weighted-search) — 2023-07-14
- 2.34.3-cdr-ga-4.23 (cdr-ga-4) — 2022-10-20
- 2.34.3-cdr-ga-2.19 (cdr-ga-2) — 2022-10-20
- 2.34.3-cdr-ga.20 (cdr-ga) — 2022-10-20
- 2.34.3-cdr-preview.20 (cdr-preview) — 2022-10-20
- 2.34.2-empty-template-cli.0 (empty-template-cli) — 2022-10-13
- 2.34.1-canary.0 (canary) — 2022-10-12
- 2.33.4-shopify.8 (shopify) — 2022-09-22
- 2.33.4-performance-opts.16 (performance-opts) — 2022-09-22
- 2.33.3-edge.8 (edge) — 2022-09-20
- 2.30.7-findability.87 (findability) — 2022-09-20
- 2.33.1-performance-opts-doc-pane.2 (performance-opts-doc-pane) — 2022-09-12
- 2.32.1-next.22 (next) — 2022-09-08
- … 689 more at https://npm.io/package/@sanity/state-router/versions

## README

# ⚠️ THIS PACKAGE IS DEPRECATED

> This package is part of Sanity Studio v2, which has been superseded by **Sanity Studio v3**, the current major version released on Dec 7th, 2022. This package is no longer used/needed for Sanity Studio in its current version and will be retired on Dec 7th, 2023. The core packages for Sanity Studio v2 will only receive critical bug fixes until this date.
>
> Please head over to [the documentation for Sanity Studio v3](https://www.sanity.io/docs/sanity-studio) to learn more.

## @sanity/state-router

## Features

Based on a routing schema:

- A state object can be derived from the current pathname
- A state object can be used to generate a path name

## API Usage

Define the routes for your application and how they should map to application state

```js
import {route} from '@sanity/state-router'

const router = route('/', [route('/products/:productId'), route('/users/:userId'), route('/:page')])

router.encode({})
// => '/'
router.decode('/')
// => {}

router.encode({productId: 54})
// => '/products/54'

router.decode('/products/54')
// => {productId: 54}

router.encode({userId: 22})
// => '/users/22'

router.decode('/users/54')
// => {userId: 54}

router.encode({page: 'about'})
// => '/about'

router.decode('/about')
// => {page: about}
```

## React usage

### Setup routes and provider

```jsx
import {route} from '@sanity/state-router'
import {RouterProvider, withRouter} from '@sanity/state-router/components'

const router = route('/', [route('/bikes/:bikeId')])

const history = createHistory()

function handleNavigate(nextUrl, {replace} = {}) {
  if (replace) {
    history.replace(nextUrl)
  } else {
    history.push(nextUrl)
  }
}

const App = withRouter(function App({router}) {
  if (router.state.bikeId) {
    return <BikePage id={router.state.bikeId} />
  }
  return (
    <div>
      <h1>Welcome</h1>
      <StateLink state={{bikeId: 22}}>Go to bike 22</StateLink>
    </div>
  )
})

function render(location) {
  ReactDOM.render(
    <RouterProvider
      router={router}
      onNavigate={handleNavigate}
      state={router.decode(location.pathname)}
    >
      <App />
    </RouterProvider>,
    document.getElementById('container')
  )
}
history.listen(() => render(document.location))
```

## API

- `route(path : string, ?options : Options, ?children : ) : Router`
- `route.scope(name : string, path : string, ?options : Options, ?children : ) : Router`
- `Router`:

  - `encode(state : object) : string`
  - `decode(path : string) : object`
  - `isRoot(path : string) : boolean`
  - `getBasePath() : string`,
  - `isNotFound(pathname: string): boolean`
  - `getRedirectBase(pathname : string) : ?string`

- `RouteChildren`:
  ```
  Router | [Router] | ((state) => Router | [Router])
  ```
- `Options`:

  ```
  {
    path?: string,
    children?: RouteChildren,
    transform?: {[key: string] : Transform<*>},
    scope?: string
  }
  ```

  - `children` can be either another router returned from another `route()-call`, an array of routers or a function that gets passed the matched parameters, and conditionally returns child routes

## Limitations

- Parameterized paths _only_. Each route must have at least one unique parameter. If not, there's no way of unambiguously resolve a path from an empty state.

Consider the following routes:

```js
const router = route('/', [route('/about'), route('/contact')])
```

What route should be resolved from an empty state? Since both `/about` and `/contact` above resolves to an empty state object, there's no way to encode an empty state unambiguously back to either of them. The solution to this would be to introduce the page name as a parameter instead:

```js
const router = route('/', route('/:page'))
```

Now, `/about` would resolve to the state `{page: 'about'}` which unambiguously can map back to `/page`, and an empty state can map to `/`. To figure out if you are on the index page, you can check for `state.page == null`, (and set the state.page to null to navigate back to the index)

### No query params

Query parameters doesn't work too well with router scopes as they operate in a global namespace. A possible workaround is to "fake" query params in a path segment using transforms:

```js
function decodeParams(pathsegment) {
  return pathsegment.split(';').reduce((params, pair) => {
    const [key, value] = pair.split('=')
    params[key] = value
    return params
  }, {})
}
function encodeParams(params) {
  return Object.keys(params)
    .map((key) => `${key}=${params[key]}`)
    .join(';')
}

const router = route(
  '/some/:section/:settings',
  {
    transform: {
      settings: {
        toState: decodeParams,
        toPath: encodeParams,
      },
    },
  },
  route('/other/:page')
)
```

This call...

```js
router.decode('/some/bar/width=full;view=details')
```

...will return the following state

```js
{
  section: 'bar',
  settings: {
    width: 'full',
    view: 'details',
  }
}
```

Conversely calling

```js
router.encode({
  section: 'bar',
  settings: {
    width: 'full',
    view: 'details',
  },
})
```

will return

```
/some/bar/width=full;view=details
```

## Scopes

A scope is a separate router state space, allowing different parts of an application to be completely agnostic about the overall routing schema is like. Let's illustrate:

```js
import {route} from './src'
function findAppByName(name) {
  return (
    name === 'pokemon' && {
      name: 'pokemon',
      router: route('/:section', route('/:pokemonName')),
    }
  )
}

const router = route('/', [
  route('/users/:username'),
  route('/apps/:appName', (params) => {
    const app = findAppByName(params.appName)
    return app && route.scope(app.name, '/', app.router)
  }),
])
```

Decoding the following path...

```js
router.decode('/apps/pokemon/stats/bulbasaur')
```

...will give us the state:

```js
{
  appName: 'pokemon',
  pokemon: {
    section: 'stats',
    pokemonName: 'bulbasaur'
  }
}
```

## Intents

An _intent_ is a kind of global route that can be used for dispatching user actions. The intent route can be mounted with

```js
route.intents(<basePath>)
```

Intent links bypasses scoping, and will always be mapped to the configured `basePath`.

An intent consists of a name, e.g. `open` and a set of parameters, e.g. `{id: 'abc33'}` and the easiest way to make a link to an intent is using the `IntentLink` React component:

```jsx
<IntentLink intent="open" params={{id: abc33}}>
  Open document
</IntentLink>
```

This will generate an `<a` tag with a href like `/<base path>/open/id=abc33` depending on where the intent handler is mounted

State router comes with a built in intent-route parser that decodes an intent route to route state.

Full example:

```
const router = route('/', [
  route('/users/:username'),
  route.intents('/intents') // <-- sets up intent routes at the /intents base path
])
```

Decoding the url `/intents/open/id=abc33` will produce the following state:

```js
{
  intent: 'open',
  params: {id: 'abc33'}
}
```

It is now up to your application logic to translate this intent into an action, and redirect accordingly.

## 404s

To check whether a path name matches, you can use the isNotFound method on the returned router instance:

```js
const router = route('/pages/:page')

router.isNotFound('/some/invalid/path')
// => true
```

## Base paths

Using a base path is as simple as adding a toplevel route with no params:

```js
const router = route('/some/basepath', [route('/:foo'), route('/:bar')])
```

Any empty router state will resolve to `/some/basepath`. To check if you should redirect to the base path on app init, you can use the `router.isRoot(path)` and `router.getBasePath()` method:

```js
if (router.isRoot(location.pathname)) {
  const basePath = router.getBasePath()
  if (basePath !== location.pathname) {
    history.replaceState(null, null, basePath)
  }
}
```

For convenience, this check is combined in the method `router.getRedirectBase()`, that if a redirect is needed, will return the base path, otherwise `null`

```js
const redirectTo = router.getRedirectBase(location.pathname)
if (redirectTo) {
  history.replaceState(null, null, redirectTo)
}
```

## License

MIT-licensed

---
_Source: https://npm.io/package/@sanity/state-router · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._