TutorialKit

https://github.com/stackblitz/tutorialkit
Admin
TutorialKit is a framework for creating interactive coding tutorials that boost adoption of...
Tokens:39,574
Snippets:359
Trust Score:9.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Start the demo website

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/demo/README.md

Launches the demo website locally. Requires the previous install step to have completed successfully.

```bash
pnpm run demo
```

--------------------------------

### Start TutorialKit development server

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/installation.mdx

Start the development server after installation. The server runs on port 4321 by default; if that port is in use, it will use the next available port, which is shown in the terminal output.

```shell
npm start
```

```shell
pnpm start
```

```shell
yarn start
```

--------------------------------

### Install and Run Dev Server

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/README.md

Commands to install dependencies and start the dev server. The <% pkgManager %> placeholder is replaced by the package manager used to scaffold the project.

```bash
<% pkgManager %> install
<% pkgManager %> run dev
```

--------------------------------

### Install TutorialKit with npm, pnpm, or Yarn

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/installation.mdx

Run the install wizard to create a new TutorialKit project. The command can be run anywhere; the wizard will create an empty directory if needed. Append the enterprise flag with your instance URL (e.g., --enterprise <origin>) for StackBlitz Enterprise Server.

```shell
# create a new project with npm
npm create tutorial
```

```shell
# create a new project with pnpm
pnpm create tutorial
```

```shell
# create a new project with Yarn
yarn create tutorial
```

--------------------------------

### Install @tutorialkit/react and @tutorialkit/theme

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/react-components.mdx

Install the required packages for TutorialKit's React components. Choose the command that matches your package manager (npm, pnpm, or yarn).

```shell
npm install @tutorialkit/react @tutorialkit/theme
```

```shell
pnpm install @tutorialkit/react @tutorialkit/theme
```

```shell
yarn add @tutorialkit/react @tutorialkit/theme
```

--------------------------------

### Run the documentation website

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/README.md

Starts the documentation website locally.

```bash
pnpm run docs
```

--------------------------------

### Filesystem configuration examples

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

Example YAML configurations for the filesystem option, showing how to enable or disable watching and how to specify glob patterns for files to watch.

```yaml
filesystem:
  watch: true  # Filesystem changes to files already in the editor are reflected in the editor

filesystem:
  watch: false # Or if it's omitted, the default value is false

filesystem:
  watch: ['/*.json', '/src/**/*'] # Files changed, added or deleted that match one of the globs are updated in the editor

```

--------------------------------

### Preview configuration example

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

Example YAML configuration for the previews option, showing various ways to specify ports, titles, and pathnames, and how to hide the preview panel.

```yaml
previews:
  - 3000 # Preview is on :3000/
  - "3001/docs" # Preview is on :3001/docs/
  - [3002, "Dev Server"] # Preview is on :3002/. Displayed title is "Dev Server".
  - [3003, "Dev Server", "/docs"] # Preview is on :3003/docs/. Displayed title is "Dev Server".
  - { port: 3004, title: "Dev Server" } # Preview is on :3004/. Displayed title is "Dev Server".
  - { port: 3005, title: "Dev Server", pathname: "/docs" } # Preview is on :3005/docs/. Displayed title is "Dev Server".

previews: false # Do not show preview panel

```

--------------------------------

### Tutorial directory structure example

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/README.md

Shows the file and folder layout for a tutorial in src/content/tutorial, including content.md, _files, _solution, and meta.md files.

```bash
tutorial
├── 1-basics-of-vite
│   ├── 1-introduction
│   │   ├── 1-welcome
│   │   │   ├── content.md    # The content of your lesson
│   │   │   ├── _files        # Initial set of files
│   │   │   │   └── ...
│   │   │   └── _solution     # Solution of the lesson
│   │   │       └── ...
│   │   ├── 2-why-vite
│   │   │   ├── content.md
│   │   │   └── _files
│   │   │       └── ...
│   │   └── meta.md           # Metadata for the chapter
│   └── meta.md               # Metadata for the part
├── 2-advanced
│   ├── ...
│   └── meta.md
└── meta.md                   # Metadata for the tutorial
```

--------------------------------

### meta configuration examples

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

Example values for the `meta` configuration. Relative paths are resolved to the `public` directory, while absolute URLs are used as-is. The first example shows all fields; the second shows a relative path; the third shows an absolute URL.

```yaml
meta:
  image: /cover.png
  title: Title shown on social media and search engines
  description: Description shown on social media and search engines
```

```yaml
meta:
  image: /cover.png # Resolves to public/cover.png
```

```yaml
meta:
  image: 'https://tutorialkit.dev/tutorialkit-opengraph.png' # URL is used as is
```

--------------------------------

### Create viem client and get block number (focused)

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md

TypeScript example using viem to create a public client and fetch the block number, with a focus on the mainnet chain and HTTP transport. Includes a comment emphasizing the action.

```ts
// 1. Import modules
import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';

// 2. Set up your client with desired chain & transport
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
});

// 3. Consume an action!
const blockNumber = await client.getBlockNumber();
```

--------------------------------

