No dudes en abrir una issue si encuentras un bug o quieres solicitar funciones
# Demo
Demo |
Enlace espejoLimitación de tamaño de URI, hasta 12KB es seguro
¡Añade una y sígueme para apoyar el proyecto!
Agradeceré tus comentarios/opiniones en [discusiones](https://github.com/asmyshlyaev177/state-in-url/discussions/1)
Comparte si te resulta útil.
[X.com](https://twitter.com/intent/tweet?&url=https://github.com/asmyshlyaev177/state-in-url)
[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/asmyshlyaev177/state-in-url)
[FB](https://www.facebook.com/sharer.php?u=https://github.com/asmyshlyaev177/state-in-url)
[VK](http://vk.com/share.php?url=https://github.com/asmyshlyaev177/state-in-url)
[¡Muéstrame solo el código!](#useurlstate)
## ¿Por qué usar `state-in-url`?
Guarda cualquier estado de usuario en los parámetros de consulta; imagina JSON en la URL de un navegador. Todo ello manteniendo los tipos y la estructura de los datos: por ejemplo, los números se decodificarán como números y no como cadenas, las fechas como fechas, etc.; se admiten objetos y matrices.
Simple a más no poder, rápido y con validación estática de TypeScript. Los enlaces profundos, es decir, la sincronización de URL, se vuelven fáciles.
Incluye el hook `useUrlState` para Next.js y react-router, y helpers para cualquier otra cosa en JS.
Como los navegadores modernos soportan URLs enormes y a los usuarios no les importan las cadenas de consulta (es un flujo de seleccionar todo y copiar/pegar).
Es hora de usar la cadena de consulta para gestionar el estado, como se pensó originalmente.
Esta biblioteca hace todo el trabajo tedioso por ti.
Esta biblioteca es una buena alternativa a NUQS.
### Casos de uso
- Guardar formularios de usuario no guardados o filtros de página en la URL
- Sincronizar la URL con el estado de React
- Solo sincronizar datos entre componentes de cliente no relacionados sin tocar la URI
- URLs compartibles con el estado de la aplicación (enlaces profundos, sincronización del estado en la URL)
- Persistencia sencilla del estado entre recargas de página
### Características
- 🧩 **Simple**: Sin providers, reducers, código repetitivo ni conceptos nuevos, API similar a `React.useState`
- 📘 **Validación/autocompletado de TypeScript**: El estado es solo un objeto, validación estática automática en el IDE/pruebas según la definición de TypeScript
- ✨ **Datos complejos**: Objetos anidados, fechas y matrices, funciona igual que JSON, pero en la URL
- ☂ **Valores por defecto**: Te da valores por defecto si el parámetro no está en la url
- ⌨ **Organizado**: Todos los valores posibles se definen al inicio, te protege de obtener una clave inexistente
- **compatible**: Mantendrá los parámetros de consulta de terceros tal cual
- **flexible**: Puede usar más de 1 objeto de estado en la misma página, solo usa claves diferentes
- **Rápido**: Mínimos re-renders, alrededor de [1ms](https://github.com/asmyshlyaev177/state-in-url/blob/87c8c7c995c5cd7d9e7aa039c30bfe64b24abe4b/packages/urlstate/encoder/encoder.test.ts#L185) para codificar y decodificar un objeto grande
- **Renderizado en el servidor**: Se puede usar en componentes de servidor, se soportan Next.js 14, 15 y 16
- **Ligero**: Cero dependencias, biblioteca de menos de 2KB
- **DX**: Buena experiencia de desarrollo, documentación, comentarios JSDoc y ejemplos
- **Flexibilidad de frameworks**: Hooks para `Next.js` y `react-router`, helpers para usarla con otros frameworks o JS puro
- **Bien probada**: [Pruebas unitarias y pruebas de Playwright para Chrome/Firefox/Safari](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)
- **Licencia permisiva**: MIT
## Tabla de contenido
- [State in url](#state-in-url)
- [Demo](#demo)
- [¿Por qué usar `state-in-url`?](#por-qué-usar-state-in-url)
- [Casos de uso](#casos-de-uso)
- [Características](#características)
- [Tabla de contenido](#tabla-de-contenido)
- [Instalación](#instalación)
- [1. Instalar el paquete](#1-instalar-el-paquete)
- [2. Editar tsconfig.json](#2-editar-tsconfigjson)
- [Uso con agentes de codificación con IA](#uso-con-agentes-de-codificación-con-ia)
- [useUrlState](#useurlstate)
- [Hook useUrlState para Next.js](#hook-useurlstate-para-nextjs)
- [Ejemplos de uso](#ejemplos-de-uso)
- [Básico](#básico)
- [Con renderizado del lado del servidor](#con-renderizado-del-lado-del-servidor)
- [Usar el hook en el componente `layout`](#usar-el-hook-en-el-componente-layout)
- [Con una forma de estado arbitraria (no recomendado)](#con-una-forma-de-estado-arbitraria-no-recomendado)
- [Hook useUrlState para Remix.js](#hook-useurlstate-para-remixjs)
- [Ejemplo](#ejemplo)
- [Hook useUrlState para React-Router](#hook-useurlstate-para-react-router)
- [Ejemplo](#ejemplo-1)
- [Recetas](#recetas)
- [Hook personalizado para trabajar cómodamente con una porción del estado](#hook-personalizado-para-trabajar-cómodamente-con-una-porción-del-estado)
- [Con una forma de estado compleja](#con-una-forma-de-estado-compleja)
- [Actualizar solo el estado y sincronizarlo manualmente con la URL](#actualizar-solo-el-estado-y-sincronizarlo-manualmente-con-la-url)
- [Otros hooks y helpers](#otros-hooks-y-helpers)
- [Hook `useUrlStateBase` para otros routers](#hook-useurlstatebase-para-otros-routers)
- [Hook `useSharedState` para React.js](#hook-usesharedstate-para-reactjs)
- [Hook `useLinkProps` para React.js](#hook-uselinkprops-para-reactjs)
- [Hook `useUrlEncode` para React.js](#hook-useurlencode-para-reactjs)
- [Helpers `encodeState` y `decodeState`](#helpers-encodestate-y-decodestate)
- [Helpers `encode` y `decode`](#helpers-encode-y-decode)
- [Buenas prácticas](#buenas-prácticas)
- [Trampas](#trampas)
- [Otros](#otros)
- [Contribuir y/o ejecutar localmente](#contribuir-yo-ejecutar-localmente)
- [Hoja de ruta](#hoja-de-ruta)
- [Contacto y soporte](#contacto-y-soporte)
- [Registro de cambios](#registro-de-cambios)
- [Menciones](#menciones)
- [Licencia](#licencia)
- [Contrátame](#contrátame)
- [Inspiración](#inspiración)
## Instalación
### 1. Instalar el paquete
```sh
# npm
npm install --save state-in-url
# yarn
yarn add state-in-url
# pnpm
pnpm add state-in-url
```
### 2. Editar tsconfig.json
En `tsconfig.json`, en `compilerOptions`, establece `"moduleResolution": "Bundler"`, o `"moduleResolution": "Node16"`, o `"moduleResolution": "NodeNext"`.
Posiblemente necesites establecer `"module": "ES2022"`, o `"module": "ESNext"`
## Uso con agentes de codificación con IA
`state-in-url` incluye archivos de habilidades (skills) para [@tanstack/intent](https://tanstack.com/intent/latest/docs/overview), de modo que los agentes de IA (Claude Code, Cursor, Copilot, Codex, etc.) carguen los patrones correctos y eviten errores comunes al usar la biblioteca. Tras instalar `state-in-url`, ejecuta una vez en tu proyecto:
```sh
npx @tanstack/intent@latest install
```
Esto configura tu agente instalado para que descubra las habilidades desde `node_modules/state-in-url/skills/`. Lista las habilidades disponibles con `npx @tanstack/intent@latest list`.
## useUrlState
Hook principal que toma el estado inicial como parámetro y devuelve el objeto de estado, un callback para actualizar la url y un callback para actualizar solo el estado.
Todos los componentes que usan el mismo objeto `state` se sincronizan automáticamente.
### Hook useUrlState para Next.js
[Documentación completa de la API](packages/urlstate/next/useUrlState)
[Ejemplo de React-Router](#hook-useurlstate-para-react-router)
#### Ejemplos de uso
##### Básico
1. Define la forma del estado con valores por defecto
```typescript
// userState.ts
// Solo los parámetros con valor distinto al predeterminado irán a la url.
export const userState: UserState = { name: '', age: 0 }
// ¡Usa `Type`, no `Interface`!
type UserState = { name: string, age: number }
```
2. Impórtalo y úsalo
```typescript
'use client'
import { useUrlState } from 'state-in-url/next';
import { userState } from './userState';
function MyComponent() {
// puedes pasar el argumento `replace`, controla si `setUrl` usará `router.push` o `router.replace`, por defecto replace=true
// puedes pasar `searchParams` desde componentes de servidor, pasa `useHistory: false` si necesitas obtener algo en el componente de servidor
const { urlState, setUrl, setState } = useUrlState(userState);
return (
// urlState.name devolverá el valor por defecto de `userState` si la url está vacía
currVal + 1)
onChange={(ev) => setUrl({ name: ev.target.value }) }
/>
setUrl({ age: +ev.target.value }) }
/>
{ setState(curr => ({ ...curr, name: ev.target.value })) }}
// Puede actualizar el estado inmediatamente pero sincronizar el cambio con la url según sea necesario
onBlur={() => setUrl()}
/>
)
}
```
##### Con renderizado del lado del servidor
Ejemplo
```typescript
export default async function Home({ searchParams }: { searchParams: object }) {
return (
)
}
// Form.tsx
'use client'
import React from 'react';
import { useUrlState } from 'state-in-url/next';
import { form } from './form';
const Form = ({ searchParams }: { searchParams: object }) => {
const { urlState, setState, setUrl } = useUrlState(form, { searchParams });
}
```
##### Usar el hook en el componente `layout`
Ejemplo
Eso es una parte delicada, ya que nextjs con app router no permite acceder a searchParams desde el lado del servidor. Hay una solución alternativa usando middleware, pero no es elegante y puede dejar de funcionar tras una actualización de nextjs.
```typescript
// añadir al `layout.tsx` apropiado
export const runtime = 'edge';
// middleware.ts
import type { NextRequest } from 'next/server';
import { NextResponse } from 'next/server';
export function middleware(request: NextRequest) {
const url = request.url?.includes('_next') ? null : request.url;
const sp = url?.split?.('?')?.[1] || '';
const response = NextResponse.next();
if (url !== null) {
response.headers.set('searchParams', sp);
}
return response;
}
// Componente layout de destino
import { headers } from 'next/headers';
import { decodeState } from 'state-in-url/encodeState';
export default async function Layout({
children,
}: {
children: React.ReactNode;
}) {
const sp = headers().get('searchParams') || '';
return (
{children}
);
}
```
##### Con una forma de estado arbitraria (no recomendado)
Ejemplo
```typescript
'use client'
import { useUrlState } from 'state-in-url/next';
const someObj = {};
function SettingsComponent() {
const { urlState, setUrl, setState } = useUrlState
### Hook useUrlState para Remix.js
La API es la misma que la de la versión para Next.js, excepto que se pueden pasar opciones del tipo [NavigateOptions](https://github.com/remix-run/react-router/blob/bc693ed9f39170bda13b9e1b282fb8e9d5925f66/packages/react-router/lib/context.ts#L99).
[Documentación de la API](packages/urlstate/remix/useUrlState)
#### Ejemplo
```typescript
export const form: Form = {
name: '',
age: undefined,
agree_to_terms: false,
tags: [],
};
type Form = {
name: string;
age?: number;
agree_to_terms: boolean;
tags: { id: string; value: { text: string; time: Date } }[];
};
```
```typescript
import { useUrlState } from 'state-in-url/remix';
import { form } from './form';
function TagsComponent() {
const { urlState, setUrl, setState } = useUrlState(form);
const onChangeTags = React.useCallback(
(tag: (typeof tags)[number]) => {
setUrl((curr) => ({
...curr,
tags: curr.tags.find((t) => t.id === tag.id)
? curr.tags.filter((t) => t.id !== tag.id)
: curr.tags.concat(tag),
}));
},
[setUrl],
);
return (
{ setState(curr => ({ ...curr, name: ev.target.value })) }}
// Puede actualizar el estado inmediatamente pero sincronizar el cambio con la url según sea necesario
onBlur={() => setUrl()}
/>
);
}
const tags = [
{
id: '1',
value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
},
{
id: '2',
value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
},
{
id: '3',
value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
},
];
```
[Ejemplo de código](packages/example-remix2/app/routes/Form-for-test.tsx)
### Hook useUrlState para React-Router
La API es la misma que la de la versión para Next.js, excepto que se pueden pasar opciones del tipo [NavigateOptions](https://github.com/remix-run/react-router/blob/bc693ed9f39170bda13b9e1b282fb8e9d5925f66/packages/react-router/lib/context.ts#L99).
[Documentación de la API](packages/urlstate/react-router/useUrlState)
#### Ejemplo
```typescript
export const form: Form = {
name: '',
age: undefined,
agree_to_terms: false,
tags: [],
};
type Form = {
name: string;
age?: number;
agree_to_terms: boolean;
tags: { id: string; value: { text: string; time: Date } }[];
};
```
```typescript
import { useUrlState } from 'state-in-url/react-router';
// para react-router v6
// import { useUrlState } from 'state-in-url/react-router6';
import { form } from './form';
function TagsComponent() {
const { urlState, setUrl, setState } = useUrlState(form);
const onChangeTags = React.useCallback(
(tag: (typeof tags)[number]) => {
setUrl((curr) => ({
...curr,
tags: curr.tags.find((t) => t.id === tag.id)
? curr.tags.filter((t) => t.id !== tag.id)
: curr.tags.concat(tag),
}));
},
[setUrl],
);
return (
{ setState(curr => ({ ...curr, name: ev.target.value })) }}
// Puede actualizar el estado inmediatamente pero sincronizar el cambio con la url según sea necesario
onBlur={() => setUrl()}
/>
);
}
const tags = [
{
id: '1',
value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
},
{
id: '2',
value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
},
{
id: '3',
value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
},
];
```
[Ejemplo de código](packages/example-react-router6/src/Form-for-test.tsx)
## Recetas
##### Hook personalizado para trabajar cómodamente con una porción del estado
Ejemplo
```typescript
'use client';
import React from 'react';
import { useUrlState } from 'state-in-url/next';
const form: Form = {
name: '',
age: undefined,
agree_to_terms: false,
tags: [],
};
type Form = {
name: string;
age?: number;
agree_to_terms: boolean;
tags: {id: string; value: {text: string; time: Date } }[];
};
export const useFormState = ({ searchParams }: { searchParams?: object }) => {
const { urlState, setUrl: setUrlBase, reset } = useUrlState(form, {
searchParams,
});
// la primera navegación añadirá una nueva entrada al historial
// todas las siguientes solo reemplazarán esa entrada
// de esta forma el historial tendrá solo 2 entradas - ['/url', '/url?key=param']
const replace = React.useRef(false);
const setUrl = React.useCallback((
state: Parameters[0],
opts?: Parameters[1]
) => {
setUrlBase(state, { replace: replace.current, ...opts });
replace.current = true;
}, [setUrlBase]);
return { urlState, setUrl, resetUrl: reset };
};
```
##### Con una forma de estado compleja
Ejemplo
```typescript
export const form: Form = {
name: '',
age: undefined,
agree_to_terms: false,
tags: [],
};
type Form = {
name: string;
age?: number;
agree_to_terms: boolean;
tags: { id: string; value: { text: string; time: Date } }[];
};
```
```typescript
'use client'
import { useUrlState } from 'state-in-url/next';
import { form } from './form';
function TagsComponent() {
// ¡`urlState` se inferirá del tipo Form!
const { urlState, setUrl } = useUrlState(form);
const onChangeTags = React.useCallback(
(tag: (typeof tags)[number]) => {
setUrl((curr) => ({
...curr,
tags: curr.tags.find((t) => t.id === tag.id)
? curr.tags.filter((t) => t.id !== tag.id)
: curr.tags.concat(tag),
}));
},
[setUrl],
);
return (
);
}
const tags = [
{
id: '1',
value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
},
{
id: '2',
value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
},
{
id: '3',
value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
},
];
```
[Ejemplo de código de la página de demo](https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/example-nextjs15/src/app/Form.tsx)
##### Actualizar solo el estado y sincronizarlo manualmente con la URL
Ejemplo
```typescript
const timer = React.useRef(0 as unknown as NodeJS.Timeout);
React.useEffect(() => {
clearTimeout(timer.current);
timer.current = setTimeout(() => {
// comparará el estado por contenido y no por referencia, y lanzará la actualización solo para valores nuevos
setUrl(urlState);
}, 500);
return () => {
clearTimeout(timer.current);
};
}, [urlState, setUrl]);
```
Sincronizar el estado en `onBlur` estará más alineado con el uso en el mundo real.
```typescript
updateUrl()} .../>
```
## Otros hooks y helpers
### Hook `useUrlStateBase` para otros routers
Hooks para crear tus propios hooks `useUrlState` con otros routers, p. ej. react-router o tanstack router.
[Documentación de la API](packages/urlstate/useUrlStateBase)
### Hook `useSharedState` para React.js
Hook para compartir estado entre cualquier componente de React, probado con Next.js y Vite.
```typescript
'use client'
import { useSharedState } from 'state-in-url';
export const someState = { name: '' };
function SettingsComponent() {
const { state, setState } = useSharedState(someState);
}
```
[Documentación de la API](packages/urlstate/useSharedState/README.es.md)
### Hook `useLinkProps` para React.js
Hook para llevar el estado a un enlace que apunta a otra ruta, por ejemplo un selector de idioma. `setUrl` siempre escribe en la ruta actual; este no.
```tsx
'use client'
import Link from 'next/link';
import { useRouter } from 'next/navigation';
import { useLinkProps } from 'state-in-url/useLinkProps';
export const form = { name: '' };
function LanguagePicker() {
const linkProps = useLinkProps(form, useRouter().push);
return Deutsch;
}
```
El marcado conserva el `href` tal cual, así que los rastreadores y `hreflang` ven la URL canónica; el estado se lee al hacer clic.
[Documentación de la API](packages/urlstate/useLinkProps/README.es.md)
### Hook `useUrlEncode` para React.js
[Documentación de la API](packages/urlstate/useUrlEncode/README.es.md)
### Helpers `encodeState` y `decodeState`
[Documentación de la API](packages/urlstate/encodeState/README.es.md)
### Helpers `encode` y `decode`
[Documentación de la API](packages/urlstate/encoder/README.es.md)
## Buenas prácticas
- Define la forma de tu estado como una constante
- Usa TypeScript para mayor seguridad de tipos y autocompletado
- Evita guardar información sensible en los parámetros de la URL (SSN, claves de API, etc.)
- Usa esta [extensión](https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors) para obtener errores de TS legibles
Puedes crear hooks de estado para porciones del estado y reutilizarlos en toda la aplicación. Por ejemplo:
```Typescript
type UserState = {
name: string;
age: number;
other: { id: string, value: number }[]
};
const userState = {
name: '',
age: 0,
other: [],
};
export const useUserState = () => {
const { urlState, setUrl, reset } = useUrlState(userState);
// otra lógica
// restablecer los parámetros de consulta al navegar a otra página
React.useEffect(() => {
return reset
}, [])
return { userState: urlState, setUserState: setUrl };;
}
```
## Trampas
1. Solo se pueden pasar valores serializables; `Function`, `BigInt` o `Symbol` no funcionarán, y probablemente tampoco cosas como `ArrayBuffer`. Todo lo que se pueda serializar a JSON funcionará.
2. Los servidores de Vercel limitan el tamaño de las cabeceras (la cadena de consulta y demás) a **14KB**, así que mantén el estado de tu URL por debajo de ~5000 palabras.
3. Probado con `next.js` 14/15/16 con app router; no hay planes de soportar pages.
## Otros
### Contribuir y/o ejecutar localmente
Consulta el [documento de contribución](CONTRIBUTING.md)
## Hoja de ruta
- [x] hook para `Next.js`
- [x] hook para `react-router`
- [x] hook para `remix`
- [ ] hook para `svelte`
- [ ] hook para `astro`
- [ ] hook para guardar el estado en el hash ?
## Contacto y soporte
- Crea un [GitHub issue](https://github.com/asmyshlyaev177/state-in-url/issues) para informes de errores, solicitudes de funciones o preguntas
## [Registro de cambios](CHANGELOG.md)
## Menciones
- [This Week in React 209](https://thisweekinreact.com/newsletter/209)
- [JavaScript Weekly](https://javascriptweekly.com/issues/741)
- [This Week in React 240](https://thisweekinreact.com/newsletter/240)
## Licencia
Este proyecto está licenciado bajo la [licencia MIT](LICENSE).
## Contrátame
Soy **Aleksandr Smyshliaev**, único autor y mantenedor de esta biblioteca.
Ingeniero frontend sénior (React / Next.js / TypeScript, más de 8 años) y **disponible para trabajo remoto a tiempo completo ahora mismo**.
Esta biblioteca es la versión resumida de lo que se me da bien: una API tipada sobre un primitivo de navegador desordenado, cero dependencias y estabilidad en Next.js, Remix y React Router a través de varias versiones mayores de React.
- **Se me da mejor** — bibliotecas de componentes, gestión de estado y suites de pruebas que sobreviven a un refactor.
- **También son míos** —
[react-horizontal-scrolling-menu](https://github.com/asmyshlyaev177/react-horizontal-scrolling-menu)
(~84k instalaciones semanales),
[test-proxy-recorder](https://github.com/asmyshlyaev177/test-proxy-recorder)
(grabación/reproducción para Playwright),
[llm-queue](https://github.com/asmyshlyaev177/llm-queue).
- **Dónde** — Tiflis, Georgia (GMT+4), solapamiento total con CET. Entidad contratista registrada, de modo que el compromiso B2B no necesita configuración de employer-of-record.
- **Contáctame** — [asmyshlyaev177.dev](https://asmyshlyaev177.dev) ·
[asmyshlyaev177@gmail.com](mailto:asmyshlyaev177@gmail.com) ·
[LinkedIn](https://linkedin.com/in/asmyshlyaev177) · Telegram @asmyshlyaev177
## Inspiración
[NUQS](https://github.com/47ng/nuqs)
[Usar la URL para almacenar estado en Vue](https://dev.to/jacobandrewsky/using-url-to-store-state-in-vue-275c)
[Almacenar el estado en la URL](https://antonz.org/storing-state/)
[NextJS useSearchParams](https://nextjs.org/docs/app/api-reference/functions/use-search-params)
# State in url
y sígueme para apoyar el proyecto!
Agradeceré tus comentarios/opiniones en [discusiones](https://github.com/asmyshlyaev177/state-in-url/discussions/1)
Comparte si te resulta útil.
[X.com](https://twitter.com/intent/tweet?&url=https://github.com/asmyshlyaev177/state-in-url)
[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/asmyshlyaev177/state-in-url)
[FB](https://www.facebook.com/sharer.php?u=https://github.com/asmyshlyaev177/state-in-url)
[VK](http://vk.com/share.php?url=https://github.com/asmyshlyaev177/state-in-url)