Scripts estándar de collections en Payload para desarrollar más rápido
Los scripts de seed y clear parecen tareas de limpieza. En la práctica están más cerca de ser infraestructura, porque entre los dos deciden cuánto tardas en pasar de una base vacía a una pantalla contra la que puedas diseñar de verdad.
{
"scripts": {
"seed:blog": "tsx src/scripts/Blog/seed-blog.ts",
"clear:blog": "tsx src/scripts/Blog/clear-blog.ts",
"seed:portfolio": "tsx src/scripts/Portfolio/seed-portfolio.ts",
"clear:portfolio": "tsx src/scripts/Portfolio/clear-portfolio.ts",
"sync:media": "tsx src/scripts/Media/sync-media.ts"
}
}La mayoría de los proyectos los tratan como algo secundario y lo pagan todas las semanas. Lo que sigue es qué te dan realmente, y cómo escribir los dos que más importan: seed y clear.
Por qué estos scripts valen el tiempo
Tu base local se muere más seguido de lo que esperas, sobre todo mientras el esquema todavía se está moviendo. Cambias el tipo de un campo y el push falla a la mitad. Escribes mal una palabra en el nombre de un archivo y la tabla termina declarada con otro nombre. Son los accidentes normales de construir una colección, y cualquiera de ellos puede dejar la base en un estado desde el que no puedes trabajar. Con un seed, repoblarla es un comando y unos segundos. El valor no está en evitar esas situaciones, está en lo barato que sale recuperarse de ellas.
El segundo argumento es de calidad, y es el que casi nadie ve. La data hecha a mano siempre sale demasiado limpia. Tres registros cuando producción va a tener cuarenta, títulos que casualmente entran en una línea, todas las imágenes presentes, todos los campos opcionales llenos. Una data de ejemplo realista te rompe el layout en los lugares donde siempre se iba a romper: el título que se va a tres líneas, la entrada sin galería, la que tiene las cuatro imágenes del máximo, la etiqueta de categoría que en alemán mide el doble. Diseñar contra esos casos en tu propia máquina es lo que hace que el resultado aguante frente a un cliente.
Cómo debería funcionar el seed
// Se salta todo lo que el CMS hace en el camino de entrada. La fila existe,
// y el panel de administración no la puede abrir.
await db.insert(posts).values({ title: 'Hello', category: 'frontend' })
// Toma el mismo camino que toma el panel: corren los hooks beforeChange, se
// genera el slug, se validan los requeridos, se revalida el caché.
await payload.create({
collection: 'posts',
locale: 'en',
overrideAccess: true,
data: { title: 'Hello', category: 'frontend' },
})Empieza por ordenar los archivos. Mantén las entradas fuera del script y fuera de un único json gigante, porque un seed con cuarenta registros incrustados es un script que nadie quiere tocar. Pon el contenido en archivos propios, uno por registro, y que el script lea la carpeta de entradas. La ganancia es que la carpeta se vuelve la fuente de verdad, y editar una entrada no puede romper otra.
Revisa el archivo antes de abrir una conexión. La razón no es el rendimiento, es que un script que falla a la mitad deja la colección en un estado que nadie pidió, sembrada por partes e incómoda de razonar. Tres chequeos cubren cada entrada nueva: que los campos requeridos estén, que cualquier valor de enum exista en el catálogo del campo al que pertenece, y que los arreglos localizados tengan el mismo largo en todos los idiomas.
Si la colección es localizada, y casi siempre lo es, crear un registro es más de una operación. Empieza por el idioma por defecto con todo adentro, y después actualiza ese registro en cada idioma restante solo con los campos localizados. Mandar de nuevo los campos no localizados en la segunda pasada es inofensivo pero engañoso, porque sugiere que varían por idioma cuando el esquema dice que no.
Imprime lo que el script está por hacer antes de que lo haga. Los archivos que encontró en la carpeta, las entradas que va a saltar porque ya existen, y las que está por crear. Un seed que reporta su propio plan es un seed que puedes correr sin abrir después el panel para verificar si funcionó.
Cómo debería funcionar el clear
Ahora la otra mitad. Un script de clear no hace nada la primera vez que lo corres: se conecta, cuenta lo que eliminaría, imprime la lista de registros que están por irse, y termina. Borrar algo exige pasar una bandera explícita, y la que usamos es --yes.
Esa primera ejecución es la línea que de verdad evita el accidente, por la pregunta que responde. ¿A qué base de datos está por tocar el script? Una cadena de conexión vive en una variable de entorno, así que el script sabe exactamente a dónde apunta y tú no. Imprime el host, el puerto y el nombre de la base, nunca las credenciales. Tres palabras de salida convierten una suposición invisible en algo que lees antes de confirmar.
En la segunda ejecución, --yes borra. Ese es todo el mecanismo, y es lo bastante simple como para agregarlo a cualquier script en diez minutos. También es lo que te ahorra la tarde que tomaría volver a crear un conjunto de registros que costó horas producir la primera vez.
Otros casos donde un script te da tranquilidad
Seed y clear cubren cualquier colección cuyo contenido vive por completo en la base de datos. Algunos casos no tienen esa forma, y esos necesitan un verbo propio.
El primero es sync:media. Una colección de uploads de Payload guarda metadata, un nombre de archivo, dimensiones, un tipo mime, mientras los bytes reales viven en un bucket de S3 o R2. Las dos partes se desincronizan con mucha facilidad en una dirección: la base pierde todos los registros de media y el bucket sigue teniendo todos los archivos, intactos. Volver a sembrar no ayuda, porque los archivos no están en el repositorio. Lo que ayuda es un script que recorre el bucket y vuelve a crear un registro por cada objeto que se quedó sin uno.
El segundo es un par de scripts de punto de control, generate-backup y restore-backup. Una base que puedes respaldar en tres o cuatro segundos es una base sobre la que puedes trabajar con libertad, y poder dejar de preocuparte por ella es justo lo que necesitas para avanzar más rápido en la parte que importa.
Uno escribe un respaldo local nuevo, el otro lo restaura y te devuelve a ese punto de control. Tener puntos de control en la base es lo que te permite probar un cambio de esquema, verlo fallar, y estar de vuelta donde empezaste un minuto después en lugar de una hora después.
La seguridad no es el fin en sí misma, lo es la reversibilidad, porque la reversibilidad es lo que te permite dejar de pensar en el comando y volver a pensar en el trabajo. Un script que te da miedo correr es un script que postergas, rodeas, y terminas corriendo apurado contra lo que no era.