### Example hooks: useTheme and useWebcontainer

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/react-components.mdx

Example hooks used by the component examples. useTheme returns the current theme, and useWebcontainer returns a WebContainer instance.

```ts
export function useTheme() {
  return 'light';
}
```

```ts
export function useWebcontainer() {
  return 'light';
}
```

--------------------------------

### Create viem client and get block number (focused lines)

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md

TypeScript example using viem to create a public client and fetch the block number, with focus markers on the action lines.

```ts
// 1. Import modules
import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';

// 2. Set up your client with desired chain & transport
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
});

// 3. Consume an action! // [!code focus]
const blockNumber = await client.getBlockNumber(); // [!code focus]
```

--------------------------------

### Add http import to viem client example

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md

TypeScript example showing a diff-style change: adding the http import to the viem import statement. Includes the full client setup and block number retrieval.

```ts
// 1. Import modules.
import { createPublicClient } from 'viem'; // [!code --]
import { createPublicClient, http } from 'viem'; // [!code ++]
import { mainnet } from 'viem/chains';

// 2. Set up your client with desired chain & transport.
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
});

// 3. Consume an action!
const blockNumber = await client.getBlockNumber();
```

--------------------------------

### Create viem public client and get block number

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md

TypeScript example using viem to create a public client and fetch the current block number. Demonstrates importing modules, setting up the client with mainnet and HTTP transport, and consuming an action.

```ts
// 1. Import modules
import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';

// 2. Set up your client with desired chain & transport
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
});

// 3. Consume an action
const blockNumber = await client.getBlockNumber();
```

--------------------------------

### Install dependencies with pnpm

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/demo/README.md

Installs all project dependencies using pnpm workspaces. Run from the root of the cloned project.

```bash
pnpm install
```

--------------------------------

### Tutorial structure example

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Shows the hierarchical structure of a tutorial with parts, chapters, and lessons, as used in TutorialKit content.

```plaintext
- Part 1: Basics of Vite
  - Chapter 1: Introduction
    - Lesson 1: Welcome!
    - Lesson 2: Why Vite?
    - …
  - Chapter 2: Your first Vite project
- Part 2: Vite CLI
  - …
```

--------------------------------

### Editor configuration examples

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

Example YAML configurations for the editor option, showing how to hide the editor, hide the file tree, and configure allowEdits with booleans or glob patterns.

```yaml
editor: false # Editor is hidden

editor: # Editor is visible
  fileTree: false # File tree is hidden

editor: # Editor is visible
  fileTree: # File tree is visible
    allowEdits: true # User can add new files and folders from the file tree


editor: # Editor is visible
  fileTree: # File tree is visible
    allowEdits: "/src/**" # User can add files and folders anywhere inside "/src/"

editor: # Editor is visible
  fileTree: # File tree is visible
    allowEdits:
      - "/*" # User can add files and folders directly in the root
      - "/first-level/allowed-filename-only.js" # Only "allowed-filename-only.js" inside "/first-level" folder
      - "**/second-level/**" # Anything inside "second-level" folders anywhere

```

--------------------------------

### Lesson content example in Markdown

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/README.md

Example of a lesson content file with Front Matter containing type and title, followed by the lesson body.

```markdown
---
type: lesson
title: Welcome!
---

# Welcome to TutorialKit!

In this tutorial we'll walk you through how to setup your environment to
write your first tutorial 🤩
```

--------------------------------

### Provide feedback when lesson is solved using TutorialKit Core APIs

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/how-to-use-tutorialkit-api.mdx

These three files form the complete example: the LessonChecker component listens for changes to /math.js, runs check-lesson.mjs in the webcontainer, and shows a dialog on success; the check script exits with 0 only if the math functions return expected values; the lesson content imports and mounts the component with client:load.

```tsx
import { Dialog } from '@tutorialkit/react';
import { useEffect, useState } from 'react';
import { webcontainer } from 'tutorialkit:core';
import tutorialStore from 'tutorialkit:store';

export default function LessonChecker() {
  const [success, setSuccess] = useState(false);

  useEffect(() => {
    let timeout: ReturnType<typeof setTimeout> | undefined = undefined;

    const unsubscribe = tutorialStore.onDocumentChanged('/math.js', () => {
      clearTimeout(timeout);

      timeout = setTimeout(async () => {
        if (await checkLesson()) {
          setSuccess(true);
          unsubscribe();
        }
      }, 250);
    });

    return function cleanup() {
      unsubscribe();
      clearTimeout(timeout);
    };
  }, []);

  return (
    <>
      {success && (
        <Dialog title="Lesson complete" confirmText="OK" onClose={() => setSuccess(false)}>
          Lesson complete, congratulations! 🎉
        </Dialog>
      )}
    </>
  );
}

async function checkLesson(): Promise<boolean> {
  const webcontainerInstance = await webcontainer;
  const process = await webcontainerInstance.spawn('node', ['./check-lesson.mjs']);

  const exitCode = await process.exit;

  return exitCode === 0;
}

```

```js
import * as math from './math.js';

if (math.sum(25, 32) !== 57) {
  process.exit(1);
}

if (math.multiply(3, 25) !== 75) {
  process.exit(1);
}

process.exit(0);

```

