feat: sync files from WebContainer to editor (#334)

Author: Nemikolh

docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

@@ -260,6 +260,35 @@ type Command = string
 
 ```
 
+##### `filesystem`
+Configures how changes such as files being modified or added in WebContainer should be reflected in the editor when they weren't caused by the user directly. By default, the editor will not reflect these changes.
+
+An example use case is when a user runs a command that modifies a file. For instance when a `package.json` is modified by doing an `npm install <xyz>`. If `watch` is set to `true`, the file will be updated in the editor. If set to `false`, the file will not be updated.
+
+This property is by default set to `false` as it can impact performance. If you are creating a lesson where the user is expected to modify files outside the editor, you may want to keep this to `false`.
+
+<PropertyTable inherited type={'FileSystem'} />
+
+The `FileSystem` type has the following shape:
+
+```ts
+type FileSystem = {
+  watch: boolean
+}
+
+```
+
+Example values:
+
+```yaml
+filesystem:
+  watch: true  # Filesystem changes are reflected in the editor
+
+filesystem:
+  watch: false # Or if it's omitted, the default value is false
+```
+
+
 ##### `terminal`
 Configures one or more terminals. TutorialKit provides two types of terminals: read-only, called `output`, and interactive, called `terminal`. Note, that there can be only one `output` terminal.
 
@@ -319,7 +348,7 @@ Navigating to a lesson that specifies `autoReload` will always reload the previe
 Specifies which folder from the `src/templates/` directory should be used as the basis for the code. See the "[Code templates](/guides/creating-content/#code-templates)" guide for a detailed explainer.
 <PropertyTable inherited type="string" />
 
-#### `editPageLink`
+##### `editPageLink`
 Display a link in lesson for editing the page content.
 The value is a URL pattern where `${path}` is replaced with the lesson's location relative to the `src/content/tutorial`.
 
@@ -346,7 +375,7 @@ You can instruct Github to show the source code instead by adding `plain=1` quer
 
 :::
 
-### `openInStackBlitz`
+##### `openInStackBlitz`
 Display a link for opening current lesson in StackBlitz.
 <PropertyTable inherited type="OpenInStackBlitz" />
 

e2e/src/components/ButtonWriteToFile.tsx

@@ -1,22 +1,30 @@
 import tutorialStore from 'tutorialkit:store';
+import { webcontainer } from 'tutorialkit:core';
 
 interface Props {
   filePath: string;
   newContent: string;
+
+  // default to 'store'
+  access?: 'store' | 'webcontainer';
   testId?: string;
 }
 
-export function ButtonWriteToFile({ filePath, newContent, testId = 'write-to-file' }: Props) {
+export function ButtonWriteToFile({ filePath, newContent, access = 'store', testId = 'write-to-file' }: Props) {
   async function writeFile() {
-    await new Promise<void>((resolve) => {
-      tutorialStore.lessonFullyLoaded.subscribe((value) => {
-        if (value) {
-          resolve();
-        }
-      });
-    });
+    switch (access) {
+      case 'webcontainer': {
+        const webcontainerInstance = await webcontainer;
+
+        await webcontainerInstance.fs.writeFile(filePath, newContent);
 
-    tutorialStore.updateFile(filePath, newContent);
+        return;
+      }
+      case 'store': {
+        tutorialStore.updateFile(filePath, newContent);
+        return;
+      }
+    }
   }
 
   return (

e2e/src/content/tutorial/tests/filesystem/meta.md

@@ -0,0 +1,4 @@
+---
+type: chapter
+title: filesystem
+---

e2e/src/content/tutorial/tests/filesystem/no-watch/_files/bar.txt

@@ -0,0 +1 @@
+Initial content

e2e/src/content/tutorial/tests/filesystem/no-watch/content.mdx

@@ -0,0 +1,11 @@
+---
+type: lesson
+title: No watch
+focus: /bar.txt
+---
+
+import { ButtonWriteToFile } from '@components/ButtonWriteToFile';
+
+# Watch filesystem test
+
+<ButtonWriteToFile client:load access="webcontainer" filePath="/bar.txt" newContent='Something else' />

e2e/src/content/tutorial/tests/filesystem/watch/_files/a/b/baz.txt

@@ -0,0 +1 @@
+Baz

e2e/src/content/tutorial/tests/filesystem/watch/_files/bar.txt

@@ -0,0 +1 @@
+Initial content

e2e/src/content/tutorial/tests/filesystem/watch/content.mdx

@@ -0,0 +1,14 @@
+---
+type: lesson
+title: Watch
+focus: /bar.txt
+filesystem:
+  watch: true
+---
+
+import { ButtonWriteToFile } from '@components/ButtonWriteToFile';
+
+# Watch filesystem test
+
+<ButtonWriteToFile client:load access="webcontainer" filePath="/bar.txt" newContent='Something else' />
+<ButtonWriteToFile client:load access="webcontainer" filePath="/a/b/baz.txt" newContent='Foo' testId='write-to-file-in-subfolder' />

e2e/test/filesystem.test.ts

@@ -0,0 +1,52 @@
+import { test, expect } from '@playwright/test';
+
+const BASE_URL = '/tests/filesystem';
+
+test('editor should reflect changes made from webcontainer', async ({ page }) => {
+  const testCase = 'watch';
+  await page.goto(`${BASE_URL}/${testCase}`);
+
+  await expect(page.getByRole('textbox', { name: 'Editor' })).toHaveText('Initial content\n', {
+    useInnerText: true,
+  });
+
+  await page.getByTestId('write-to-file').click();
+
+  await expect(page.getByRole('textbox', { name: 'Editor' })).toHaveText('Something else', {
+    useInnerText: true,
+  });
+});
+
+test('editor should reflect changes made from webcontainer in file in nested folder', async ({ page }) => {
+  const testCase = 'watch';
+  await page.goto(`${BASE_URL}/${testCase}`);
+
+  await page.getByRole('button', { name: 'baz.txt' }).click();
+
+  await expect(page.getByRole('textbox', { name: 'Editor' })).toHaveText('Baz', {
+    useInnerText: true,
+  });
+
+  await page.getByTestId('write-to-file-in-subfolder').click();
+
+  await expect(page.getByRole('textbox', { name: 'Editor' })).toHaveText('Foo', {
+    useInnerText: true,
+  });
+});
+
+test('editor should not reflect changes made from webcontainer if watch is not set', async ({ page }) => {
+  const testCase = 'no-watch';
+  await page.goto(`${BASE_URL}/${testCase}`);
+
+  await expect(page.getByRole('textbox', { name: 'Editor' })).toHaveText('Initial content\n', {
+    useInnerText: true,
+  });
+
+  await page.getByTestId('write-to-file').click();
+
+  await page.waitForTimeout(1_000);
+
+  await expect(page.getByRole('textbox', { name: 'Editor' })).toHaveText('Initial content\n', {
+    useInnerText: true,
+  });
+});

packages/astro/src/default/utils/content.ts

@@ -247,6 +247,7 @@ export async function getTutorial(): Promise<Tutorial> {
           'i18n',
           'editPageLink',
           'openInStackBlitz',
+          'filesystem',
         ],
       ),
     };

packages/runtime/README.md

@@ -4,10 +4,9 @@ A wrapper around the **[WebContainer API][webcontainer-api]** focused on providi
 
 The runtime exposes the following:
 
-- `lessonFilesFetcher`: A singleton that lets you fetch the contents of the lesson files
-- `TutorialRunner`: The API to manage your tutorial content in WebContainer
+- `TutorialStore`: A store to manage your tutorial content in WebContainer and in your components.
 
-Only a single instance of `TutorialRunner` should be created in your application and its lifetime is bound by the lifetime of the WebContainer instance.
+Only a single instance of `TutorialStore` should be created in your application and its lifetime is bound by the lifetime of the WebContainer instance.
 
 ## License
 

packages/runtime/src/index.ts

@@ -1,5 +1,3 @@
-export { LessonFilesFetcher } from './lesson-files.js';
-export { TutorialRunner } from './tutorial-runner.js';
 export type { Command, Commands, PreviewInfo, Step, Steps } from './webcontainer/index.js';
 export { safeBoot } from './webcontainer/index.js';
 export { TutorialStore } from './store/index.js';

packages/runtime/src/store/editor.ts

@@ -113,7 +113,7 @@ export class EditorStore {
     });
   }
 
-  updateFile(filePath: string, content: string): boolean {
+  updateFile(filePath: string, content: string | Uint8Array): boolean {
     const documentState = this.documents.get()[filePath];
 
     if (!documentState) {

packages/runtime/src/store/index.ts

@@ -3,7 +3,6 @@ import type { WebContainer } from '@webcontainer/api';
 import { atom, type ReadableAtom } from 'nanostores';
 import { LessonFilesFetcher } from '../lesson-files.js';
 import { newTask, type Task } from '../tasks.js';
-import { TutorialRunner } from '../tutorial-runner.js';
 import type { ITerminal } from '../utils/terminal.js';
 import type { EditorConfig } from '../webcontainer/editor-config.js';
 import { bootStatus, unblockBoot, type BootStatus } from '../webcontainer/on-demand-boot.js';
@@ -13,6 +12,7 @@ import type { TerminalConfig } from '../webcontainer/terminal-config.js';
 import { EditorStore, type EditorDocument, type EditorDocuments, type ScrollPosition } from './editor.js';
 import { PreviewsStore } from './previews.js';
 import { TerminalStore } from './terminal.js';
+import { TutorialRunner } from './tutorial-runner.js';
 
 interface StoreOptions {
   webcontainer: Promise<WebContainer>;
@@ -59,7 +59,7 @@ export class TutorialStore {
     this._lessonFilesFetcher = new LessonFilesFetcher(basePathname);
     this._previewsStore = new PreviewsStore(this._webcontainer);
     this._terminalStore = new TerminalStore(this._webcontainer, useAuth);
-    this._runner = new TutorialRunner(this._webcontainer, this._terminalStore, this._stepController);
+    this._runner = new TutorialRunner(this._webcontainer, this._terminalStore, this._editorStore, this._stepController);
 
     /**
      * By having this code under `import.meta.hot`, it gets:
@@ -150,6 +150,8 @@ export class TutorialStore {
       return;
     }
 
+    this._runner.setWatchFromWebContainer(lesson.data.filesystem?.watch ?? false);
+
     this._lessonTask = newTask(
       async (signal) => {
         const templatePromise = this._lessonFilesFetcher.getLessonTemplate(lesson);

packages/runtime/src/tutorial-runner.spec.ts renamed to packages/runtime/src/store/tutorial-runner.spec.ts

@@ -4,10 +4,11 @@ import { resetProcessFactory, setProcessFactory } from '@tutorialkit/test-utils'
 import type { MockedWebContainer } from '@tutorialkit/test-utils';
 import { WebContainer } from '@webcontainer/api';
 import { beforeEach, describe, expect, test, vi } from 'vitest';
-import { TerminalStore } from './store/terminal.js';
+import { withResolvers } from '../utils/promises.js';
+import { StepsController } from '../webcontainer/steps.js';
+import { EditorStore } from './editor.js';
+import { TerminalStore } from './terminal.js';
 import { TutorialRunner } from './tutorial-runner.js';
-import { withResolvers } from './utils/promises.js';
-import { StepsController } from './webcontainer/steps.js';
 
 beforeEach(() => {
   resetProcessFactory();
@@ -17,7 +18,12 @@ describe('TutorialRunner', () => {
   test('prepareFiles should mount files to WebContainer', async () => {
     const webcontainer = WebContainer.boot();
     const mock = (await webcontainer) as MockedWebContainer;
-    const runner = new TutorialRunner(webcontainer, new TerminalStore(webcontainer, false), new StepsController());
+    const runner = new TutorialRunner(
+      webcontainer,
+      new TerminalStore(webcontainer, false),
+      new EditorStore(),
+      new StepsController(),
+    );
 
     await runner.prepareFiles({
       files: {
@@ -72,7 +78,12 @@ describe('TutorialRunner', () => {
 
     setProcessFactory(processFactory);
 
-    const runner = new TutorialRunner(webcontainer, new TerminalStore(webcontainer, false), new StepsController());
+    const runner = new TutorialRunner(
+      webcontainer,
+      new TerminalStore(webcontainer, false),
+      new EditorStore(),
+      new StepsController(),
+    );
 
     runner.setCommands({
       mainCommand: 'some command',