feat: add template.visibleFiles option

Author: AriPerkkio

docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

@@ -110,6 +110,19 @@ template: my-advanced-template
 
 This declaration will make TutorialKit use the `src/templates/my-advanced-template` directory as the base for the lesson.
 
+By default files in template are not shown in the code editor.
+To make them visible, you can use `visibleFiles` option.
+This can reduce repetition when you want to show same files visible in multiple lessons.
+
+```markdown {5}
+---
+title: Advanced Topics
+template:
+  name: my-advanced-template
+  visibleFiles: ['index.js', '**/utils/**']
+---
+```
+
 If you start having a lot of templates and they all share some files, you can create a shared template that they all extend. This way, you can keep the shared files in one place and avoid duplication. To do that, you need to specify the `extends` property in the template's `.tk-config.json` file:
 
 ```json

packages/astro/package.json

@@ -50,6 +50,7 @@
     "kleur": "4.1.5",
     "mdast-util-directive": "^3.0.0",
     "mdast-util-to-markdown": "^2.1.0",
+    "micromatch": "^4.0.7",
     "nanostores": "^0.10.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
@@ -62,6 +63,7 @@
   "devDependencies": {
     "@tutorialkit/types": "workspace:*",
     "@types/mdast": "^4.0.4",
+    "@types/micromatch": "^4.0.9",
     "esbuild": "^0.20.2",
     "esbuild-node-externals": "^1.13.1",
     "execa": "^9.2.0",

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

@@ -10,6 +10,7 @@ import type {
 import { folderPathToFilesRef, interpolateString } from '@tutorialkit/types';
 import { getCollection } from 'astro:content';
 import glob from 'fast-glob';
+import mm from 'micromatch';
 import path from 'node:path';
 import { IGNORED_FILES } from './constants';
 import { DEFAULT_LOCALIZATION } from './content/default-localization';
@@ -18,6 +19,7 @@ import { logger } from './logger';
 import { joinPaths } from './url';
 
 const CONTENT_DIR = path.join(process.cwd(), 'src/content/tutorial');
+const TEMPLATES_DIR = path.join(process.cwd(), 'src/templates');
 
 export async function getTutorial(): Promise<Tutorial> {
   const collection = sortCollection(await getCollection('tutorial'));
@@ -262,6 +264,18 @@ export async function getTutorial(): Promise<Tutorial> {
       ),
     };
 
+    if (lesson.data.template) {
+      const template = typeof lesson.data.template === 'string' ? { name: lesson.data.template } : lesson.data.template;
+
+      const allTemplateFiles = template.visibleFiles?.length
+        ? (await getFilesRefList(template.name, TEMPLATES_DIR))[1]
+        : [];
+
+      const templateFiles = mm(allTemplateFiles, template.visibleFiles || []);
+
+      lesson.files[1] = [...lesson.files[1], ...templateFiles].filter(filterUnique).sort();
+    }
+
     if (prevLesson) {
       const partSlug = _tutorial.parts[prevLesson.part.id].slug;
       const chapterSlug = _tutorial.parts[prevLesson.part.id].chapters[prevLesson.chapter.id].slug;
@@ -330,8 +344,8 @@ function getSlug(entry: CollectionEntryTutorial) {
   return slug;
 }
 
-async function getFilesRefList(pathToFolder: string): Promise<FilesRefList> {
-  const root = path.join(CONTENT_DIR, pathToFolder);
+async function getFilesRefList(pathToFolder: string, base = CONTENT_DIR): Promise<FilesRefList> {
+  const root = path.join(base, pathToFolder);
 
   const filePaths = (
     await glob(`${glob.convertPathToPattern(root)}/**/*`, {
@@ -348,6 +362,10 @@ async function getFilesRefList(pathToFolder: string): Promise<FilesRefList> {
   return [filesRef, filePaths];
 }
 
+function filterUnique<T>(item: T, index: number, array: T[]) {
+  return array.indexOf(item) === index;
+}
+
 interface CollectionEntryTutorial {
   id: string;
   slug: string;

packages/cli/src/commands/eject/index.ts

@@ -18,7 +18,15 @@ interface PackageJson {
 }
 
 const TUTORIALKIT_VERSION = pkg.version;
-const REQUIRED_DEPENDENCIES = ['@tutorialkit/runtime', '@webcontainer/api', 'nanostores', '@nanostores/react', 'kleur'];
+const REQUIRED_DEPENDENCIES = [
+  '@tutorialkit/runtime',
+  '@webcontainer/api',
+  'nanostores',
+  '@nanostores/react',
+  'kleur',
+  'micromatch',
+  '@types/micromatch',
+];
 
 export function ejectRoutes(flags: Arguments) {
   if (flags._[1] === 'help' || flags.help || flags.h) {
@@ -104,6 +112,7 @@ async function _eject(flags: EjectOptions) {
   for (const dep of REQUIRED_DEPENDENCIES) {
     if (!(dep in pkgJson.dependencies) && !(dep in pkgJson.devDependencies)) {
       pkgJson.dependencies[dep] = astroIntegrationPkgJson.dependencies[dep];
+      pkgJson.devDependencies[dep] = astroIntegrationPkgJson.devDependencies[dep];
 
       newDependencies.push(dep);
     }

packages/cli/tests/__snapshots__/create-tutorial.test.ts.snap

@@ -72,6 +72,7 @@ exports[`create a project 1`] = `
   "src/templates/default/package.json",
   "src/templates/default/src",
   "src/templates/default/src/index.js",