```mdx
---
type: lesson
title: TutorialKit API usage example
focus: /math.js
---

import LessonChecker from '@components/LessonChecker';

# TutorialKit API usage example

Solve <code>math.js</code> and you'll see notification about completed lesson!

<LessonChecker client:load />

```

--------------------------------

### Install vocs with npm

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md

Terminal command to install the vocs package using npm.

```bash
npm i vocs
```

--------------------------------

### Terminal configuration example

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

Example `terminal` configuration with two panels: an output panel titled 'Dev Server' and an interactive terminal with id 'cmds'. The interactive panel allows output redirection and restricts commands to `ls` and `echo`. `activePanel: 1` makes the second panel active by default.

```yaml
terminal:
  open: true
  activePanel: 1
  panels:
    - ['output', 'Dev Server']
    - type: terminal
      id: 'cmds'
      title: 'Command Line'
      allowRedirects: true
      allowCommands:
        - ls
        - echo

```

--------------------------------

### TypeScript type alias example

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md

TypeScript example showing a type alias and a variable declaration, with a highlight marker on the type line.

```ts
type Example = string; // [!code hl]
const example: Example = 'example';
```

--------------------------------

### Example template directory structure

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Shows a possible layout for shared and custom templates. The shared-template contains common files, while first-template and second-template extend it via .tk-config.json and can override or add files.

```text
src/templates
├── shared-template
│   ├── index.js
│   ├── index.html
│   └── package.json
│
└── first-template
│   │   # Contains { "extends": "../shared-template" }
│   │   # Inherits all files from "shared-template"
│   ├── .tk-config.json
│   │
│   │   # Only available in first-template
│   └── main.js
│
└── second-template
    │   # Contains { "extends": "../shared-template" }
    │   # Inherits all files from "shared-template"
    ├── .tk-config.json
    │
    │   # Overrides "index.js" from "shared-template"
    └── index.js
```

--------------------------------

### Plain text example

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md

A plain text code block used to demonstrate basic code formatting without syntax highlighting.

```plaintext
wowee plain text!
```

--------------------------------

### Create a fieldset for form field pairs

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/demo/src/content/tutorial/1-forms-css/3-fieldset/1-fieldset-element/content.md

Wrap each pair of form fields in a <fieldset> element to group them visually and logically. The example shows the first fieldset containing the first name and last name inputs.

```html
  <fieldset>
    <div>
      <label for="q_1">First name:</label>
      <input id="q_1" />
    </div>
    <div>
      <label for="q_2">Last name:</label>
      <input id="q_2" />
    </div>
  </fieldset>
```

--------------------------------

### Custom TopBar component with Astro slots

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/overriding-components.mdx

Example of a custom `TopBar` component (`src/components/CustomTopBar.astro`) that uses TutorialKit's default components via Astro slots: `logo`, `open-in-stackblitz-link`, `download-button`, `theme-switch`, and `login-button`. The `LanguageSelect` component is used directly.

```jsx
<nav>
  <slot name="logo" />

  <a href="https://tutorialkit.dev/">
    Home page
  </a>

  <slot name="theme-switch" />

  <LanguageSelect />

  <slot name="download-button" />

  <slot name="open-in-stackblitz-link" />

  <slot name="login-button" />
</nav>
```

--------------------------------

### Custom HeadTags component with Astro slots

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/overriding-components.mdx

Example of a custom `HeadTags` component (`src/components/CustomHeadLinks.astro`) that uses TutorialKit's default components via Astro slots: `title`, `links`, and `meta`. You can add your own tags, such as a sitemap link.

```jsx
<slot name="title" />
<slot name="links" />
<slot name="meta" />
{/** Add your own tags */}
<link rel="sitemap" href="/sitemap-index.xml" />
```

--------------------------------

### Set lesson slug in frontmatter

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Example of setting a custom `slug` property in the lesson's frontmatter to change the URL segment. The URL changes from the folder name to the slug value (e.g., `localhost:4321/1-basics/1-introduction/hello-world`).

```markdown
---
title: Welcome!
slug: hello-world
---

```

--------------------------------

### Project Structure

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/README.md

Shows the project structure of a TutorialKit starter, highlighting where tutorial content, templates, and configuration files live.

```bash
.
├── astro.config.mjs    # TutorialKit uses Astro 🚀 (https://astro.build)
├── src
│   ├── ...
│   ├── content
│   │   └── tutorial    # Your tutorial content lives here
│   └── templates       # Your templates (see below for more information)
├── public
│   ├── favicon.svg
│   └── logo.svg        # Default logo used in top left for your tutorial
├── ...
├── theme.ts            # Customize the theme of the tutorial
└── uno.config.ts       # UnoCSS config (https://unocss.dev/)
```

--------------------------------

### Create Tutorial with NPM

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/cli/README.md

Use this command to create a new interactive tutorial project with TutorialKit using NPM. It will scaffold a project named 'my-tutorial'.

```bash
npx tutorialkit@latest create my-tutorial
```

--------------------------------

