DEV Community: Kus Cámara

Creación de agentes AI con PydanticAI – Introducción

Kus Cámara — Wed, 05 Nov 2025 01:35:33 +0000

En los últimos meses he tenido la suerte de explorar el mundo de los agentes AI, concretamente utilizando la librería PydanticAI. A fecha de la escritura de este post, no hay mucha información técnica en español sobre el tema, y dado que la librería es relativamente “nueva”, he decidido escribir una serie de posts para compartir lo que voy aprendiendo.

DISCLAIMER: No soy una experta, por lo que deberías tomar este post con la misma cautela que una respuesta de ChatGPT 😅

Concepto de Agente AI

Definir qué es exactamente un agente no es tarea sencilla. Si te das una vuelta por LinkedIn, encontrarás fácilmente debates sobre si algo es realmente un agente, un workflow, o si tus agentes son menos agentes que los míos por haber usado herramientas low-code. Fuentes como HuggingFace, nos hablan incluso de niveles de agencia en lugar de establecer una clasificación binaria.

Polémicas aparte, para el propósito de este post, nos quedaremos con la siguiente definición. Un agente es la combinación de los siguientes componentes:

Un LLM (GPT, Claude, Gemini, etc.) -> el cerebro del agente. Responsable de procesar instrucciones en lenguaje natural, tomar decisiones sobre acciones a realizar y utilizar herramientas para interactuar con su entorno.
Un system prompt -> un conjunto de instrucciones que configuran el comportamiento del LLM, definiendo su propósito y especialización, tono, medidas de seguridad (guardrails), etc.
Herramientas (tools) -> funciones que el agente puede utilizar para llevar a cabo tareas específicas, como acceder a bases de datos, realizar búsquedas en la web o interactuar con APIs.

Probar LLMs sin arruinarse

Sabiendo que lo primero que necesitamos es un LLM y que los más populares no son baratos, nos interesa encontrar formas de experimentar sin dejarnos una pasta.

Existen varias opciones que podemos probar:

GitHub Models: GitHub te permite experimentar de forma gratuita (con limitaciones de uso) con varios modelos LLM alojados en su plataforma. Es una excelente opción para empezar sin necesidad de configurar nada localmente. Solo necesitas una cuenta de GitHub y una API key.
Google AI Studio: Google también permite probar varios modelos de la serie Gemini de forma gratuita (con limitaciones) mediante Google AI Studio. Los modelos Gemini destacan por ofrecer una ventana de contexto enorme y un buen equilibrio entre rendimiento y coste.
Ollama: Si prefieres trabajar completamente offline, Ollama te permite ejecutar modelos LLM de forma local en tu máquina. Eso sí, es importante elegir modelos adecuados para agentes (con capacidad de thinking y uso de tools) y que puedan funcionar con fluidez en tu equipo. En mi caso, usando un MacBook Air M3 con 16GB de RAM, los modelos con mejor rendimiento son qwen2.5:7b-instruct, llama3.1:8b, gemma2:9b y mistral:7b-instruct. Si bien estos modelos están lejos de la calidad de los grandes LLMs comerciales, pueden ser más que suficientes para experimentar y aprender.

PydanticAI soporta estas tres opciones y otras como Anthropic, HuggingFace, OpenAI, etc.

Creando un agente con PydanticAI

Una vez que tenemos un LLM y alguna idea de agente que queremos construir, podemos ponernos manos a la obra con PydanticAI.

En este ejemplo vamos a hacer algo sencillo y poco original: un agente que recomienda un plato de cocina en función de los ingredientes que el usuario le proporcione. Se llamará DelicIA.

Configuración del proyecto Python e instalación de dependencias

He usado uv como gestor de dependencias y entornos virtuales, pero puedes usar el que prefieras y adaptar los comandos según corresponda.

Crear un proyecto nuevo:

uv init delicia-agent

Instalación de dependencias:

uv add pydantic_ai

