feat: allow custom components that modify the tutorial state (#64)

Author: Nemikolh

packages/astro/package.json

@@ -9,6 +9,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./types": "./types.d.ts",
     "./default/pages/index.astro": "./dist/default/pages/index.astro",
     "./default/pages/[...slug].astro": "./dist/default/pages/[...slug].astro"
   },

packages/astro/src/index.ts

@@ -3,7 +3,9 @@ import { fileURLToPath } from 'node:url';
 import { extraIntegrations } from './integrations.js';
 import { updateMarkdownConfig } from './remark/index.js';
 import { WebContainerFiles } from './webcontainer-files.js';
-import { userlandCSS, watchUserlandCSS } from './css.js';
+import { userlandCSS, watchUserlandCSS } from './vite-plugins/css.js';
+import { tutorialkitStore } from './vite-plugins/store.js';
+import { tutorialkitCore } from './vite-plugins/core.js';
 
 export { theme } from './theme.js';
 
@@ -84,6 +86,8 @@ export default function createPlugin({ defaultRoutes = true, isolation, enterpri
             },
             plugins: [
               userlandCSS,
+              tutorialkitStore,
+              tutorialkitCore,
               process.env.TUTORIALKIT_DEV ? (await import('vite-plugin-inspect')).default() : null,
             ],
           },

packages/astro/src/utils.ts

@@ -13,3 +13,8 @@ export function withResolvers<T>(): PromiseWithResolvers<T> {
     promise,
   };
 }
+
+export function normalizeImportPath(importPath: string): string {
+  // this is a fix for windows where import path should still use forward slashes
+  return importPath.replaceAll('\\', '/');
+}

packages/astro/src/vite-plugins/core.ts

@@ -0,0 +1,47 @@
+/**
+ * A plugin that let users write components that can access the internals
+ * of TutorialKit
+ *
+ * The virtual module can be imported as:
+ *
+ * ```ts
+ * import { webcontainer } from 'tutorialkit:core';
+ *
+ * export const MyComponent = () => {
+ *   useEffect(() => {
+ *     (async () => {
+ *       const webcontainerInstance = await webcontainer;
+ *       await webcontainerInstance.fs.writeFile('foo.js', 'console.log("hello world")');
+ *     })();
+ *   }, []);
+ *
+ *   return null;
+ * };
+ * ```
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { VitePlugin } from '../types.js';
+import { normalizeImportPath } from '../utils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const virtualModuleId = 'tutorialkit:core';
+const resolvedVirtualModuleId = `${virtualModuleId}`;
+
+export const tutorialkitCore: VitePlugin = {
+  name: 'tutorialkit-core-virtual-mod-plugin',
+  resolveId(id) {
+    if (id === virtualModuleId) {
+      return resolvedVirtualModuleId;
+    }
+  },
+  async load(id) {
+    if (id === resolvedVirtualModuleId) {
+      const pathToInit = normalizeImportPath(path.join(__dirname, 'default/components/webcontainer.ts'));
+
+      return `
+        export { webcontainer } from '${pathToInit}';
+      `;
+    }
+  },
+};

packages/astro/src/css.ts renamed to packages/astro/src/vite-plugins/css.ts

@@ -9,7 +9,7 @@
 import { watch } from 'chokidar';
 import fs from 'fs/promises';
 import path from 'path';
-import type { ViteDevServer, VitePlugin } from './types.js';
+import type { ViteDevServer, VitePlugin } from '../types.js';
 import type { AstroIntegrationLogger } from 'astro';
 
 const CUSTOM_PATHS = ['theme.css', 'theme/index.css'];

packages/astro/src/vite-plugins/store.ts

@@ -0,0 +1,41 @@
+/**
+ * A plugin that let users write components that can interact with the tutorial
+ * state, indirectly acting on the editor and WebContainer.
+ *
+ * The virtual module can be imported as:
+ *
+ * ```ts
+ * import tutorialStore from 'tutorialkit:store';
+ *
+ * export const MyComponent = () => (
+ *   <button onClick={() => tutorialStore.reset()}>Reset</button>
+ * );
+ * ```
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { VitePlugin } from '../types.js';
+import { normalizeImportPath } from '../utils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const virtualModuleId = 'tutorialkit:store';
+const resolvedVirtualModuleId = `${virtualModuleId}`;
+
+export const tutorialkitStore: VitePlugin = {
+  name: 'tutorialkit-store-virtual-mod-plugin',
+  resolveId(id) {
+    if (id === virtualModuleId) {
+      return resolvedVirtualModuleId;
+    }
+  },
+  async load(id) {
+    if (id === resolvedVirtualModuleId) {
+      const pathToInit = normalizeImportPath(path.join(__dirname, 'default/components/webcontainer.ts'));
+
+      return `
+        import { tutorialStore } from '${pathToInit}';
+        export default tutorialStore;
+      `;
+    }
+  },
+};

packages/astro/types.d.ts

@@ -0,0 +1,9 @@
+declare module 'tutorialkit:store' {
+  const tutorialStore: import('@tutorialkit/runtime').TutorialStore;
+
+  export default tutorialStore;
+}
+
+declare module 'tutorialkit:core' {
+  export const webcontainer: import('@webcontainer/api').WebContainer;
+}

packages/template/package.json

@@ -16,6 +16,7 @@
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
+    "@types/react": "^18.2.75",
     "@astrojs/check": "^0.6.0",
     "@astrojs/react": "^3.3.4",
     "@iconify-json/ph": "^1.1.12",

packages/template/src/content/tutorial/1-basics/1-introduction/2-foo/content.md renamed to packages/template/src/content/tutorial/1-basics/1-introduction/2-foo/content.mdx

@@ -1,2 +1,3 @@
 /// <reference path="../.astro/types.d.ts" />
+/// <reference types="@tutorialkit/astro/types" />
 /// <reference types="astro/client" />