From 29a6bafdff9364419ac061f8d9a02b30554d5031 Mon Sep 17 00:00:00 2001 From: Marcos Corrochano Arroyo Date: Sat, 11 Jul 2026 21:08:48 +0200 Subject: [PATCH 1/9] update astro-zod.mdx --- .../docs/es/reference/modules/astro-zod.mdx | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 src/content/docs/es/reference/modules/astro-zod.mdx diff --git a/src/content/docs/es/reference/modules/astro-zod.mdx b/src/content/docs/es/reference/modules/astro-zod.mdx new file mode 100644 index 0000000000000..768769a8e7529 --- /dev/null +++ b/src/content/docs/es/reference/modules/astro-zod.mdx @@ -0,0 +1,119 @@ +--- +title: Referencia de la API de Zod +sidebar: + label: 'astro/zod' +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- + +import ReadMore from '~/components/ReadMore.astro'; + +[Zod](https://github.com/colinhacks/zod) es una librería de declaración y validación de esquemas basada en TypeScript. Te permite definir esquemas que puedes utilizar para validar y transformar datos, desde tipos sencillos (p. ej, `string`, `number`) hasta estructuras de datos complejas (p. ej, objetos anidados). + +El módulo `astro/zod` expone una reexportación de Zod que te permite acceder a todas las funciones de Zod v4. Al utilizar este módulo, no es necesario que instales Zod por tu cuenta. Esto también garantiza que tu proyecto utilice las mismas versiones de la API que usa Astro al usar funciones como [Colecciones de contenido](/es/guides/content-collections/) o [Acciones](/es/guides/actions/). + +Consulta la [página web de Zod](https://zod.dev/) para obtener documentación completa sobre cómo funciona Zod y qué funciones están disponibles. + +## Importa desde `astro/zod` + +```ts +import { z } from 'astro/zod'; +``` + +### `z` + +

+ +**Tipo:** `object` +

+ +La utilidad `z` te permite acceder a validadores para una amplia variedad de tipos de datos, métodos y tipos para trabajar con tus datos. + +Aprende más sobre la utilidad `z` en la [documentación de Zod](https://zod.dev/basics) + +#### Validadores comunes de tipos de datos + +Con Zod, puedes validar cualquier tipo de dato, como [tipos primitivos](https://zod.dev/api#primitives), [objetos](https://zod.dev/api#objects), [listas](https://zod.dev/api#arrays) y mucho más. + +El siguiente ejemplo muestra una hoja de referencia con muchos tipos de datos habituales de Zod para crear un esquema `user`: + +```ts +import { z } from 'astro/zod'; + +const user = z.object({ + username: z.string(), + name: z.string().min(2), + email: z.email(), + role: z.enum(['admin', 'editor']), + language: z.enum(['en', 'fr', 'es']).default('en'), + hobbies: z.array(z.string()), + age: z.number(), + isEmailConfirmed: z.boolean(), + inscriptionDate: z.date(), + website: z.url().optional(), +}); +``` + +#### Extrayendo un tipo de TypeScript + +Zod te permite crear un tipo de TypeScript a partir de cualquier esquema [utilizando la inferencia de tipos de Zod](https://zod.dev/basics#inferring-types). Esto puede resultar útil para describir la estructura de datos esperada al [definir las propiedades de los componentes](/es/guides/typescript/#atributos-de-los-componentes). + +El siguiente ejemplo crea un tipo `User` basado en el esquema anterior: + +```ts +type User = z.infer; + +/* El tipo `User` será: + * type User = { + * username: string; + * name: string; + * email: string; + * role: 'admin' | 'editor'; + * language: 'en' | 'fr' | 'es'; + * hobbies: string[]; + * age: number; + * isEmailConfirmed: boolean; + * inscriptionDate: Date; + * website?: string | undefined; + * } + */ +``` + +#### Uso de los métodos de Zod + +Zod ofrece diversos métodos de esquema para [personalizar los mensajes de error](https://zod.dev/error-customization), [transformar datos](https://zod.dev/api#transforms) o crear [lógicas de validación personalizadas](https://zod.dev/api#refinements). + +```ts +// Personalizar el mensaje de error +const nonEmptyStrings = z.array(z.string()).nonempty('¡No puede estár vacío!'); + +// Validar un dato de un esquema +nonEmptyStrings.parse([]); // lanzará nuestro error personalizado + +// Crear un objeto a partir de una URL para una imagen decorativa +const decorativeImg = z.string().transform((value) => { + return { src: value, alt: '' }; +}); + +// Crear un validador personalizado y un mensaje de error para una cadena de texto +const constrainedString = z + .string() + .refine((val) => val.length > 0 && val.length <= 255, { + error: 'Debe tener entre 1 y 255 caracteres.', + }); +``` + +### Importaciones individuales + +Alternativamente, puedes importar todos los validadores, métodos y tipos de Zod disponibles en la [utilidad `z`](#z) directamente desde el módulo. + +En el siguiente ejemplo se importa `coerce` para crear un objeto `Date` a partir de una cadena de fecha: + +```ts +import { coerce } from 'astro/zod'; + +const publishedOn = coerce.date(); +const publicationDate = publishedOn.parse('2025-12-03'); +``` \ No newline at end of file From 08635a5437e4f5d2153f4cccb429c74fbc2cea2d Mon Sep 17 00:00:00 2001 From: Marcos Corrochano Arroyo Date: Sat, 11 Jul 2026 22:20:21 +0200 Subject: [PATCH 2/9] create typescript.mdx --- src/content/docs/es/guides/typescript.mdx | 381 ++++++++++++++++++ .../docs/es/reference/modules/astro-zod.mdx | 2 +- 2 files changed, 382 insertions(+), 1 deletion(-) create mode 100644 src/content/docs/es/guides/typescript.mdx diff --git a/src/content/docs/es/guides/typescript.mdx b/src/content/docs/es/guides/typescript.mdx new file mode 100644 index 0000000000000..e825be947a9de --- /dev/null +++ b/src/content/docs/es/guides/typescript.mdx @@ -0,0 +1,381 @@ +--- +title: TypeScript +description: Aprende cómo usar la compatibilidad integrada de Astro con TypeScript. +i18nReady: true +--- + +import Since from '~/components/Since.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' + +Astro incluye compatibilidad integrada con [TypeScript](https://www.typescriptlang.org/). Puedes importar archivos `.ts` y `.tsx` en tu proyecto de Astro, escribir código en TypeScript directamente dentro de tu [componente de Astro](/es/basics/astro-components/#script-de-un-componente) e incluso utilizar un archivo [`astro.config.ts`](/es/guides/configuring-astro/#el-archivo-de-configuración-de-astro) para la configuración de Astro si lo prefieres. + +Al usar TypeScript, puedes evitar errores en tiempo de ejecución definiendo los tipos de los objetos y componentes en tu código. Por ejemplo, si utilizas TypeScript para [especificar los tipos de las propiedades de tu componente](#propiedades-de-componente), aparecerá un error en tu editor si asignas un prop que tu componente no admite. + +No necesitas escribir código en TypeScript en tus proyectos de Astro para beneficiarte de sus ventajas. Astro siempre trata el código de tus componentes como si fuera TypeScript, y la [extensión de Astro para VS Code](/es/editor-setup/) deducirá todo lo que pueda para ofrecerte autocompletado, sugerencias y avisos de errores en tu editor. + +El servidor de desarrollo de Astro no realiza ningún tipo de comprobación de tipos, pero puedes utilizar un [script independiente](#verificación-de-tipos) para detectar errores de tipos desde la línea de comandos. + +## Configuración + +Los proyectos iniciales de Astro incluyen un archivo `tsconfig.json` en tu proyecto. Aunque no escribas código en TypeScript, este archivo es importante para que herramientas como Astro y VS Code sepan cómo interpretar tu proyecto. Algunas funciones (como la importación de paquetes de npm) no son totalmente compatibles con el editor si no se dispone de un archivo `tsconfig.json`. Si instalas Astro manualmente, asegúrate de crear este archivo tú mismo. + +### Plantillas de TSConfig + +Astro incluye tres plantillas extensibles de `tsconfig.json`: `base`, `strict` y `strictest`. La plantilla `base` permite el uso de las características modernas de JavaScript y también se utiliza como base para las demás plantillas. Recomendamos utilizar `strict` o `strictest` si tienes pensado escribir en TypeScript en tu proyecto. Puedes consultar y comparar las configuraciones de las tres plantillas en [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/). + +Para heredar de una de las plantillas, utiliza [la opción `extends`](https://www.typescriptlang.org/tsconfig#extends): + +```json title="tsconfig.json" +{ + "extends": "astro/tsconfigs/base" +} +``` + +Además, recomendamos configurar `include` y `exclude` de la siguiente manera para aprovechar los tipos de Astro y evitar la revisión de los archivos compilados: + +```json title="tsconfig.json" ins={3-4} +{ + "extends": "astro/tsconfigs/base", + "include": [".astro/types.d.ts", "**/*"], + "exclude": ["dist"] +} +``` + +### Plugin de TypeScript para editores + +El [plugin de Astro para TypeScript](https://www.npmjs.com/package/@astrojs/ts-plugin) se puede instalar por separado si no utilizas la [extensión oficial de Astro para VS Code](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). La extensión de VS Code instala y configura automáticamente este plugin, por lo que no es necesario instalar ambos. + +Este plugin solo funciona en el editor. Al ejecutar `tsc` en la terminal, los archivos `.astro` se ignoran por completo. En su lugar, puedes utilizar [el comando de la CLI `astro check`](/es/reference/cli-reference/#astro-check) para comprobar tanto los archivos `.astro` como los `.ts`. + +Este plugin también soporta la importación de archivos `.astro` a partir de archivos `.ts` (lo cual puede resultar útil para volver a exportarlos). + + + + ```shell + npm install @astrojs/ts-plugin + ``` + + + ```shell + pnpm add @astrojs/ts-plugin + ``` + + + ```shell + yarn add @astrojs/ts-plugin + ``` + + + +A continuación, añade lo siguiente a tu archivo `tsconfig.json`: + +```json title="tsconfig.json" +{ + "compilerOptions": { + "plugins": [ + { + "name": "@astrojs/ts-plugin" + }, + ], + } +} +``` + +Para comprobar que el plugin funciona, crea un archivo `.ts` e importa un componente de Astro en él. No deberías recibir ningún mensaje de advertencia del editor. + +### Frameworks de UI + +Si tu proyecto utiliza un [framework de UI](/es/guides/framework-components/), es posible que se necesiten ajustes adicionales en función del framework. Consulta la documentación de TypeScript de tu framework para obtener más información. ([Vue](https://vuejs.org/guide/typescript/overview.html#using-vue-with-typescript), [React](https://react-typescript-cheatsheet.netlify.app/docs/basic/setup), [Preact](https://preactjs.com/guide/v10/typescript), [Solid](https://www.solidjs.com/guides/typescript), [Svelte](https://svelte.dev/docs/svelte/typescript)) + +## Importaciones de tipos + +Usa importaciones de tipos explícitas y exportaciones siempre que sea posible. + +```js del={1} ins={2} ins="type" +import { SomeType } from './script'; +import type { SomeType } from './script'; +``` + +De esta forma, evitas casos extremos en los que el empaquetador de Astro podría intentar empaquetar erróneamente los tipos que has importado como si fueran JavaScript. + +Puedes configurar TypeScript para que exija el uso de importaciones de tipos en tu archivo `tsconfig.json`. Configura [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax) en `true`. TypeScript comprobará tus importaciones y te indicará cuándo debes utilizar `import type`. Esta configuración está activada por defecto en todos nuestros ajustes preestablecidos. + +```json title="tsconfig.json" ins={3} +{ + "compilerOptions": { + "verbatimModuleSyntax": true + } +} +``` + +## Alias de importación + +Astro soporta alias de importación que puedes definir en la configuración `paths` de tu archivo `tsconfig.json`. [Consulta nuestra guía de importaciones](/es/guides/imports/#alias) para aprender más. + +```astro title="src/pages/about/nate.astro" "@components" "@layouts" +--- +import HelloWorld from '@components/HelloWorld.astro'; +import Layout from '@layouts/Layout.astro'; +--- +``` + +```json title="tsconfig.json" {4-5} +{ + "compilerOptions": { + "paths": { + "@components/*": ["./src/components/*"], + "@layouts/*": ["./src/layouts/*"] + } + } +} +``` + +## Extender tipos globales + +Puedes crear el archivo `src/env.d.ts` como convención para añadir declaraciones de tipos personalizados, o para aprovechar los tipos de Astro si no dispones de un archivo `tsconfig.json`: + +```ts title="src/env.d.ts" +// Declaraciones de tipos personalizados +declare var myString: string; + +// Tipos de Astro, no son necesarios si ya tienes un archivo `tsconfig.json`. +/// +``` + +### `window` y `globalThis` + +Es posible que quieras añadir una propiedad al objeto global. Para ello, puedes añadir declaraciones de nivel superior utilizando la palabra clave `declare` en tu archivo `env.d.ts`: + +```ts title="src/env.d.ts" +declare var myString: string; +declare function myFunction(): boolean; +``` + +Esto proporcionará un tipo a `globalThis.myString` y `globalThis.myFunction`, así como a `window.myString` y `window.myFunction`. + +Ten en cuenta que `window` solo está disponible en el código del lado del cliente. `globalThis` está disponible tanto en el lado del servidor como en el lado del cliente, pero su valor en el lado del servidor no se compartirá con el cliente. + +Si solo quieres definir una propiedad en el objeto `window`, proporciona una interfaz `Window` en su lugar: + +```ts title="src/env.d.ts" +interface Window { + myFunction(): boolean; +} +``` + +### Agregar atributos no estándar + +Es posible que quieras definir un tipo para atributos personalizados o CSS. Puedes extender las definiciones predeterminadas de JSX para añadir atributos no estándar redeclarando el namespace `astroHTML.JSX` en un archivo `.d.ts`. + +```ts title="src/env.d.ts" +declare namespace astroHTML.JSX { + interface HTMLAttributes { + 'data-count'?: number; + 'data-label'?: string; + } + + // Agrega una propiedad CSS personalizada al objeto de estilo + interface CSSProperties { + '--theme-color'?: 'black' | 'white'; + } +} +``` + +:::note +`astroHTML` se inyecta globalmente en los componentes `.astro`. Para usarlo en archivos de TypeScript, utiliza una [directiva de tres barras](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html): + +```ts +/// + +type MyAttributes = astroHTML.JSX.ImgHTMLAttributes; +``` +::: + +### Uso de importaciones + +Es posible que quieras extender los tipos globales reutilizando tipos declarados en otras partes de tu proyecto o procedentes de una librería externa. Para ello, utiliza [importaciones dinámicas](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import): + +```ts title="src/env.d.ts" +type Product = { + id: string; + name: string; + price: number; +}; + +declare namespace App { + interface Locals { + orders: Map + session: import('./lib/server/session').Session | null; + user: import('mi-lib-externa').User; + } +} +``` + +Un archivo `.d.ts` es una declaración de [módulo ambiental](https://www.typescriptlang.org/docs/handbook/modules/reference.html#ambient-modules). Aunque su sintaxis es similar a la de los módulos ES, estos archivos no permiten importaciones ni exportaciones de nivel superior. Si TypeScript encuentra uno, el archivo se considerará una [ampliación de módulo](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) y esto romperá tus tipos globales. + +## Propiedades de componente + +Astro permite definir las propiedades de tus componentes con TypeScript. Para activarlo, añade una interfaz `Props` de TypeScript al frontmatter de tu componente. Se puede utilizar una instrucción `export`, aunque no es necesario. La [extensión de Astro para VS Code](/es/editor-setup/) buscará automáticamente la interfaz `Props` y te proporcionará la compatibilidad adecuada con TypeScript cuando utilices ese componente dentro de otra plantilla. + +```astro title="src/components/HelloProps.astro" ins={2-5} +--- +interface Props { + name: string; + greeting?: string; +} + +const { greeting = 'Hello', name } = Astro.props; +--- +

{greeting}, {name}!

+``` + +### Patrones habituales de tipos de propiedades + +- Si tu componente no admite propiedades ni contenido en slots, puedes utilizar `type Props = Record`. +- Si tu componente debe recibir elementos hijos en su slot predeterminado, puedes garantizarlo utilizando `type Props = { children: any; };`. + +## Utilidades de tipos + +

+ +Astro incluye algunos tipos de utilidades integrados para patrones comunes de tipos de prop. Están disponibles en el punto `astro/types` . + +### Atributos HTML integrados + +Astro proporciona el tipo `HTMLAttributes` para verificar que el código HTML utiliza atributos válidos. Puedes usar estos tipos para ayudarte a crear las propiedades de los componentes. + +Por ejemplo, si estuvieras creando un componente ``, podrías hacer lo siguiente para reflejar los atributos HTML predeterminados de las etiquetas `` en los tipos de propiedades de tu componente. + +```astro title="src/components/Link.astro" ins="HTMLAttributes" ins="HTMLAttributes<'a'>" +--- +import type { HTMLAttributes } from 'astro/types'; + +// usa un `type` +type Props = HTMLAttributes<'a'>; + +// o extiende con una `interface` +interface Props extends HTMLAttributes<'a'> { + myProp?: boolean; +} + +const { href, ...attrs } = Astro.props; +--- + + + +``` + +### Tipo `ComponentProps` + +

+ +Esta exportación de tipo te permite hacer referencia a los `Props` que acepta otro componente, aunque dicho componente no exporte directamente ese tipo de `Props`. + +El siguiente ejemplo muestra cómo utilizar la utilidad `ComponentProps` de `astro/types` para hacer referencia a los tipos de `Props` de un componente `