### Clone and navigate into the TutorialKit repository

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/demo/README.md

Clones the TutorialKit repository from GitHub and changes into the project directory. Requires Git and network access.

```bash
git clone git@github.com:stackblitz/tutorialkit.git
cd tutorialkit
```

--------------------------------

### Create Tutorial with PNPM

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/cli/README.md

Use this command to create a new interactive tutorial project with TutorialKit using PNPM. It will scaffold a project named 'my-tutorial'.

```bash
pnpm dlx tutorialkit@latest create my-tutorial
```

--------------------------------

### tutorialkit:store

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/tutorialkit-api.mdx

The TutorialKit Store is an experimental API accessible via the `tutorialkit:store` entrypoint. It exposes reactive atoms and configuration objects for previews, terminals, editor state, and lesson information, enabling authors to build custom tutorial experiences.

```APIDOC
## tutorialkit:store

### Description
Import the `tutorialkit:store` entrypoint to access the Tutorial Store, which provides low-level APIs for customizing tutorial experiences.

### Import
```ts
import tutorialStore from "tutorialkit:store";
```

### Properties

#### `previews`
- **Type**: `ReadableAtom<PreviewInfo[]>`
- **Description**: Instances of the preview tabs.

#### `terminalConfig`
- **Type**: `ReadableAtom<TerminalConfig>`
- **Description**: Configuration and instances of the terminal.

#### `editorConfig`
- **Type**: `ReadableAtom<EditorConfig>`
- **Description**: Configuration of the editor and file tree.

#### `currentDocument`
- **Type**: `ReadableAtom<EditorDocument | undefined>`
- **Description**: File that's currently open in the editor.

#### `bootStatus`
- **Type**: `ReadableAtom<BootStatus>`
- **Description**: Status of the webcontainer's booting.

#### `documents`
- **Type**: `ReadableAtom<EditorDocuments>`
- **Description**: Files that are available in the editor.

#### `files`
- **Type**: `ReadableAtom<FileDescriptor[]>`
- **Description**: Paths of the files that are available in the lesson.

#### `selectedFile`
- **Type**: `ReadableAtom<string | undefined>`
- **Description**: File that's currently selected in the file tree.

#### `lesson`
- **Type**: `Readonly<Lesson> | undefined`
- **Description**: Currently active lesson.

### Types

#### `PreviewInfo`
```ts
class PreviewInfo {
    readonly portInfo: PortInfo;
    title?: string;
    pathname?: string;
    get url(): string | undefined;
    get port(): number;
    get baseUrl(): string | undefined;
    get ready(): boolean;
    static parse(preview: Exclude<PreviewSchema, boolean>[0]): Preview;
    static equals(a: PreviewInfo, b: PreviewInfo): boolean;
}
```

#### `PortInfo`
```ts
class PortInfo {
    readonly port: number;
    origin?: string | undefined;
    ready: boolean;
}
```

#### `Preview`
```ts
interface Preview {
    port: number;
    pathname?: string;
    title?: string;
}
```

#### `TerminalConfig`
```ts
class TerminalConfig {
    get panels(): TerminalPanel[];
    get activePanel(): number;
    get defaultOpen(): boolean;
}
```

#### `TerminalPanel`
```ts
class TerminalPanel implements ITerminal {
    readonly type: TerminalPanelType;
    static panelCount: Record<TerminalPanelType, number>;
    static resetCount(): void;
    readonly id: string;
    readonly title: string;
    get terminal(): ITerminal | undefined;
    get process(): WebContainerProcess | undefined;
    get processOptions(): {
        allowRedirects: boolean;
        allowCommands: string[] | undefined;
    } | undefined;
    get cols(): number | undefined;
    get rows(): number | undefined;
    reset(): void;
    write(data: string): void;
    onData(callback: (data: string) => void): void;
    attachProcess(process: WebContainerProcess): void;
    attachTerminal(terminal: ITerminal): void;
}
```

#### `ITerminal`
```ts
interface ITerminal {
    readonly cols?: number;
    readonly rows?: number;
    reset: () => void;
    write: (data: string) => void;
    onData: (cb: (data: string) => void) => void;
}
```

#### `EditorConfig`
```ts
class EditorConfig {
    get visible(): boolean;
    get fileTree(): {
        visible: boolean;
        allowEdits: false | string[];
    };
}
```

#### `EditorDocument`
```ts
interface EditorDocument {
    value: string | Uint8Array;
    loading: boolean;
    filePath: string;
    type: FileDescriptor['type'];
    scroll?: ScrollPosition;
}
```

#### `ScrollPosition`
```ts
interface ScrollPosition {
    top: number;
    left: number;
}
```

#### `BootStatus`
```ts
type BootStatus = 'unknown' | 'blocked' | 'booting' | 'booted';
```

#### `EditorDocuments`
```ts
type EditorDocuments = Record<string, EditorDocument | undefined>
```

#### `FileDescriptor`
```ts
type FileDescriptor = {
    path: string;
    type: 'file' | 'folder';
}
```

#### `Lesson`
```ts
import type { Lesson } from '@tutorialkit/types';
```
```

