TypeScript

Add type safety to build scripts, component props, content collections, and environment variables.

Aero supports TypeScript in <script is:build> blocks, content config files, and shared type modules. The VS Code extension provides IntelliSense and diagnostics automatically. You can type component props, validate content schemas, and run aero check --types in CI.

Ambient types

Aero ships ambient declarations that make Aero, renderComponent, and *.html imports available to TypeScript. Include them in your tsconfig.json:

tsconfig.json

{
	"compilerOptions": {
		"types": ["@aero-js/core/env"]
	}
}

Or use a triple-slash reference:

/// <reference types="@aero-js/core/env" />

For .html build scripts, the VS Code extension injects these declarations automatically. You only need the above for .ts files outside of templates.

Typing component props

Aero.props is typed as Record<string, any> by default. Add type safety with an interface:

client/components/greeting.html

<script is:build>
	interface GreetingProps {
		name: string
		title?: string
	}

	const { name, title = 'Guest' } = Aero.props as GreetingProps
</script>

<h1>Hello, { name }!</h1>

For shared types, define them in a .ts file and import:

client/types/props.ts

export interface HeaderProps {
	title: string
	subtitle?: string
}

client/components/header.html

<script is:build>
	import type { HeaderProps } from 'types/props'
	const { title, subtitle } = Aero.props as HeaderProps
</script>

When you use as TypeName, required vs optional comes from the interface (name vs name?). Without a cast, Aero infers required props from destructuring defaults: no default means required at the call site; a default means optional.

<script is:build>
	const { title, body = 'No body provided.' } = Aero.props
</script>

Here title is required and body is optional for aero check and IDE diagnostics.

Typing content collections

Use a schema validator in content.config.ts to type collection entries:

content.config.ts

import { defineConfig, defineCollection } from '@aero-js/content'
import { z } from 'zod'

export default defineConfig({
	collections: [
		defineCollection({
			name: 'docs',
			directory: 'client/content/docs',
			schema: z.object({
				title: z.string(),
				published: z.number(),
			}),
		}),
	],
})

Typing import.meta.env

Create an env.d.ts to add types for environment variables:

env.d.ts

/// <reference types="@aero-js/core/env" />

interface ImportMetaEnv {
	readonly SITE: string
	readonly VITE_API_URL: string
}

interface ImportMeta {
	readonly env: ImportMetaEnv
}

CI type-checking

Run type checks in CI without an IDE:

pnpm

pnpm exec aero check --types

npm exec aero check --types

yarn exec aero check --types

This runs compile checks, then TypeScript on build scripts and { } interpolation sites. See CLI for flags and exit codes.