(WIP) docs: apply twoslash

[serkodev]

Before submitting the PR, please make sure you do the following

• [x] Read the Contributing Guidelines.
• [x] Read the Pull Request Guidelines.
• [x] Check that there isn't already a PR that solves the problem the same way to avoid creating a duplicate.
• [x] Provide a description in this PR that addresses what the PR is solving, or reference the issue that it solves (e.g. fixes #123).
• [x] Ideally, include relevant tests that fail without this PR but pass with it.

---

Description

Related: https://github.com/vueuse/vueuse/discussions/4548#discussioncomment-11997908

This PR applies Twoslash to document of VueUse and still in progress.

• Makes all ts and vue code blocks in the index.md document automatically apply Twoslash.
• Automatically imports vue in all code blocks (silently).
• Some sample code includes vue imports while others do not. Instead of enforcing uniform importing or non-importing, I believe that keeping shorter code snippets import-free can enhance readability. Therefore, I aim to preserve the original code snippets as much as possible.
• I believe some sample code is more like pseudo-code. Although certain null checks or type checks may not pass, they improve readability. As a result, I have enabled Twoslash’s noErrors option by default.

Preview

Progress

Core

Category	Status
State	✅
Elements	✅
Browser	✅
Sensors	✅
Network	✅
Animation	✅
Component	✅
Watch	✅
Reactivity	✅
Array	✅
Time	✅
Utilities	✅

Add-ons

Category	Status
Electron	✅
Firebase	✅
Head	🔗
Integrations	✅
Math	✅
Motion	🔗
Router	✅
RxJS	⚠️
SchemaOrg	🔗
Sound	🔗

Other Pages

Pending ⏳

Additional context

[userquin]

@serkodev You need to change the node max_old_space_size here https://github.com/vueuse/vueuse/blob/main/netlify.toml#L6

Just try with 8192 (the free tier is limited to 6GB), iirc Anthony doesn't have any restriction at Netlifly

[serkodev]

@userquin Oh! Thanks for the reminder. I’m currently researching whether there’s a way to reduce build memory usage (it does require more than 16GB at the moment). So, it’s still uncertain whether this flag will be changed. If I decide to modify it later, I’ll add it to Netlify’s config. 👍

[userquin]

@serkodev don't waste your time, looks like it is a problem with Vue version, check:

• https://github.com/vuejs/vitepress/issues/4242
• https://github.com/shikijs/shiki/issues/796

If we can run the build at Netlify with 16GB it should be fine /cc @antfu

In the meantime you can also try using buildConcurrency: 10 (or even small number, beware, will be slow) at VP config file (by default it is 64) here https://github.com/vueuse/vueuse/blob/main/packages/.vitepress/config.ts#L67:

• https://github.com/vuejs/vitepress/issues/4227#issuecomment-2469892828
• default VP buildConcurrency

[userquin]

@serkodev Maybe you can try with VP 2.0.2.alpha (using Vite 6) in a new local branch from this one (or even using a new clean clone of the branch, no idea if updating to Vite 6 will have some side effect on the build): https://github.com/vuejs/vitepress/releases

(If you don't have time, I can give it a try next Saturday)

[userquin]

we can also try updating the dependency to latest version 2.3.2: https://github.com/vueuse/vueuse/blob/main/pnpm-workspace.yaml#L12

[userquin]

Thx @brc-dd :

You can try enabling the fs cache thing that twoslash added (it might not work though 🫠). Twoslash is rebuilding whole ts graph for each file which is both slow + goes OOM.

[serkodev]

@userquin Thanks for providing this information and saving me a lot of time! 💚 I’ll take a look and see if it fixes the issue.

[serkodev]

I tried the following:

• ✅ Using twoslash’s createFileSystemTypesCache successfully reduced memory usage, bringing it down from 24GB to 12GB.
• ❌ Reducing buildConcurrency didn’t seem to help with memory usage.
• ❌ Updating the following dependencies also didn’t help:

'@shikijs/vitepress-twoslash': ^2.3.2  
vitepress: ^2.0.0-alpha.2  

[serkodev]

I’m not sure if it’s Netlify’s memory limit or build timeout, but after applying twoslash to all code blocks, Netlify encounters an error when running build:docs. 🧐 It can build success if I disable auto apply twoslash.

Failed during stage 'building site': Build script returned non-zero exit code: 2 (https://ntl.fyi/exit-code-2)
ELIFECYCLE  Command failed with exit code 129. (https://ntl.fyi/exit-code-129)

https://app.netlify.com/sites/vueuse/deploys/67a5e6ad2313310008ea2696

[userquin]

can you try updating shikijs and shikijs vitepress to latest versions?

[serkodev]

Updated but seems Netlify still can't build.

[OrbisK]

@serkodev can we support you somehow?

[serkodev]

@serkodev can we support you somehow?

I’m currently still stuck on the issue of not being able to build successfully on Netlify. Since the build works after reducing the number of twoslash code blocks, I believe the issue is caused by twoslash. Recently, I’ve been investigating twoslash to see if there might be any memory leak issues. If possible, I would really appreciate any help in finding other solutions. Thank you very much!

[43081j]

fwiw i have an older macbook pro at the min and i can't run vitepress build

i eventually hit an out of memory error

annoyingly, i can't debug it because it also crashes devtools if you try attach to it and do anything of use...

something in there smells of a memory leak though

[43081j]

@serkodev can you catch up from main and also set this in the vitepress config:

  vite: {
    build: {
      sourcemap: false,
    },
  },

this should solve the problem with slow/out of memory builds

afaik we don't care about sourcemaps for our docs

[43081j]

looks like it still fails 😞

i wonder if its worth trying to put the config in .vitepress/config.ts. it shouldn't make a difference but who knows

will see if i can dig into it a bit more with the e18e folks again some time (they're the ones that found the sourcemaps problem)

[serkodev]

Inside .vitepress/config.ts, the vite: viteConfig is imported from vite.config.ts so it should be the same?

[43081j]

ah i hadn't noticed that. you're right in that case 👍

so we probably solved the memory issue but somehow still not the build... 🤔

[serkodev]

On my device, if there is a memory leak issue during the build process, an error message like below will be displayed.

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

However, since Netlify only shows the error below:

ELIFECYCLE  Command failed with exit code 129

I am unable to confirm whether the issue is same or related to a memory leak.

[43081j]

yep i suspect it is two problems

however, you have solved a huge memory issue by disabling sourcemaps. i've had a few people check out this branch and fail to build it thanks to OOM exceptions. with sourcemaps disabled, it builds successfully

but we still have whatever problem CI is having

[serkodev]

But my situation is the opposite. With max-old-space-size=12288, setting sourcemap: false results in a JavaScript heap out of memory error. However, if I don’t set it, the build succeeds. Anyway, I can make the build succeed by increasing max-old-space-size tho.

On my device, the build has always been successful, but on Netlify it fails unless I reduce the number of Twoslash code blocks.

[43081j]

aha and that is absurd, since of course having sourcemaps results in more memory (we're computing more of something, in general)

no idea why it would be the reverse for you! very strange

there's almost certainly a memory issue here either way. there's no way it should need you to specify memory limits at all. if it doesn't succeed under defaults, we have a problem

[userquin]

can you try with VP ^1.6.3 instead 2 alpha?

[serkodev]

Seems still cannot build on Netlify, seems like the memory usage issue is related to twoslash. I’m thinking about whether it’s possible to build it using GitHub Actions and then upload it to Netlify?

[pkg-pr-new[bot]]

Open in StackBlitz

@vueuse/components

npm i https://pkg.pr.new/@vueuse/components@4560

@vueuse/core

npm i https://pkg.pr.new/@vueuse/core@4560

@vueuse/electron

npm i https://pkg.pr.new/@vueuse/electron@4560

@vueuse/firebase

npm i https://pkg.pr.new/@vueuse/firebase@4560

@vueuse/integrations

npm i https://pkg.pr.new/@vueuse/integrations@4560

@vueuse/math

npm i https://pkg.pr.new/@vueuse/math@4560

@vueuse/metadata

npm i https://pkg.pr.new/@vueuse/metadata@4560

@vueuse/nuxt

npm i https://pkg.pr.new/@vueuse/nuxt@4560

@vueuse/router

npm i https://pkg.pr.new/@vueuse/router@4560

@vueuse/rxjs

npm i https://pkg.pr.new/@vueuse/rxjs@4560

@vueuse/shared

npm i https://pkg.pr.new/@vueuse/shared@4560

commit: 07bb11f

[ilyaliao]

Looks like it works 👀

[serkodev]

Yep, after plenty of trial-and-error, I finally got it building successfully on Netlify! 😭

[serkodev]

Currently I'm working on passing the test:browser test, seems there are some bug related to rolldown. I'm trying to only apply rolldown-vite to vitepress

---

Update: test units passed