Creación del entorno virtual y activación:

uv venv .venv
source .venv/bin/activate  # Linux/Mac

Configuración del agente

El archivo main.py se genera automáticamente al crear el proyecto con uv.

Como LLM he optado por usar GitHub Models con gpt-4o.

# main.py

import asyncio
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.github import GitHubProvider

# Configuración del modelo LLM usando GitHub Models
model = OpenAIChatModel(
    "openai/gpt-4o",
    provider=GitHubProvider(api_key="github_pat_XXXXXXXXXXXXXXXXXXXXXX")  
)

# Definición del agente
delicia = Agent(
    name="DelicIA",
    model=model,
    # System prompt
    instructions=(
        "You are DelicIA, an AI specialized in providing delicious and healthy recipes. "
        "Your goal is to help users find recipes that can be made with the ingredients they provide. "
        "Provide a concise response with the recipe name and the preparation steps."
    )
)

async def main():
    await delicia.to_cli(prog_name="🥘 DelicIA")

if __name__ == "__main__":
    asyncio.run(main())

Estamos usando el método to_cli() de PydanticAI para interactuar con el agente desde la línea de comandos. Al ejecutar el script, se nos presentará un prompt para introducir los ingredientes, y el agente nos responderá con una recomendación de plato siguiendo las instrucciones definidas en el system prompt.

Ejecución del agente

uv run python main.py

Demo de ejecución

Acceso a herramientas (tools)

Hasta ahora hemos podido materializar en el código dos de los componentes clave de un agente: el LLM y el system prompt con instrucciones básicas. Podríamos extender el system prompt mucho más con instrucciones para evitar respuestas no deseadas, ejemplos del formato de las respuestas a modo de few-shot learning, etc. Sin embargo, para que un agente sea realmente útil, y agente, necesita poder interactuar con su entorno a través de herramientas (tools).

Hay varias formas de definir herramientas en PydanticAI. En nuestro caso vamos a usar una function tool que simulará una consulta a una base de datos de recetas. Por simplicidad, usaremos un diccionario con un mapeo de ingredientes a recetas.

Para declarar una función como tool podemos usar el decorador @tool, si necesitamos acceso al contexto del agente, o @tool_plain si no necesitamos acceso al contexto. En nuestro caso, usaremos @tool_plain:

@delicia.tool_plain
def get_recipe(ingredient: str) -> str:
    """
    Returns a dish recipe based on the provided ingredient.
    Args:
        ingredient (str): The main ingredient for the recipe.
    Returns:
        str: A recipe suggestion or a message indicating no pre-established recipe is available.
    """
    recipes_dict = {
        "patatas": "Tortilla de patatas",
        "tomate": "Gazpacho andaluz",
        "pollo": "Pollo al ajillo",
        "arroz": "Paella valenciana",
        "huevos": "Huevos revueltos con jamón",
        "pescado": "Pescado a la plancha con limón",
        "pasta": "Espaguetis carbonara",
    }

    ingredient_lower = ingredient.lower().strip()

    if ingredient_lower in recipes_dict:
        return recipes_dict[ingredient_lower]
    else:
        return "croquetas"

¿Cómo sabe el agente qué hace esta herramienta y qué parámetros necesita?

Mediante la documentación de la función y los argumentos proporcionados en el docstring. PydanticAI utiliza esta información para generar un schema que describe la herramienta y sus parámetros. El LLM es el que se encarga de razonar sobre lo que debe hacer y las herramientas que tiene a su disposición para llevar a cabo las tareas solicitadas por el usuario.

Dependiendo del modelo que uses, puede que necesites ser más explícito en el system prompt e indicar que debe usar las herramientas disponibles. Incluso puede ser necesario incluir ejemplos de uso para guiar al modelo sobre cómo invocarlas correctamente y con qué parámetros. En nuestro caso con GPT-4o no ha sido necesario.

Demo de ejecución con tool