--------------------------------

### Access tutorial state with HelpButton and content.mdx

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/how-to-use-tutorialkit-api.mdx

Use the TutorialKit store to read the contents of /index.js and provide hints when the user clicks Help. The HelpButton component imports tutorialStore from "tutorialkit:store" and uses magicast's parseModule to verify the code. The content.mdx lesson imports and mounts the HelpButton with client:load, setting focus to /index.js.

```tsx
import tutorialStore from "tutorialkit:store";
import { Dialog } from "@tutorialkit/react";
import { useState } from "react";
import { parseModule } from "magicast";

export default function HelpButton() {
  const [message, setMessage] = useState<string | null>(null);

  function onClick() {
    const files = tutorialStore.documents.value;
    const index = files["/index.js"].value as string;

    const message = verifyIndexJs(index);
    setMessage(message);
  }

  return (
    <>
      <button onClick={onClick} className="px-4 py-1 rounded-md bg-tk-elements-primaryButton-backgroundColor text-tk-elements-primaryButton-textColor">
        Help
      </button>

      {message && (
        <Dialog title="Help" confirmText="OK" onClose={() => setMessage(null)}>
          {message}
        </Dialog>
      )}
    </>
  );
}

function verifyIndexJs(code: string) {
  const mod = parseModule(code);

  const hasSumFunction =
    mod.$ast.type === "Program" &&
    mod.$ast.body.some(
      (node) => node.type === "FunctionDeclaration" && node.id.name === "sum"
    );

  if (!hasSumFunction) {
    return "Your index.js should have a sum function";
  }

  if (mod.exports.default?.$name !== "sum") {
    return "Your index.js should export sum as default export";
  }

  return "All good";
}

```

```mdx
---
type: lesson
title: TutorialKit API usage example
focus: /index.js
---

import HelpButton from '@components/HelpButton';

# TutorialKit API usage example

Click this button if you get stuck:

<HelpButton client:load />

```

--------------------------------

### Build TutorialKit project with npm, pnpm, or yarn

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/deployment.mdx

Build commands for npm, pnpm, and yarn to prepare the production build of a TutorialKit project. Generates a dist directory containing static files.

```shell
npm run build
```

```shell
pnpm build
```

```shell
yarn build
```

--------------------------------

### Parts-and-lessons structure and file tree

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Shows a tutorial structure with parts and lessons (no chapters) and its corresponding file tree.

```plaintext
- Part 1: Introduction
  - Lesson 1: What is Vite?
  - Lesson 2: Installing
    - …
- Part 2: Project structure
    - …
```

```plaintext
- src
  - content
    - tutorial
      - introduction/
        - what-is-vite/
          - _files/
          - _solution/
          - content.md
        - installing/
      - project-structure/
      - meta.md
  - config.ts
  - templates/
```

--------------------------------

### Import Tutorial Core

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/tutorialkit-api.mdx

Import the Tutorial Core module using the 'tutorialkit:core' entrypoint to access webcontainer APIs for reading and modifying files on the virtual file system.

```typescript
import * as core from "tutorialkit:core";
```

--------------------------------

### Import tutorialStore from tutorialkit:store

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/tutorialkit-api.mdx

Import the tutorial store from the 'tutorialkit:store' entrypoint. This API is experimental and may introduce breaking changes in patch and minor version updates.

```ts
import tutorialStore from "tutorialkit:store";
```

--------------------------------

### TutorialKit project file tree

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Shows the directory structure of a TutorialKit project with numbered folders for parts and chapters.

```plaintext
- src
  - content
    - tutorial
      - 1-basics
        - 1-introduction/
        - 2-your-first-vite-project/
      - 2-vite-cli/
      - meta.md
  - config.ts
  - templates/
```

--------------------------------

### fieldset:focus-within styling

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/demo/src/content/tutorial/1-forms-css/3-fieldset/5-focus-within/content.md

Applies background and border styles to a fieldset when any descendant receives focus, and styles the legend with matching colors. The selector matches whenever a descendant gets focus.

```css
fieldset:focus-within {
  background: #00a1;
  border-color: #00a6;
}

fieldset:focus-within legend {
  color: #00a9;
  border-color: #00a6;
}
```

--------------------------------

### Lessons-only structure and file tree

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Shows a tutorial structure with only lessons (no parts or chapters) and its corresponding file tree.

```plaintext
- Lesson 1: Getting started
- Lesson 2: Adding pages
```

```plaintext
- src
  - content
    - tutorial
      - getting-started
        - _files/
        - _solution/
        - content.md
      - adding-pages/
      - meta.md
  - config.ts
  - templates/
```

--------------------------------

### Write to terminal with tutorialStore.terminalConfig

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/how-to-use-tutorialkit-api.mdx

Shows how to write a command to the terminal using the Tutorial Store API. The TerminalWriter component accesses the first terminal panel via tutorialStore.terminalConfig.value!.panels[0] and calls terminal.input('npm run test\n') when the button is clicked. The content.mdx file imports the component and renders it with client:load, so the button appears in the lesson.