+  "src/templates/default/src/template-only-file.js",
   "src/templates/vite-app",
   "src/templates/vite-app-2",
   "src/templates/vite-app-2/.tk-config.json",
@@ -226,6 +227,7 @@ exports[`create and eject a project 1`] = `
   "src/templates/default/package.json",
   "src/templates/default/src",
   "src/templates/default/src/index.js",
+  "src/templates/default/src/template-only-file.js",
   "src/templates/vite-app",
   "src/templates/vite-app-2",
   "src/templates/vite-app-2/.tk-config.json",

packages/runtime/src/store/index.ts

@@ -169,7 +169,14 @@ export class TutorialStore {
         this._lessonFiles = files;
         this._lessonSolution = solution;
 
-        this._editorStore.setDocuments(files);
+        this._editorStore.setDocuments(
+          Object.fromEntries(
+            Object.entries({
+              ...template,
+              ...files,
+            }).filter(([filename]) => lesson.files[1].includes(filename)),
+          ),
+        );
 
         if (lesson.data.focus === undefined) {
           this._editorStore.setSelectedFile(undefined);

packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md

@@ -13,6 +13,7 @@ terminal:
   panels: ['terminal', 'output']
 template:
   name: default
+  visibleFiles: ['/src/template-only-file.js']
 ---
 
 # Kitchen Sink [Heading 1]

packages/template/src/templates/default/src/template-only-file.js

@@ -0,0 +1 @@
+export default 'This file is only present in template';

packages/types/src/schemas/common.spec.ts

@@ -358,6 +358,16 @@ describe('webcontainerSchema', () => {
     }).not.toThrow();
   });
   it('should allow specifying the template by object type', () => {
+    expect(() => {
+      webcontainerSchema.parse({
+        template: {
+          name: 'default',
+          visibleFiles: ['**/fixture.json', '*/tests/*'],
+        },
+      });
+    }).not.toThrow();
+  });
+  it('should allow specifying the template to omit visibleFiles', () => {
     expect(() => {
       webcontainerSchema.parse({
         template: {

packages/types/src/schemas/common.ts

@@ -145,6 +145,9 @@ export const webcontainerSchema = commandsSchema.extend({
     z.strictObject({
       // name of the template
       name: z.string(),
+
+      // list of globs of files that should be visible
+      visibleFiles: z.array(z.string()).optional(),
     }),
   ]),
   terminal: terminalSchema.optional(),