Esta parte puede resultar un poco confusa. Nuestra tool con una consulta ficticia a una base de datos devuelve solamente el nombre del plato. Sin embargo, la respuesta que estamos obteniendo del agente es mucho más completa, incluyendo los pasos de preparación. Lo que ocurre aquí es que el LLM incorpora la información devuelta por la tool en su razonamiento y genera una respuesta más elaborada con el objetivo de cumplir la instrucción dada en el system prompt, que es proporcionar una receta completa.

Otros usos de las tools

Las tools no se limitan a obtener datos de fuentes externas. También son ideales para realizar cálculos, formatear datos o cualquier tarea que requiera la ejecución de código.

Por ejemplo, si necesitamos la fecha actual, es mucho más eficiente y fiable usar una tool que llame a datetime.now() que delegarlo al LLM. El LLM, muy probablemente, nos devolverá una fecha inventada en el pasado (los LLMs no tienen acceso a información en tiempo real) y además estaríamos consumiendo tokens innecesariamente. En general, cualquier operación determinista que pueda resolverse con código es una buena candidata para ser implementada como tool.

Salida estructurada

Ya podemos decir que tenemos un agente, sin embargo, me gustaría mostrar una característica más de PydanticAI: la capacidad de definir un formato específico para la salida del agente. Esto puede ser útil cuando queremos que la salida del agente pueda ser consumida programáticamente por otras herramientas.

Para ello, vamos a necesitar Pydantic para definir un modelo que represente la estructura de la salida que queremos.

Instalamos la dependencia:

uv add pydantic

En nuestro caso, definiremos un modelo RecipeOutput con los campos name y preparation_steps. Podríamos añadir campos como cooking_time, difficulty, ingredients, etc..

from pydantic import BaseModel

class RecipeOutput(BaseModel):
    name: str
    preparation_steps: list[str]

Luego, al definir el agente, podemos usar el parámetro output_type para especificar que queremos que la salida del agente siga la estructura definida en RecipeOutput.

delicia = Agent(
    name="DelicIA",
    model=model,
    instructions=(
        "You are DelicIA, an AI specialized in providing delicious and healthy recipes. "
        "Your goal is to help users find recipes that can be made with the ingredients they provide. "
        "Provide a concise response with the recipe name and the preparation steps."
    ),
    output_type=RecipeOutput  # Especificamos el tipo de salida
)

Al ejecutar el agente, la respuesta será una instancia de RecipeOutput, que podemos serializar fácilmente a JSON o manipular directamente como un objeto Python.

Conclusión y próximos pasos

Hemos visto cómo crear un agente AI básico utilizando PydanticAI, incluyendo la configuración del LLM, el system prompt, la definición de herramientas (tools) y la estructuración de la salida utilizando Pydantic.

En próximos posts veremos temas como:

Uso de MCPs
Instrumentación mediante Pydantic Logfire
Estrategias de reintentos para gestionar rate limits
Optimización de mensajes para ajustarse a las ventanas de contexto de los LLMs

Si te interesan estos temas y estás empezando, no puedo dejar de recomendar los cursos gratuitos de HuggingFace.

Hasta la próxima! 👋

Píldoras TypeScript: type narrowing con "as const"

Kus Cámara — Sat, 03 Aug 2024 21:07:45 +0000

En muchas ocasiones te habrás encontrado con un error de tipo "string no es asignable a... Whatever" al asignar a una variable un valor compatible con el tipo esperado. Esto ocurre cuando TypeScript infiere un tipo más amplio que el que se espera para una variable, como por ejemplo, cuando asignamos un string a una variable que debería ser de tipo literal.

Para entenderlo mejor, vamos a verlo con un ejemplo.

Tenemos un tipo Severity definido como un string unión de los valores: "low", "medium" y "high".

type Severity = "low" | "medium" | "high"

Podríamos decir que Severity es un subtipo de string que, de todos los strings posibles, solo admite esos tres.