```tsx
import tutorialStore from 'tutorialkit:store';

export default function TerminalWriter() {
  async function onClick() {
    const terminal = tutorialStore.terminalConfig.value!.panels[0];
    terminal.input('npm run test\n');
  }

  return (
    <button
      onClick={onClick}
      className="px-4 py-1 my-3 cursor-pointer border-1 border-tk-border-primary rounded-md bg-tk-elements-primaryButton-backgroundColor text-tk-elements-primaryButton-textColor"
    >
      Run tests
    </button>
  );
}

```

```mdx
---
type: lesson
title: Write to Terminal example
---

import TerminalWriter from "@components/TerminalWriter";

# Write to Terminal example

Fix <code>counter.js</code> and run the tests!

<TerminalWriter client:load />

```

--------------------------------

### CSS grid layout for form controls

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/demo/src/content/tutorial/1-forms-css/2-colors/1-accent-color/_files/index.html

CSS layout for a form with a two-column grid, aligning labels to the end and inputs to the start. Styles labels with a monospace font, except the color label, and scales form controls to 1.5 times their size.

```css
body { display: grid; gap: 0 16px; grid-template-columns: 1fr 1fr; justify-items: end; align-items: center; font-family: 'Gill Sans', 'Gill Sans MT', Calibri, 'Trebuchet MS', sans-serif; }
body > :not(label) { justify-self: start; }
label { margin: 1.2rem 0 0.8rem; font-family: 'Courier New', Courier, monospace; font-weight: bold; }
label[for='color'] { font-family: 'Gill Sans', 'Gill Sans MT', Calibri, 'Trebuchet MS', sans-serif; font-weight: normal; padding: 0; }
input, meter, progress { transform-origin: left; transform: scale(1.5); }
```

--------------------------------

### Create an info callout with :::info

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Use this callout syntax to create an info callout in lesson content. The callout supports markdown syntax and links inside its body.

```markdown
:::info
Some info with some markdown `syntax` and a [`link`](https://tutorialkit.dev/).

Here's a normal [link](https://tutorialkit.dev/).
:::
```

--------------------------------

### Import a file with the file shortcode

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Shows how to import a file from the _files folder using the file shortcode. The first block is the shortcode, the second is the content of the imported file.

```markdown
```file:/box.css
```
```

```css
.box {
  width: 100px;
  height: 100px;
  background-color: red;
}
```

--------------------------------

### Configure Tutorialkit Astro integration in astro.config.ts

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

Configures the `@tutorialkit/astro` integration in `astro.config.ts`. Disables the dev toolbar and adds the `tutorialkit()` integration.

```ts
import tutorialkit from "@tutorialkit/astro";
import { defineConfig } from "astro/config";

export default defineConfig({
  devToolbar: {
    enabled: false,
  },
  integrations: [
    tutorialkit(),
  ],
});
```

--------------------------------

### UI Structure Diagram

Source: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/README.md

ASCII diagram of the TutorialKit UI layout, showing the content area, code editor, preview/boot screen, and terminal.

```markdown
┌─────────────────────────────────────────────────────┐
│ ● ● ●                                               │
├───────────────────────────┬─────────────────────────┤
│                           │                         │
│                           │                         │
│                           │                         │
│                           │                         │
│                           │       Code Editor       │
│                           │                         │
│                           │                         │
│                           │                         │
│          Content          ├─────────────────────────┤
│                           │                         │
│                           │                         │
│                           │  Preview & Boot Screen  │
│                           │                         │
│                           │                         │
│                           ├─────────────────────────┤
│                           │                         │
│                           │        Terminal         │
│                           │                         │
└───────────────────────────┴─────────────────────────┘
```

--------------------------------

### Create uno.config.ts with defineConfig

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/react-components.mdx

Create a UnoCSS configuration file that imports defineConfig from @tutorialkit/theme. Add your custom UnoCSS configuration inside the defineConfig call.

```ts
import { defineConfig } from '@tutorialkit/theme';

export default defineConfig({
  // add your UnoCSS config here: https://unocss.dev/guide/config-file
});
```

--------------------------------

### TutorialKit API Methods

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/tutorialkit-api.mdx

Methods available on the TutorialKit API for interacting with the lesson state, file tree, editor, and terminal.

```APIDOC
## hasFileTree

### Description
Check if file tree is visible.

### Method
hasFileTree

### Signature
`() => boolean`

### Returns
- **boolean** - Whether the file tree is visible.

```

```APIDOC
## hasEditor

### Description
Check if editor is visible.

### Method
hasEditor

### Signature
`() => boolean`

### Returns
- **boolean** - Whether the editor is visible.

```

```APIDOC
## hasPreviews

### Description
Check if lesson has any previews set.

### Method
hasPreviews

### Signature
`() => boolean`

### Returns
- **boolean** - Whether the lesson has any previews set.

```

```APIDOC
## hasTerminalPanel

### Description
Check if lesson has any terminals set.

### Method
hasTerminalPanel

### Signature
`() => boolean`

### Returns
- **boolean** - Whether the lesson has any terminals set.

```

