---
title: Guia para agentes de IA
description: Instrucciones de implementacion de Michi Router para agentes automaticos.
lastUpdated: 2026-04-25
---

# Michi Router: Guia de Implementacion para Agentes de IA

Este documento esta disenado para que un agente de IA pueda integrar **@arielgonzaguer/michi-router** de forma correcta, segura y consistente.

## 1. Objetivo

Implementar enrutado cliente minimalista en React con:

- Rutas estaticas y dinamicas (`:param`, `*`)
- Navegacion programatica
- Rutas protegidas opcionales
- Buenas practicas de seguridad para navegacion interna

## 2. Reglas no negociables

1. `Link` es **solo para rutas internas**.
2. No usar `navigate` para ir a dominios externos.
3. Las redirecciones de `Protected` deben ser rutas internas (ej. `"/login"`).
4. Mantener fallback 404 (`notFound` o `children`).
5. Preferir imports desde `@arielgonzaguer/michi-router/core` cuando no se use `Protected` (bundle mas pequeno).

## 3. Instalacion

```bash
pnpm add @arielgonzaguer/michi-router
```

## 4. Imports recomendados

### Core (recomendado por tamano)

```tsx
import {
  RouterProvider,
  Link,
  useNavigate,
  useLocation,
  useParams
} from '@arielgonzaguer/michi-router/core';
```

### Protected (si aplica auth)

```tsx
import { Protected } from '@arielgonzaguer/michi-router/protected';
```

> Tambien puedes importar todo desde el paquete raiz: `@arielgonzaguer/michi-router`.

## 5. Implementacion base (plantilla)

```tsx
import React from 'react';
import {
  RouterProvider,
  Link,
  useNavigate,
  useLocation,
  useParams
} from '@arielgonzaguer/michi-router/core';
import { Protected } from '@arielgonzaguer/michi-router/protected';

function Home() {
  const navigate = useNavigate();
  return (
    <main>
      <h1>Home</h1>
      <Link to="/users/42">Perfil</Link>
      <button onClick={() => navigate('/search?q=michi#top')}>Buscar</button>
    </main>
  );
}

function UserPage() {
  const { id } = useParams<{ id: string }>();
  return <h1>User {id}</h1>;
}

function SearchPage() {
  const location = useLocation();
  return <pre>{location.fullPath}</pre>;
}

function PrivatePage() {
  return <h1>Area privada</h1>;
}

export default function App() {
  const authState = { user: { id: 'u1' }, isLoading: false };

  return (
    <RouterProvider
      basename="/app"
      routes={[
        { path: '/', component: <Home /> },
        { path: '/users/:id', component: <UserPage /> },
        { path: '/search', component: <SearchPage /> },
        {
          path: '/private',
          component: (
            <Protected
              configObject={{
                states: authState,
                redirectionPath: '/login',
                defaultMessage: 'Cargando autenticacion...'
              }}
            >
              <PrivatePage />
            </Protected>
          )
        },
        { path: '/docs/*', component: <h1>Docs</h1> }
      ]}
      notFound={<h1>404</h1>}
    />
  );
}
```

## 6. API clave para agentes

- `navigate(to, options?)`
  - `to`: ruta interna (`/dashboard`, `/users/1?tab=a#top`)
  - `options.replace?: boolean`
  - `options.state?: unknown`
- `useLocation()` -> `{ pathname, search, hash, fullPath }`
- `useParams<T>()` -> params de ruta dinamica
- `RouterProvider`
  - `routes: Route[]`
  - `basename?: string`
  - `notFound?: ReactNode`
  - `children?: ReactNode` (fallback)

## 7. Patron de Protected

Cuando el usuario no esta autenticado, `Protected` redirige con fallback seguro:

```tsx
<Protected
  configObject={{
    states: { user, isLoading },
    redirectionPath: '/login',
    loadingComponent: <Spinner />
  }}
>
  <Dashboard />
</Protected>
```

## 8. Checklist de aceptacion (para PR de agente IA)

- [ ] No hay uso de URLs externas en `Link`/`navigate`.
- [ ] Existe fallback 404.
- [ ] Rutas dinamicas (`:id`) funcionan correctamente.
- [ ] Si se usa auth, `Protected` redirige a ruta interna.
- [ ] Si no se usa auth, se importa desde `core` para minimizar tamano.
- [ ] La app compila y navega sin recargar pagina.

## 9. Errores comunes a evitar

1. Usar `Link` para `https://...` (incorrecto: es interno).
2. Omitir `basename` cuando la app vive bajo subruta.
3. No definir ruta de fallback (`notFound`/`children`).
4. Redireccion insegura en `Protected` (no usar URLs absolutas externas).

## 10. Errores comunes y como solucionarlos

| Error comun | Sintoma | Solucion |
| --- | --- | --- |
| `Link` usado con URL externa (`https://...`) | No navega o se bloquea por seguridad | Usar `<a href="https://..." target="_blank" rel="noopener noreferrer">` para enlaces externos y reservar `Link` para rutas internas |
| Falta `basename` en apps bajo subruta (`/app`) | 404 o rutas que no coinciden | Configurar `<RouterProvider basename="/app" ... />` |
| No hay `notFound` ni `children` fallback | Pantalla vacia en rutas no registradas | Definir `notFound={<NotFoundPage />}` o pasar `children` como fallback |
| `Protected` redirige a URL absoluta externa | Redireccion reemplazada por `/` | Usar siempre rutas internas en `redirectionPath` (ej. `"/login"`) |
| Ruta dinamica mal definida (`/users/id` en vez de `/users/:id`) | `useParams()` vacio | Declarar `path: '/users/:id'` y consumir `useParams<{ id: string }>()` |
| Uso de imports desde raiz sin necesitar `Protected` | Bundle mayor al necesario | Importar desde `@arielgonzaguer/michi-router/core` para mantener tamano minimo |

### Snippets de correccion rapida

```tsx
// 1) Enlace externo correcto (NO usar Link)
<a href="https://example.com" target="_blank" rel="noopener noreferrer">
  Sitio externo
</a>
```

```tsx
// 2) Basename correcto
<RouterProvider basename="/app" routes={routes} notFound={<h1>404</h1>} />
```

```tsx
// 3) Ruta dinamica correcta
{ path: '/users/:id', component: <UserPage /> }
```

```tsx
// 4) Redireccion segura en Protected
<Protected configObject={{ states: { user, isLoading }, redirectionPath: '/login' }}>
  <Dashboard />
</Protected>
```