Por otra parte tenemos un objeto messages en el que las claves son un Severity y los valores son strings.

const messages: Record<Severity, string> = {
  low: "😕 not good",
  medium: "😖 ugly",
  high: "😱 AAAAHHH!!!",
}

Queremos acceder a los valores de messages y para ello definimos una variable severity con el valor "low".

let severity = "low"

console.log(messages[severity])
//          ^? Error: Element implicitly has an 'any' type because
// expression of type 'string' can't be used to index type 
// 'Record<Severity, string>'.

Aunque el valor que hemos asignado a la variable severity es compatible con el tipo Severity, TypeScript nos muestra un error que viene a decirnos que las claves de messages deben ser de tipo Severity y no de tipo string.

Para entender por qué ocurre esto, necesitamos entender cómo TypeScript infiere los tipos de las variables a las que no asignamos un tipo explícitamente.

Si hacemos hover en nuestro editor o en el Playground de TypeScript sobre severity veremos que TypeScript lo infiere como string.

Esto es así porque hemos declarado severity usando let y por lo tanto podemos reasignarle un valor que no sea compatible con Severity en cualquier momento.

En estos casos, TypeScript aplica lo que se conoce como "widening" y asigna a la variable el tipo más amplio que sea compatible con el valor que le hemos asignado inicialmente.

Ojo, digo "inicialmente" porque TypeScript espera que cambiemos el valor de una variable en runtime, pero no su tipo (de string a number, etc.). Si esta es nuestra intención, debemos especificarlo explícitamente.

No ocurre lo mismo si declaramos la variable con const.

const severity = "low"

console.log(messages[severity]) // OK

Puesto que el uso de const no permite la reasignación de la variable, TypeScript infiere el tipo como el tipo literal "low" y el error desaparece.

Por lo tanto, como regla general (con alguna excepción), TypeScript infiere el tipo más amplio para las variables de tipo primitivo declaradas con let y el tipo literal para las variables declaradas con const.

Esto en cuanto a las variables de tipo primitivo, pero ¿qué ocurre con los objetos?

Vamos a verlo con otro ejemplo.

Tenemos una interfaz Issue con estas propiedades:

interface Issue {
  id: string
  severity: Severity
}

Y una función printIssue que recibe un objeto de tipo Issue y hace algo con él, que nos da igual.

declare function printIssue(issue: Issue): void

Si pasamos a printIssue un objeto con una estructura compatible con Issue, TypeScript nos mostrará un error indicando que los tipos de severity no son compatibles.

const issue = {
  id: '123',
  severity: 'low',
}

printIssue(issue)
//         ^? Error: Argument of type '{ id: string; severity:
// string; }' is not assignable to parameter of type 'Issue'. 
// Types of property 'severity' are incompatible.

En el caso de los objetos, independientemente de que los declaremos con let o const, TypeScript infiere el tipo de sus propiedades como si hubieran sido declaradas con let.

Aunque no podamos asignar un nuevo valor a una variable de tipo objeto declarada con const, sí que podemos modificar sus propiedades.

issue.severity = 'other'

Si llevamos un tiempo trabajando con TypeScript, sabremos que podemos solucionar este problema de varias formas, y una de ellas es usando as const sobre la propiedad incompatible.

const issue = {
  id: '123',
  severity: 'low' as const,
}

Con el uso de as const le estamos indicando a TypeScript que infiera el tipo más pequeño posible (narrowing) para la propiedad severity en lugar del tipo más amplio string. En este caso, se infiere el tipo literal "low".

Otra forma de solucionar este problema, a efectos didácticos, es usar Object.freeze sobre el objeto.

const issue = Object.freeze({
  id: '123',
  severity: 'low',
})

Dado que Object.freeze devuelve un objeto de solo lectura, TypeScript infiere el tipo literal para sus propiedades.

