Type checking

Scaffolded projects ship a typecheck script that runs svelte-check and then tsc:

bun run typecheck

Both tools, and the Svelte VS Code extension, read .svelte files raw. They see the mochi:* directives that Mochi strips before the Svelte compiler runs, so two small additions keep them quiet.

Ambient types

Reference mochi-framework/ambient from a .d.ts file in your project. Scaffolds do this in src/global.d.ts:

// file: src/global.d.ts
/// <reference types="mochi-framework/ambient" />

It declares Mochi’s asset imports (*.css, *.md, images) and whitelists the directives on every HTML element and on every component, so <UserAvatar mochi:defer userId={1} /> type-checks without the component declaring anything.

Directives on components

Since: 0.10.0 (not released yet): Directives on components are covered by the ambient types since 0.10.0. Earlier versions only covered HTML elements and patched svelte-check instead.

svelte2tsx checks a call site against the component’s own $props() type. Mochi widens that type where svelte2tsx builds it, so the mochi:* keys and their option objects are known on every component. Generic components (<script generics="…">) are the one exception: svelte2tsx types them separately, so intersect MochiDirectives into their props yourself:

<!-- file: src/List.svelte -->
<script lang="ts" generics="T">
  import type { MochiDirectives } from 'mochi-framework';

  let { items }: { items: T[] } & MochiDirectives = $props();
</script>

attribute_illegal_colon

The Svelte compiler warns about the colon in every mochi:* attribute. Filter it in svelte.config.js; svelte-check and the VS Code extension both read that file:

// file: svelte.config.js
export default {
  compilerOptions: {
    experimental: { async: true },
    warningFilter: (warning) => warning.code !== 'attribute_illegal_colon',
  },
};

Scaffolds ship this filter. If yours predates it, adding the line replaces the --compiler-warnings 'attribute_illegal_colon:ignore' flag in the typecheck script.