setupHashUrl

utility

Installation

npx jsrepo add github/reatom/reusables setupHashUrl

Copy the source code below and save it to the specified file path in your project.

setup-hash-url.ts

import { onEvent, urlAtom } from '@reatom/core'

/**
 * Converts the current `window.location.hash` into a full URL object. Strips
 * the leading `#/` from the hash and joins with `window.origin`.
 *
 * @example
 *   // window.location.hash === '#/users/123'
 *   hashToUrl() // URL { pathname: '/users/123', ... }
 */
export const hashToUrl = () =>
  new URL([window.origin, window.location.hash.replace(/^#\//, '')].join('/'))

/**
 * Converts a pathname to a hash-prefixed string.
 *
 * @example
 *   pathToHash('/users/123') // '#/users/123'
 */
export const pathToHash = (path: string) => `#${path}`

/**
 * Configures `urlAtom` for hash-based routing (`#/path` instead of History
 * API). Sets the initial value from the hash, subscribes to `hashchange`, and
 * overrides sync to write hash URLs.
 *
 * Call once at app initialization before any routing runs.
 *
 * @see https://dev.to/guria/reatom-extensibility-saves-the-day-595e
 */
export const setupHashUrl = () => {
  urlAtom.syncFromSource(hashToUrl(), true)

  onEvent(window, 'hashchange', () => urlAtom.syncFromSource(hashToUrl(), true))

  urlAtom.sync.set(() => (url, replace) => {
    const path = url.href.replace(window.origin, '')
    if (replace) {
      history.replaceState({}, '', pathToHash(path))
    } else {
      history.pushState({}, '', pathToHash(path))
    }
  })
}

Documentation

setupHashUrl

Switches urlAtom to hash-based routing (#/path instead of History API paths). All existing routing logic works unchanged — only the browser URL format changes.

`setupHashUrl()`

Call once at app initialization before any routing runs.

Parameters

None.

Example

import { setupHashUrl } from '#reatom/utility/setup-hash-url'

setupHashUrl()

// Now urlAtom.go('/users/123') writes #/users/123 to the address bar

Exported helpers

`hashToUrl()`

Converts the current window.location.hash into a URL object.

Returns	Description
`URL`	URL parsed from current hash

`pathToHash(path)`

Converts a pathname to a hash-prefixed string.

Parameter	Type	Description
`path`	`string`	The path to hash

Returns	Description
`string`	Hash-prefixed path (`#/path`)

How it works

Sets urlAtom initial value from window.location.hash (disables default History API init)
Subscribes to hashchange events via onEvent, syncing hash changes into urlAtom
Overrides urlAtom.sync to write hash URLs via history.pushState / history.replaceState

Reference

Based on the pattern from Reatom Extensibility Saves the Day.

Example

import { urlAtom } from '@reatom/core'

import { hashToUrl, pathToHash, setupHashUrl } from './setup-hash-url'

// Call once at app initialization.
// All routing now uses hash-based URLs: #/path instead of /path.
setupHashUrl()

// Navigate — writes #/users/123 to the address bar
urlAtom.go('/users/123')

// Read current URL from hash
console.log(urlAtom().pathname) // '/users/123'

// Helpers are available for custom use
console.log(hashToUrl()) // URL { pathname: '/users/123', ... }
console.log(pathToHash('/about')) // '#/about'