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',
         ],
       ),
     };