Skip to content

Latest commit

 

History

History
106 lines (80 loc) · 4.49 KB

typescript.md

File metadata and controls

106 lines (80 loc) · 4.49 KB

TypeScript

Astro docs: TypeScript

Astro's TypeScript setup is unchanged. What AstroSharp adds is the ambient declarations that let an .astro file import C# without erroring.

What is injected

In astro:config:done the integration calls injectTypes, and Astro writes the result under .astro/integrations/astrosharp/, referenced from .astro/types.d.ts — which the base tsconfig already includes. So astro check and your editor pick it up with no configuration.

Each component gets its own declaration, generated from its C# [Parameter] properties:

// src/components/Card.razor
[Parameter] public string Title { get; set; } = "";
[Parameter] public int Count { get; set; }
[Parameter] public RenderFragment? ChildContent { get; set; }
declare module '*/components/Card.razor' {
  /** src/components/Card.razor */
  const component: (props: {
    "title"?: string;
    "count"?: number;
  }) => any;
  export default component;
}

So props are checked against the C#:

---
import Card from '../components/Card.razor';
---
<Card title="Hello" />        <!-- fine -->
<Card titel="Hello" />        <!-- error: Did you mean 'title'? -->
<Card title={123} />          <!-- error: Type 'number' is not assignable to type 'string' -->

A permissive declare module '*.razor' remains as the fallback, so an import no pattern matched still resolves rather than being "Cannot find module" (ts 2307).

A component with a catch-all is typed open. A [Parameter(CaptureUnmatchedValues = true)] property exists to accept props the parameter list does not name, so its declaration gains an index signature and the catch-all itself is left out:

const component: (props: {
  "label"?: string;
  [key: string]: unknown;
}) => any;

The named props are still checked — a typo in label is still an error — while class, id and data-* are not. See Components.

How it resolves without a tsconfig change

TypeScript's mechanism for this is allowArbitraryExtensions plus a Card.d.razor.ts beside each file — but that flag is not in Astro's base config, so it would only work after you edited a file AstroSharp does not own.

Pattern module declarations need nothing. TypeScript resolves them by longest matching prefix, so a pattern is emitted at every directory boundary — */Card.razor, */components/Card.razor, */src/components/Card.razor — and whichever is most specific to how you wrote the import wins.

Where the real types are

Content collections are fully typed, because Astro generates those types from the collection's schema — and a C# loader can be the source of that schema. getCollection('releases') comes back typed from the C# record. See Content collections.

Actions are typed the same way on the client, from the reflected input schema. See Actions.

Limitations

Every prop is optional. A prop Astro does not pass leaves the C# property at its default, which is not an error at runtime — so marking one required in TypeScript would report a failure that cannot happen. Typos and wrong types are caught; a missing prop is not.

Two components with the same file name lose the shared pattern. components/Card.razor and ui/Card.razor both want */Card.razor, and a pattern matching both would type one of them wrongly, so it is dropped. Each keeps its folder-qualified pattern, and only a sibling import written as ./Card.razor falls back to the permissive type.

Props are camel-cased. [Parameter] public string Title is declared as title. Binding is case-insensitive at runtime, so <Card Title="..." /> still works — TypeScript just will not recognise it.

A component with no [Parameter] properties is not constrained. It declares Record<string, unknown> rather than rejecting every prop, so passing one is not an error.

Types refresh on restart, not on hot reload. Astro writes injected types in astro:config:done, which runs at startup. Adding a [Parameter] in dev takes effect for rendering immediately, but the editor sees it after a restart.

Nothing type-checks slot names. RenderFragment parameters are deliberately left out of the prop type — they are slots, filled from child content rather than from an attribute, and declaring them would invite someone to pass one. Astro does not check slot names for framework components either.