```APIDOC
## hasSolution

### Description
Check if lesson has solution files set.

### Method
hasSolution

### Signature
`() => boolean`

### Returns
- **boolean** - Whether the lesson has solution files set.

```

```APIDOC
## unblockBoot

### Description
Unlock webcontainer's boot process if it was in `'blocked'` state.

### Method
unblockBoot

### Signature
`() => void`

### Returns
- **void** - No return value.

```

```APIDOC
## reset

### Description
Reset changed files back to lesson's initial state.

### Method
reset

### Signature
`() => void`

### Returns
- **void** - No return value.

```

```APIDOC
## solve

### Description
Apply lesson solution into the lesson files.

### Method
solve

### Signature
`() => void`

### Returns
- **void** - No return value.

```

```APIDOC
## setSelectedFile

### Description
Set file from file tree as selected.

### Method
setSelectedFile

### Signature
`(filePath: string | undefined) => void`

### Parameters
- **filePath** (string | undefined) - Required - The path of the file to select.

### Returns
- **void** - No return value.

```

```APIDOC
## addFile

### Description
Add new file to file tree. Throws error with message `FILE_EXISTS` if file exists already on file system.

### Method
addFile

### Signature
`(filePath: string) => Promise<void>`

### Parameters
- **filePath** (string) - Required - The path of the new file.

### Returns
- **Promise<void>** - A promise that resolves when the file is added.

### Errors
- **FILE_EXISTS** - Thrown if the file already exists.

```

```APIDOC
## addFolder

### Description
Add new file to file tree. Throws error with message `FOLDER_EXISTS` if folder exists already on file system.

### Method
addFolder

### Signature
`(folderPath: string) => Promise<void>`

### Parameters
- **folderPath** (string) - Required - The path of the new folder.

### Returns
- **Promise<void>** - A promise that resolves when the folder is added.

### Errors
- **FOLDER_EXISTS** - Thrown if the folder already exists.

```

```APIDOC
## updateFile

### Description
Update contents of file.

### Method
updateFile

### Signature
`(filePath: string, content: string) => void`

### Parameters
- **filePath** (string) - Required - The path of the file to update.
- **content** (string) - Required - The new content of the file.

### Returns
- **void** - No return value.

```

```APIDOC
## setCurrentDocumentContent

### Description
Update content of the active file.

### Method
setCurrentDocumentContent

### Signature
`(newContent: string) => void`

### Parameters
- **newContent** (string) - Required - The new content for the active file.

### Returns
- **void** - No return value.

```

```APIDOC
## setCurrentDocumentScrollPosition

### Description
Update scroll position of the file in editor.

### Method
setCurrentDocumentScrollPosition

### Signature
`(position: ScrollPosition) => void`

### Parameters
- **position** (ScrollPosition) - Required - The scroll position object.

### Types
```ts
interface ScrollPosition {
  top: number;
  left: number;
}
```

### Returns
- **void** - No return value.

```

```APIDOC
## onTerminalResize

### Description
Callback that should be called when terminal resizes.

### Method
onTerminalResize

### Signature
`(cols: number, rows: number) => void`

### Parameters
- **cols** (number) - Required - The number of columns.
- **rows** (number) - Required - The number of rows.

### Returns
- **void** - No return value.

```

```APIDOC
## onDocumentChanged

### Description
Listen for file changes made in the editor.

### Method
onDocumentChanged

### Signature
`(filePath: string, callback: (document: Readonly<EditorDocument>) => void) => () => void`

### Parameters
- **filePath** (string) - Required - The path of the file to listen to.
- **callback** (function) - Required - Callback invoked with the updated document.

### Types
```ts
import type { FileDescriptor } from '@tutorialkit/types';

interface EditorDocument {
    value: string | Uint8Array;
    loading: boolean;
    filePath: string;
    type: FileDescriptor['type'];
    scroll?: ScrollPosition;
}

interface ScrollPosition {
    top: number;
    left: number;
}
```

### Returns
- **() => void** - A function to unsubscribe from the listener.

```

```APIDOC
## takeSnapshot

### Description
Take snapshot of the current state of the lesson.

### Method
takeSnapshot

### Signature
`() => { files: Record<string, string> }`

### Returns
- **{ files: Record<string, string> }** - An object containing the current files.

```

--------------------------------

### Configure pnpm.overrides for local TutorialKit packages

Source: https://github.com/stackblitz/tutorialkit/blob/main/CONTRIBUTING.md

Add pnpm.overrides to the root package.json to link local TutorialKit packages when testing against external projects. The packages must first be listed as dependencies in the root package.json.

```json
{
  "pnpm": {
    "overrides": {
      "@tutorialkit/astro": "file:../tutorialkit/packages/astro",
      "@tutorialkit/react": "file:../tutorialkit/packages/react",
      "@tutorialkit/runtime": "file:../tutorialkit/packages/runtime",
      "@tutorialkit/theme": "file:../tutorialkit/packages/theme",
      "@tutorialkit/types": "file:../tutorialkit/packages/types"
    }
  }
}
```

--------------------------------

### Import uno.css and theme.css in src/main.ts

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/react-components.mdx

Import the generated UnoCSS styles and the theme CSS variables in your main entry file so they are included in your build.

