stackblitz / tutorialkit

TutorialKit by StackBlitz - Create interactive tutorials powered by the WebContainer API
https://tutorialkit.dev
MIT License
503 stars 48 forks source link

Compatibility with Starlight #411

Open dagilleland opened 1 week ago

dagilleland commented 1 week ago

Is your feature request related to a problem?

If I create a new TutorialKit project, since it is based on Astro, I would expect to use other Astro plugins such as Starlight. But it doesn't work out-of-the-box.

Tutorial Kit solves part of the problem in helping developers learn, but it would be best if it can be combined with other aspects, such as documentation (which Starlight excels at).

Describe the solution you'd like.

I would like to scaffold a new project with these simple commands:

pnpm create tutorial

followed by

pnpm astro add starlight

Describe alternatives you've considered.

The only alternative I see is to "roll my own" or to figure out what intermediate manual "prep" I would need to do with the Tutorial Kit project once it's scaffolded. It might be simple, such as a tweak to the astro.config.ts generated through Tutorial Kit's create-tutorial project. Or it could be more....

Additional context

When I attempt to scaffold the project, I get the following error related to 'plugins' of astro.config.ts:

4:24:34 a.m. [vite] Error when evaluating SSR module D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\astro.config.ts:
|- TypeError: Cannot destructure property 'plugins' of 'undefined' as it is undefined.
    at Module.StarlightIntegration [as default] (D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\node_modules\.pnpm\@astrojs+starlight@0.29.0_astro@4.16.9_@types+node@20.17.6_rollup@4.24.4_typescript@5.6.3_\node_modules\@astrojs\starlight\index.ts:31:2)
    at D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\astro.config.ts:10:33
    at async instantiateModule (file:///D:/GH/Programming-0101/SkunkWorks-DG/omni-kit/node_modules/.pnpm/vite@5.4.10_@types+node@20.17.6/node_modules/vite/dist/node/chunks/dep-BWSbWtLw.js:52972:5)

[astro] Unable to load your Astro config

Cannot destructure property 'plugins' of 'undefined' as it is undefined.
  Stack trace:
    at Module.StarlightIntegration [as default] (D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\node_modules\.pnpm\@astrojs+starlight@0.29.0_astro@4.16.9_@types+node@20.17.6_rollup@4.24.4_typescript@5.6.3_\node_modules\@astrojs\starlight\index.ts:31:2)
    at async instantiateModule (file:///D:/GH/Programming-0101/SkunkWorks-DG/omni-kit/node_modules/.pnpm/vite@5.4.10_@types+node@20.17.6/node_modules/vite/dist/node/chunks/dep-BWSbWtLw.js:52972:5)
 ELIFECYCLE  Command failed with exit code 1.

Here's the full console output:

┌   @tutorialkit/cli 
│
◇  What's the name of your tutorial?
│  omni-kit
│
●  We'll call your tutorial omni-kit
│
◇  Where should we create your new tutorial?
│  ./omni-kit
│
●  Scaffolding tutorial in D:\GH\Programming-0101\SkunkWorks-DG\omni-kit
│
◇  What package manager should we use?
│  pnpm
│
◇  Initialize a new git repository?
│  Yes
│
◇  Git repository initialized
│
◇  Install dependencies and start project?
│  Yes
│
◆  Tutorial successfully created!
│
└  Please wait while we install the dependencies and start your project...

Lockfile is up to date, resolution step is skipped
Packages: +641
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

   ╭──────────────────────────────────────────────────────────────────╮
   │                                                                  │
   │                Update available! 9.10.0 → 9.12.3.                │
   │   Changelog: https://github.com/pnpm/pnpm/releases/tag/v9.12.3   │
   │                Run "pnpm self-update" to update.                 │
   │                                                                  │
   │         Follow @pnpmjs for updates: https://x.com/pnpmjs         │
   │                                                                  │
   ╰──────────────────────────────────────────────────────────────────╯

Progress: resolved 641, reused 600, downloaded 41, added 641, done

dependencies:
+ @tutorialkit/react 1.2.1
+ react 18.3.1
+ react-dom 18.3.1

devDependencies:
+ @astrojs/check 0.7.0
+ @astrojs/react 3.6.2
+ @tutorialkit/astro 1.2.1
+ @tutorialkit/theme 1.2.1
+ @tutorialkit/types 1.2.1
+ @types/node 20.17.6
+ @types/react 18.3.12
+ astro 4.16.9
+ prettier-plugin-astro 0.14.1
+ typescript 5.6.3

Done in 16.7s

> omni-kit@0.0.1 dev D:\GH\Programming-0101\SkunkWorks-DG\omni-kit
> astro dev

04:22:25 [types] Generated 3ms
04:22:26 [@tutorialkit/astro] Generated 1-basics-1-introduction-1-welcome-files.json 102ms
04:22:26 [@tutorialkit/astro] Generated 1-basics-1-introduction-1-welcome-solution.json 101ms
04:22:26 [@tutorialkit/astro] Generated template-default.json 111ms

 astro  v4.16.9 ready in 3737 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

04:22:27 watching for file changes...
q
PS D:\GH\Programming-0101\SkunkWorks-DG> cd omni-kit
PS D:\GH\Programming-0101\SkunkWorks-DG\omni-kit> pnpm astro add starlight

> omni-kit@0.0.1 astro D:\GH\Programming-0101\SkunkWorks-DG\omni-kit
> astro "add" "starlight"

✔ Resolving packages...

  Astro will run the following command:
  If you skip this step, you can always run it yourself later

 ╭──────────────────────────────────────╮
 │ pnpm add @astrojs/starlight@^0.29.0  │
 ╰──────────────────────────────────────╯

√ Continue? ... yes
✔ Installing dependencies...

  Astro will make the following changes to your config file:

 ╭ astro.config.ts ───────────────────────────────╮
 │ import tutorialkit from '@tutorialkit/astro';  │
 │ import { defineConfig } from 'astro/config';   │
 │                                                │
 │ import starlight from '@astrojs/starlight';    │
 │                                                │
 │ export default defineConfig({                  │
 │   devToolbar: {                                │
 │     enabled: false,                            │
 │   },                                           │
 │   integrations: [tutorialkit(), starlight()],  │
 │ });                                            │
 ╰────────────────────────────────────────────────╯

√ Continue? ... yes

   success  Added the following integration to your project:
  - @astrojs/starlight

D:\GH\Programming-0101\SkunkWorks-DG\omni-kit>HEXT:;.JS;=;
'HEXT:' is not recognized as an internal or external command,
operable program or batch file.

D:\GH\Programming-0101\SkunkWorks-DG\omni-kit>node  "D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\node_modules\.bin\\..\astro\astro.js" "add" "starlight"      
4:24:34 a.m. [vite] Error when evaluating SSR module D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\astro.config.ts:
|- TypeError: Cannot destructure property 'plugins' of 'undefined' as it is undefined.
    at Module.StarlightIntegration [as default] (D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\node_modules\.pnpm\@astrojs+starlight@0.29.0_astro@4.16.9_@types+node@20.17.6_rollup@4.24.4_typescript@5.6.3_\node_modules\@astrojs\starlight\index.ts:31:2)
    at D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\astro.config.ts:10:33
    at async instantiateModule (file:///D:/GH/Programming-0101/SkunkWorks-DG/omni-kit/node_modules/.pnpm/vite@5.4.10_@types+node@20.17.6/node_modules/vite/dist/node/chunks/dep-BWSbWtLw.js:52972:5)

[astro] Unable to load your Astro config

Cannot destructure property 'plugins' of 'undefined' as it is undefined.
  Stack trace:
    at Module.StarlightIntegration [as default] (D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\node_modules\.pnpm\@astrojs+starlight@0.29.0_astro@4.16.9_@types+node@20.17.6_rollup@4.24.4_typescript@5.6.3_\node_modules\@astrojs\starlight\index.ts:31:2)
    at async instantiateModule (file:///D:/GH/Programming-0101/SkunkWorks-DG/omni-kit/node_modules/.pnpm/vite@5.4.10_@types+node@20.17.6/node_modules/vite/dist/node/chunks/dep-BWSbWtLw.js:52972:5)
 ELIFECYCLE  Command failed with exit code 1.
AriPerkkio commented 1 week ago

|- TypeError: Cannot destructure property 'plugins' of 'undefined' as it is undefined. at Module.StarlightIntegration [as default] (D:\GH\Programming-0101\SkunkWorks-DG\omni-kit\node_modules.pnpm\@astrojs+starlight@0.29.0astro@4.16.9@types+node@20.17.6_rollup@4.24.4typescript@5.6.3\node_modules\@astrojs\starlight\index.ts:31:2)

This error is coming from Starlight: https://github.com/withastro/starlight/blob/83d4507e1a385226879bd64147e4e09fef5f79a2/packages/starlight/index.ts#L30-L33

You'll need to add object as argument:

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

https://starlight.astro.build/manual-setup/