Object.freeze tiene una característica que puede ser un inconveniente en algunos casos, y es que la inmutabilidad que proporciona es "shallow", es decir, solo afecta a las propiedades del objeto, pero no a sus propiedades anidadas, que pueden seguir siendo modificadas.

Si nos interesa marcar un objeto como readonly en profundidad, podemos aplicar as const a todo el objeto.

const issue = {
  id: '123',
  severity: 'low',
  another: {
    prop: 'value'
  }
} as const

Y esto es todo en cuanto a inferencia de tipos y as const como técnica de "narrowing", pero tenemos otras formas de evitar que TypeScript infiera tipos más amplios de los que esperamos, como por ejemplo, especificando el tipo de las variables explícitamente, usando satisfies o aprovechando el "excess property checking", pero eso lo dejamos para otra píldora.

Si has llegado hasta aquí, ¡gracias! Y si además te ha resultado útil o simplemente te ha gustado, ayúdame a llegar a más gente compartiéndolo 😊

Testing de componentes React: ¿cuándo y por qué necesitamos usar act()?

Kus Cámara — Sat, 21 Oct 2023 11:43:44 +0000

¿A quién no le ha pasado? Cuando hacemos test de componentes React, de vez en cuando nos encontramos con este warning:

Warning: An update to MyComponent inside a test was not wrapped in act(...).

When testing, code that causes React state updates should be wrapped into act(...):

act(() => {
  /* fire events that update state */
});
/* assert on the output */

Aunque el mensaje es bastante claro (una vez que lo entendemos), es habitual no entender ni por qué aparece, ni cómo solucionarlo, dando como resultado que acabemos ignorándolo.

Actualizaciones de estado y rerenders

Cuando hacemos una actualización de estado en un componente, React se encarga de volver a renderizarlo para actualizar el DOM si es necesario. Esto ocurre automáticamente como respuesta a los eventos de usuario (clicks, input, etc.) gestionados por React. Ahora bien, los tests son otra historia.

Para demostrarlo, vamos a suponer que tenemos un componente muy sencillo que muestra un botón y un texto que cambia al hacer click sobre ese botón.

function MyComponent({ initialText }) {
  const [text, setText] = useState(initialText)

  return (
    <div>
      <button onClick={() => setText('New text')}>Click me</button>
      <p>{text}</p>
    </div>
  )
}

Cuando interactuamos con este componente en el navegador, React se encarga de volver a renderizarlo (volver a ejecutar render) cuando necesita actualizar su estado, dando como resultado en este caso una actualización del DOM.

Por el contrario, cuando renderizamos este componente en un test, React no espera que ocurran actualizaciones de estado entre lo que renderizamos inicialmente y las aserciones que hacemos sobre el DOM.

Para entenderlo mejor, digamos que el trabajo de React en un test termina después de ejecutar el render. Y para terminar de endender el nombre de esa función act(), vamos a suponer que de las tres A (Arrange, Act y Assert) React solo espera que en un test ocurran la primera y la última:

test('shows the text specified in "initialText"', () => {
  // arrange
  render(<MyComponent initialText="any" />)

  // assert
  expect(screen.getByText('any')).toBeInTheDocument()
})

Normalmente en un test vamos a necesitar simular ciertos eventos para comprobar que el resultado de una interacción es el esperado. En este caso queremos comprobar que al hacer click sobre el botón, el texto cambia a "New text".

Los métodos que Testing Library nos proporciona para simular las interacciones de usuario (fireEvent y userEvent) utilizan internamente act() y por eso no necesitamos usarlo en la mayoría de los casos. Esto es, en mi opinión, lo que contribuye a que no tengamos claro por qué a veces aparece ese warning, ya que no siempre es evidente que ya lo estamos usando.

Para demostrar esto, en lugar de fireEvent o userEvent vamos a usar el método click() nativo del botón:

test('changes initial text after clicking the button', () => {
  // arrange
  render(<MyComponent initialText="any" />)

  // 👉 esto provoca un warning de act()
  screen.getByRole('button').click() 

  // assert
  expect(screen.getByText('New text')).toBeInTheDocument()
})