```ts
import 'uno.css';
import './theme.css';
```

--------------------------------

### Override components with tutorialkit()

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

Overrides a component by providing the path to a custom component. Here, `TopBar` is replaced with `./src/components/CustomTopBar.astro`.

```ts
tutorialkit({
  components: {
    TopBar: './src/components/CustomTopBar.astro',
  },
});
```

--------------------------------

### Configure components option in astro.config.ts

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/overriding-components.mdx

Defines the `components` option in `astro.config.ts` to override TutorialKit's built-in components. The `components` object is where you specify which component to override and the path to your custom component.

```ts
import tutorialkit from '@tutorialkit/astro';
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [
    tutorialkit({
      components: {
        // Component overrides go here
      },
    }),
  ],
});
```

--------------------------------

### Import Lesson type for lesson property

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/tutorialkit-api.mdx

Import the Lesson type from '@tutorialkit/types' for the 'lesson' property, which is a Readonly<Lesson> | undefined.

```ts
import type { Lesson } from '@tutorialkit/types';
```

--------------------------------

### .tk-config.json with extends property

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Create a shared template by setting the 'extends' property in a template's .tk-config.json file. The path is relative to the template directory.

```json
{
  "extends": "../shared-template"
}
```

--------------------------------

### CSS for label layout

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/demo/src/content/tutorial/1-forms-css/1-introduction/1-welcome/_files/index.html

Basic CSS styling for the tutorial page: sets the font family to sans-serif, makes labels inline-block with a fixed width of 100px, right-aligns their text, and adds 6px padding.

```css
body { font-family: sans-serif; } label { display: inline-block; width: 100px; text-align: right; padding: 6px; }
```

--------------------------------

### PreviewInfo and PortInfo classes for previews property

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/tutorialkit-api.mdx

Type definitions for the 'previews' property, which is a ReadableAtom<PreviewInfo[]>. Includes the PreviewInfo class with static parse and equals methods, and the PortInfo class.

```ts
import type { PreviewSchema } from '@tutorialkit/types';

class PreviewInfo {
    readonly portInfo: PortInfo;
    title?: string;
    pathname?: string;
    get url(): string | undefined;
    get port(): number;
    get baseUrl(): string | undefined;
    get ready(): boolean;
    static parse(preview: Exclude<PreviewSchema, boolean>[0]): Preview;
    static equals(a: PreviewInfo, b: PreviewInfo): boolean;
}
class PortInfo {
    readonly port: number;
    origin?: string | undefined;
    ready: boolean;
}
interface Preview {
    port: number;
    pathname?: string;
    title?: string;
}
```

--------------------------------

### Lesson content file structure (content.md)

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Basic structure of a lesson file with frontmatter (type: lesson, title) and Markdown content. The frontmatter is enclosed by '---' lines and contains metadata like title. Content below is the lesson body.

```markdown
---
type: lesson
title: Welcome to TutorialKit
# ...
---

# Kitchen Sink [Heading 1]
Lorem ipsum dolor
<!--  ... -->

```

--------------------------------

### Custom fields configuration and consumption

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

Shows how to assign custom fields to a chapter/part/lesson and then consume them from the default `tutorial` collection. The YAML defines custom fields, and the TypeScript code retrieves and logs the `publishedAt` value.

```yaml
custom:
  publishedAt: 2024-16-10
  tags: tutorialkit,astro,vite
```

```ts
import { getCollection } from 'astro:content';
const collection = await getCollection('tutorial');
for (const entry of collection) {
  console.log("This part was published at:", entry.data?.custom?.publishedAt)
}
```

--------------------------------

### Netlify netlify.toml headers configuration

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/deployment.mdx

Configure headers in netlify.toml for Netlify to set cross-origin isolation headers.

```yaml
[[headers]]
  for = "/*"
  [headers.values]
    Cross-Origin-Embedder-Policy = "require-corp"
    Cross-Origin-Opener-Policy = "same-origin"
```

--------------------------------

### Cloudflare postbuild script in package.json

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/deployment.mdx

Add a postbuild script to package.json to copy the _headers file to the dist directory after build for Cloudflare.

```json
{
  "scripts": {
    "postbuild": "cp _headers ./dist/"
  }
}
```

--------------------------------

### Mark text in code blocks with strings and regex

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

Demonstrates marking text in code blocks using strings and regular expressions. The first block is the Markdown source, the second is the rendered JSX code block.

```markdown
```jsx title="code.js" "hello" /ye[sp]/ add=/add[12]/ del=/remove[12]/
console.log(
  'Hello, the words yes and yep will be marked. Also add1, add2, remove1, remove2',
)
```
```

```jsx
console.log(
  'Hello, the words yes and yep will be marked. Also add1, add2, remove1, remove2',
)
```

--------------------------------

### FileSystem type definition

Source: https://github.com/stackblitz/tutorialkit/blob/main/docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

Defines the FileSystem type, which has a watch property that can be a boolean or an array of glob strings.

```typescript
type FileSystem = {
  watch: boolean | string[]
}

```
Tokens:
Raw