typescript

description	Use this guide when working on TypeScript changes in the FAST monorepo — authoring Web Components, writing templates and styles, working with the observable/reactive system, and testing.
name	typescript

TypeScript Patterns for FAST

Modules

fast-element enables verbatimModuleSyntax, so type-only imports must use import type or the inline type qualifier:

import type { Notifier, Subscriber } from "./notifier.js";
import { type Constructable, isFunction } from "../interfaces.js";

Sub-entry-points expose focused APIs through the exports map:

import { twoWay } from "@microsoft/fast-element/two-way.js";
import { reactive } from "@microsoft/fast-element/state.js";

The barrel index.ts explicitly lists every re-export grouped by subsystem — no export * statements.

Aside from the index.ts or index.*.ts files there should be no barrel exports.

Side Effects

Do not add side effectful code and do not add sideEffects to package.json files. APIs added should import named exports.

Browser APIs

Do not use

Our stance as a framework library is that certain browser APIs are best avoided by the framework. We may facilitate the use of them through our provided APIs.

List of APIs to avoid implementing in FAST packages:

• requestIdleCallback
• setTimeout
• setInterval

Avoid

Some browser APIs can be used but should be avoided as a developer may encounter edge cases with task queuing or other logic their app is executing.

List of APIs to avoid in FAST packages:

• requestAnimationFrame
• queueMicrotask

Custom elements

Elements extend FASTElement. Do not use the @customElement decorator.

Use define() for registration. define() returns a Promise that resolves immediately when a template is provided:

Example define.ts (side-effect import):

export class MyElement extends FASTElement {
    @observable items: string[] = [];
}

await MyElement.define({
    name: "my-element",
    template,
    styles,
});

Templates

Templates use the html tagged template literal typed to the element class:

import { html } from "@microsoft/fast-element/html.js";
import { repeat } from "@microsoft/fast-element/repeat.js";
import { when } from "@microsoft/fast-element/when.js";
import type { MyElement } from "./my-element.js";

export const template = html<MyElement>`
    <h1>${x => x.title}</h1>
    ${when(x => x.showList, html<MyElement>`
        <ul>
            ${repeat(
                x => x.items,
                html<string>`<li>${x => x}</li>`
            )}
        </ul>
    `)}
`;

Binding syntax

Prefix	Purpose	Example
${x => ...}	Content or attribute	${x => x.name}
@event	Event listener	@click=${x => x.handleClick()}
@event	Event with context	@click=${(x, c) => c.parent.remove(x)}
:prop	DOM property	:value=${twoWay(x => x.description)}
?attr	Boolean attribute	?disabled=${x => !x.isValid}

Two-way bindings require a sub-entry-point import:

import { twoWay } from "@microsoft/fast-element/two-way.js";

Partial HTML

Use html.partial() to inject pre-built HTML strings into a template without creating a full ViewTemplate:

html<MyElement>`
    <div>${html.partial("<span>static markup</span>")}</div>
`;

Styles

Styles use the css tagged template literal. They attach through the element definition's styles property:

import { css } from "@microsoft/fast-element/css.js";

export const styles = css`
    :host {
        display: block;
        padding: 16px;
    }
`;

For declarative HTML definitions, styles live in a separate .styles.css file linked from both the initial shadow root template and the <f-template>:

<f-template name="my-element">
    <template>
        <link rel="stylesheet" href="./my-element.styles.css">
    </template>
</f-template>

css.partial() works the same way as html.partial() — injecting raw CSS strings.

Reactivity

@attr maps HTML attributes to properties. @observable creates reactive properties tracked by templates. @volatile marks getters whose dependencies change between calls:

import { FASTElement } from "@microsoft/fast-element/fast-element.js";
import { attr, nullableNumberConverter } from "@microsoft/fast-element/attr.js";
import { Observable, observable } from "@microsoft/fast-element/observable.js";
import { volatile } from "@microsoft/fast-element/volatile.js";

class MyElement extends FASTElement {
    @attr label?: string;
    @attr({ mode: "boolean" }) active?: boolean;
    @attr({ converter: nullableNumberConverter }) count?: number;

    @observable private _items: string[] = [];

    // Convention: ${propertyName}Changed
    labelChanged(prev: string | undefined, next: string | undefined) {}

    @volatile
    get sortedItems(): readonly string[] {
        return [...this._items].();
    }
}

Notify the system after in-place mutations that it cannot detect automatically:

this._items.splice(index, 1);
Observable.notify(this, "_items");

Make plain objects observable via the state sub-entry-point:

import { reactive } from "@microsoft/fast-element/state.js";
const todo = reactive({ description: "Buy milk", done: false });

Testing

Tests use Playwright Test (*.pw.spec.ts) and combine two patterns within the same file.

Direct-import tests

For logic that does not need browser APIs — the test callback takes no parameters:

import { expect, test } from "@playwright/test";
import { Observable } from "./observable.js";

test.describe("Observable", () => {
    test("can get a notifier", () => {
        const notifier = Observable.getNotifier(new Model());
        expect(notifier).toBeInstanceOf(PropertyChangeNotifier);
    });
});

Browser-evaluated tests

For tests requiring DOM APIs, navigate to the Vite dev server and import via "/main.js". The @ts-expect-error comment is required because TypeScript cannot resolve the URL-based import:

test("renders element", async ({ page }) => {
    await page.goto("/");

    const result = await page.evaluate(async () => {
        // @ts-expect-error: Client module.
        const { FASTElement, html, uniqueElementName } = await import("/main.js");
        // ... test logic ...
        return someSerializableValue;
    });

    expect(result).toBe(expected);
});

Only serializable values can cross the page.evaluate boundary — run expect() assertions outside it on the returned data.

The test harness at packages/<package>/test/main.ts re-exports source modules for browser tests. When adding new package exports, add them there too.

TypeScript idioms

Const-type merging for enumerations

Frozen const objects paired with a type extracted from their values replace TypeScript enum:

export const SourceLifetime = {
    default: undefined,
    couple: 1,
} as const;

export type SourceLifetime =
    (typeof SourceLifetime)[keyof typeof SourceLifetime];

Interface-const merging

FASTElement is both an interface (instance shape) and a const (constructor). Static methods use typeof to carry overloaded signatures:

export const FASTElement: {
    new (): FASTElement;
    define: typeof define;
} = Object.assign(createFASTElement(HTMLElement), { define });

Tagged template intersection types

html and css are typed as intersections of a tagged template function and a .partial() method:

type HTMLTemplateTag = (<TSource, TParent>(
    strings: TemplateStringsArray,
    ...values: TemplateValue<TSource, TParent>[]
) => ViewTemplate<TSource, TParent>) & {
    partial(html: string): InlineTemplateDirective;
};