El resultado de ejecutar este test será un warning de act() y un test fallido. Lo que React nos está diciendo con ese warning viene a ser algo así:

¡Ey! Estás haciendo algo que actualiza el estado. Necesito que me avises para que pueda volver a renderizar el componente. De lo contrario no te puedo garantizar que estés probando lo que esperas.

Y como hemos podido ver en este ejemplo, nos avisa por una buena razón: el DOM que estamos probando no está actualizado.

Avisando a React de que necesita volver a renderizar

Ahora que ya hemos entendido por qué aparece el warning, vamos a ver cómo solucionarlo.

Siempre que hagamos algo en un test que provoque un cambio de estado, tenemos que envolverlo en act():

test('changes initial text after clicking the button', () => {
  // arrange
  render(<MyComponent initialText="any" />)

  // act (Soy un comentario innecesario pero didáctico 😅)
  act(() => screen.getByRole('button').click())

  // assert
  expect(screen.getByText('New text')).toBeInTheDocument()
})

O mucho mejor, utilizar los métodos que Testing Library nos proporciona para simular interacciones de usuario, que ya hacen uso de act() "under the hood":

Ejemplo con fireEvent:

test('changes initial text after clicking the button', () => {
  // arrange
  render(<MyComponent initialText="any" />)

  // fireEvent usa act() internamente
  fireEvent.click(screen.getByRole('button'))

  // assert
  expect(screen.getByText('New text')).toBeInTheDocument()
})

Ejemplo con userEvent (asíncrono):

test('changes initial text after clicking the button', async () => {
  // arrange
  render(<MyComponent initialText="any" />)

  // userEvent usa act() internamente
  await userEvent.click(screen.getByRole('button'))

  // assert
  expect(screen.getByText('New text')).toBeInTheDocument()
})

¿Cuándo es necesario usar act()?

No todas las actualizaciones de estado ocurren inmediatamente después de una interacción de usuario. En ocasiones, el estado se actualiza como respuesta a un evento asíncrono, como por ejemplo un setTimeout.

Para ejemplificarlo, vamos a modificar un poco nuestro componente para que el texto cambie después de 1 segundo:

function MyComponent({ initialText }) {
  const [text, setText] = useState(initialText)
  const handleClick = () => setTimeout(
    () => setText('New text'), 
    1000
  )

  return (
    <div>
      <button onClick={handleClick}>Click me</button>
      <p>{text}</p>
    </div>
  )
}

En este caso, aunque usemos los métodos de Testing Library para simular la interacción de usuario, el test fallará porque el cambio de estado no ocurre inmediatamente como respuesta a un click, sino después de 1 segundo:

test('changes initial text after clicking the button', () => {
  render(<MyComponent initialText="any" />)

  fireEvent.click(screen.getByRole('button'))

  // ❌ FAIL -> necesitamos esperar 1 segundo
  expect(screen.getByText('New text')).toBeInTheDocument()
})

Podemos sentir la tentación de solucionarlo usando las queries asíncronas de Testing Library, pero en ese caso no estaremos evitando que pase 1 preciado segundo en nuestro test:

test('changes initial text after clicking the button', async () => {
  render(<MyComponent initialText="any" />)

  fireEvent.click(screen.getByRole('button'))

  // Las queries de tipo findBy* son asíncronas
  await screen.findByText('New text')
})

La ejecución de este test tarda más de 1 segundo.

Lo normal y recomendable cuando usamos temporizadores en nuestros componentes, es "mockearlos" para evitar que ese tiempo se consuma realmente en nuestros tests. Para ello, Jest o Vi nos proporcionan el método useFakeTimers():

beforeEach(() => {
  vi.useFakeTimers()
})

afterEach(() => {
  vi.clearAllTimers()
})

test('changes initial text after clicking the button', async () => {
  render(<MyComponent initialText="any" />)

  fireEvent.click(screen.getByRole('button'))

  // 👉 avanzamos 1 segundo
  vi.advanceTimersByTime(1000) 

  // No necesitamos usar findBy* porque el cambio de estado ocurre inmediatamente
  expect(screen.getByText('New text')).toBeInTheDocument()
})

Sin embargo, este test fallará con el mismo warning de act() que hemos visto anteriormente. Dado que la actualización de estado no ocurre como respuesta al onClick del botón, sino al callback del setTimeout, necesitamos avisar a React de que tiene que volver a renderizar el componente tras forzar el avance del temporizador.

test('changes initial text after clicking the button', async () => {
  render(<MyComponent initialText="any" />)

  fireEvent.click(screen.getByRole('button'))

  // 👉 avanzamos 1 segundo y avisamos a React de que tiene que volver a renderizar
  act(() => vi.advanceTimersByTime(1000))

  expect(screen.getByText('New text')).toBeInTheDocument()
})

¡Y voilà! Nuestro test no solo pasa, sino que además su ejecución es mucho más rápida gracias a los fake timers.

Conclusión

Siempre que en nuestros tests estemos provocando actualizaciones de estado, necesitamos avisar a React de que tiene que volver a renderizar el componente mediante act() si no estamos usando alguno de los métodos de Testing Library que lo hacen internamente, como fireEvent.

Ignorar este warning puede provocar que nuestros tests no sean fiables (incluso cuando no fallen), ya que el DOM que estamos probando no está actualizado.

Las queries asíncronas de Testing Library (findBy*) también usan act() internamente, pero no siempre son la solución adecuada, especialmente cuando usamos temporizadores en nuestros componentes que consumen tiempo real en nuestros tests.

Creando generadores (scaffolds) con Plop

Kus Cámara — Fri, 29 Apr 2022 15:30:10 +0000

En todo proyecto, más pronto que tarde, necesitamos un generador que nos ayude a mantener la consistencia entre los archivos que vamos creando (componentes, tests, páginas, etc.). Un generador no solo es necesario para esto, sino para evitar trabajos repetitivos a base de copy & paste que normalmente se pueden automatizar.

Yeoman es una de las herramientas más completas que podemos utilizar para crear generadores, pero a veces simplemente no necesitamos tanto o queremos tener nuestros templates dentro del proyecto en el que los vamos a usar para poder editarlos más fácilmente.

Plop es una herramienta que nos permite crear nuestros propios generadores a partir de unos templates Handlebars y un archivo de configuración en el que establecemos las preguntas que haremos al usuario mediante Inquirer. Y ya está. No necesitamos más que templates y preguntas para rellenarlos.

Creando un generador

Vamos a ver cómo podemos crear un generador con Plop fácilmente con el ejemplo de un componente.

Lo primero que vamos a necesitar, obviamente, es instalar Plop como dependencia de desarrollo:

npm i -D plop

Nuestros componentes se encuentran dentro de src/components/ComponentName/ y dentro de cada una de las carpetas de nuestros componentes tenemos un archivo con el nombre del componente, un archivo de test y un index que sirve como entry point.

Estructura del proyecto:

├── package.json
├── src
│   ├── index.ts
│   ├── components
│   │   └── MyComponent
│   │       ├── MyComponent.test.tsx
│   │       ├── MyComponent.tsx
│   │       └── index.ts

Somos libres de crear el archivo de configuración de Plop y sus templates donde nos dé la gana, y de hecho la documentación de Plop nos sugiere que creemos el archivo plopfile.js de configuración en la raíz del proyecto, pero para mantener todo más organizado y localizable, los vamos a crear dentro de una carpeta llamada generators (también podría llamarse templates, scaffolds, etc.).

La estructura de nuestro proyecto quedará así:

├── package.json
├── generators
│   ├── component
│   │   ├── component.hbs
│   │   ├── component.test.hbs
│   │   └── index.hbs
│   └── plopfile.js
├── src
│   ├── index.ts
│   ├── components
│   │   └── MyComponent
│   │       ├── MyComponent.test.tsx
│   │       ├── MyComponent.tsx
│   │       └── index.ts

Los templates

Lo primero que vamos a necesitar son los templates en formato Handlebars. Handlebars nos permite usar mucho más que variables (condicionales, bucles, etc.), pero nuestro generador es tan simple que solo utiliza la variable del nombre del componente y un helper ({{pascalCase}}) que nos proporciona el propio Plop.

{{!-- component.hbs --}}
export interface {{pascalCase name}}Props {
  /** Prop description */
  someProp?: string;
}

/**
 * Edit me!
 */
export const {{pascalCase name}} = ({}: {{pascalCase name}}Props) => {
  return <p>Hi!</p>
};

El resultado de transformar el código anterior sería el siguiente para un componente llamado MyComponent, my-component o myComponent:

// MyComponent.tsx
export interface MyComponentProps {
  /** Prop description */
  someProp?: string;
}

/**
 * Edit me!
 */
export const MyComponent = ({}: MyComponentProps) => {
  return <p>Hi!</p>
};

Las preguntas y acciones

Una vez que tenemos preparados los templates, podemos pasar a configurar las preguntas que haremos para obtener las variables que utilizamos en ellos. Para esto utilizaremos el archivo de configuración de Plop.

En este archivo podemos cargar otros generadores o bien configurar directamente las preguntas y acciones, que es lo que vamos a hacer en nuestro ejemplo, ya que de momento solo tenemos un generador.

Para las preguntas utilizaremos el tipo de Inquirer que nos interese dependiendo de si queremos obtener un input, una opción de entre varias, un yes o no, etc.

En nuestro caso solo necesitamos una pregunta de tipo input para que el usuario escriba el nombre del componente y además no necesitamos preocuparnos de validar el formato porque el helper {{pascalCase}} que utilizamos se ocupa de ello:

// plopfile.js
module.exports = (plop) => {
  plop.setGenerator('component', {
    description: 'Creates a new component',
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'Component name'
      }
    ],
    actions: []
  })
}

Por último necesitamos especificar las acciones que queremos ejecutar una vez que hemos obtenido los parámetros necesarios a partir de las respuestas del usuario.

En nuestro caso solo necesitamos añadir nuevos archivos, para lo que utilizaremos acciones de tipo add especificando el destino mediante path y el archivo utilizado como template mediante templateFile.

// plopfile.js
module.exports = (plop) => {
  plop.setGenerator('component', {
    description: 'Creates a new component',
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'Component name'
      }
    ],
    actions: [
      {
        type: 'add',
        path: '../src/components/{{pascalCase name}}/{{pascalCase name}}.tsx',
        templateFile: 'component/component.hbs'
      },
      {
        type: 'add',
        path: '../src/components/{{pascalCase name}}/{{pascalCase name}}.test.tsx',
        templateFile: 'component/component.test.hbs'
      },
      {
        type: 'add',
        path: '../src/components/{{pascalCase name}}/index.ts',
        templateFile: 'component/index.hbs'
      }
    ]
  })
}

Por último solo nos faltaría añadir un npm-script para facilitar la ejecución de nuestro generador mediante un comando. Como hemos creado el archivo de configuración de Plop en una ubicación distinta a la raíz, necesitamos especificar la ubicación de este archivo como parámetro:

{
  "scripts": {
    "generate": "plop --plopfile ./generators/plopfile.js"
  }
}

De forma bastante sencilla y rápida podemos tener generadores que podemos actualizar fácilmente en cualquier momento según las necesidades que vayan surgiendo. Plop además no se limita a crear archivos, sino que también puede actualizar los existentes, con lo que nos puede servir para mantener nuestra base de código homogénea siempre que hagamos cambios en los templates.

That's all. Happy templating!