This article has participated in the “Digitalstar Project” and won a creative gift package to challenge the creative incentive money.

There is an important point in DevOps theory: when working in complex systems, it is impossible to predict all the outcomes.

So mistakes or flaws are inevitable, and we need to look at mistakes as opportunities, opportunities for learning and self-improvement. When we understand mistakes well, we can avoid the next, more serious mistake.

Vue DevUI is a Vue3 version of the DevUI component library, based on Ng DevUI.

Vue DevUI is developed using the latest technology stack:

  • useViteFoundation Works (Vue DevUI Open Source Guide 04: Build a Vue3 component library for TypeScript/JSX using Vite)
  • useVitePressSetting up a document system (Vue DevUI Open Source Guide 05: Add VitePress documentation system to Vue3 component library)
  • useVue3+TypeScript+JSXComponent development (Vue DevUI Open Source Guide 03: How to add expansion/collapse to tree components)
  • useJest+@vue/test-utilsUnit testing
  • useeslint/stylelint/ls-lintConduct code specification checks

During the development of Vue DevUI, we encountered a number of problems:

  1. Some are our contributor issues
  2. Some of the problems I discovered during the live broadcast with the village chief
  3. Others are related to the VitePress documentation system

Here is a list of questions to be shared in this article:

  • 8.16 Problems caused by using custom commands in VitePress
  • 9.18 Document launch white pages issue caused by defineEmit
  • 10.3 Vitepress SSR building problems caused by Using Window browser variables

Problem 1: Problems caused by the use of custom instructions in Vitepress

Problem background and description

The first issue dates back to August 16, when wailen, an early contributor to Vue Devui, proposed I45VB6, just over a week after vue Devui’s documentation system switched to VitePress.

The following is the issue wailen mentioned:

Yarn build error (Loading component error)

This error could easily have been repeated by executing the YARN Build document build command:

The following error message is displayed:

SyntaxError: Custom directive is missing corresponding SSR transform and will be ignored.
Copy the code

Here’s a screenshot of Wailen at the time:

However, at that time, the Vue Devui project just started to be active, and everyone was busy submitting PR, submitting issue, reviewing and incorporating code, so they didn’t pay much attention to this issue. Moreover, our website was not accessed by domain name at that time, so we didn’t need to deploy the actual host, so we didn’t need to execute YARN Build to build the production package. So they didn’t pay attention to it.

Problem analysis

A syntax error occurred during vitePress construction, which led to the construction failure, indicating that the custom command lacked the converter for server rendering:

SyntaxError: Custom directive is missing corresponding SSR transform and will be ignored.
Copy the code

Fortunately, the error message locates the specific file:

file: D:/code/vue-devui/sites/components/loading/index.md:124:3
Copy the code

This file is the MD file of the Loading component. Here are the things that cause build errors:

<div
  v-dLoading="promises.value"
  :backdrop="true"
  message="One moment please..."
  style="margin-top: 20px; width: 100%; height: 80px; padding: 10px;"
>loading will show here2</div>
Copy the code

It can be seen that this only uses a v-dloading custom instruction, while the construction method used by Vitepress document is SSR server rendering. There is no corresponding transform converter to parse this vue custom instruction in the SSR process, so the construction document reported an error.

The solution

If you know the cause of the problem, you can solve it easily.

  • One solution is to write the corresponding transform for this custom instruction
  • Another solution is to install patch-VUE-directive-SSR patches

We choose the second option:

yarn add -D patch-vue-directive-ssr
Copy the code

Patch-vue-directive-ssr patch pack is designed to patch @vue/ Compiler-SSR to build VUE custom instructions using SSR/SSG.

Problem 2: Document launch white pages caused by defineEmit

Problem background and description

This problem was first discovered on The night of the live broadcast with the village head at STATION B on September 18. The following is the recording address of the live broadcast:

Vue DevUI Open Source Guide 01: Submit my first PR

This problem occurs when the yarn dev command is executed to start the component library file. After the yarn dev command is executed, enter http://localhost:3000/ in the address box of the browser to access the file. A white page is displayed.

Problem analysis

Open the browser console and find a red error, indicating a syntax error:

Uncaught SyntaxError: The requested module '/vue-devui/node_modules/.vite/vue.js' does not provide an export named 'defineEmit'
Copy the code

Fortunately, this error locates a specific file:

/vue-devui/sites/.vitepress/devui-theme/components/NavBar.vue
Copy the code

This file imports the defineEmit method from vue:

<script setup lang="ts">
import { defineEmit } from 'vue'
import NavBarTitle from './NavBarTitle.vue'
import NavLinks from './NavLinks.vue'
import ToggleSideBarButton from './ToggleSideBarButton.vue'

defineEmit(['toggle'])
</script>
Copy the code

This is where the error occurred.

Coincidentally, we upgraded the vue version of Vue Devui to [email protected] that night. Since 3.1.5, some of the Vue apis have changed, such as defineEmit -> defineEmits here.

The solution

Knowing the reason, the answer comes out in a puff.

Just change defineEmit to defineEmits.

The following is the PR proposed by HZTTW who was the fastest in the studio at that time:

Resolve the startup error

Problem 3: Vitepress SSR building problems caused by using browser variables such as Window /document

Problem background and description

This is also a very typical problem, first discovered during the National Day, when I planned to deploy the website of Vue Devui to the domain name, but I did not want to buy cloud host, so I planned to wager code cloud: deploy to the gitee. IO domain name.

The yarn build command has not been executed for so long. The yarn build command has not been executed for so long.

SyntaxError: Custom directive is missing corresponding SSR transform and will be ignored.
Copy the code

This problem can be solved easily by installing patch- vue-directive-SSR:

yarn add -D patch-vue-directive-ssr
Copy the code

I4D06D: I4D06D:

ReferenceError: window is not defined
Copy the code

Problem analysis

Unfortunately, this error does not locate a specific file.

The following are the details of the error:

✓ Building Client + Server bundles... ✖ rendering pages... build error: ReferenceError: window is not defined at /vue-devui-theme/node_modules/vitepress/dist/client/app/temp/app.js:932:3 at Module.<anonymous>  (/vue-devui-theme/node_modules/vitepress/dist/client/app/temp/app.js:937:2) at Module._compile (internal/modules/cjs/loader.js:999:30) at Module._extensions.. js (internal/modules/cjs/loader.js:1027:10) at extensions.. js (/vue-devui-theme/node_modules/esbuild-register/dist/node.js:2696:24) at Object.newLoader [as .js] (/vue-devui-theme/node_modules/esbuild-register/dist/node.js:2262:9) at Module.load (internal/modules/cjs/loader.js:863:32) at Function.Module._load (internal/modules/cjs/loader.js:708:14) at Module.require (internal/modules/cjs/loader.js:887:19) at require (internal/modules/cjs/helpers.js:74:18) error Command failed with exit code 1. info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.Copy the code

Error: Error: error: error: error: error

[vite:vue] Custom directive is missing corresponding SSR transform and will be ignored. file: / Users/kagol/Documents/kagol/code/vue - devui - theme/sites/components/loading/index, md: 124:3 ✖ building client + server bundles... build error: SyntaxError: Custom directive is missing corresponding SSR transform and will be ignored. at Object.createCompilerError (/Users/kagol/Documents/Kagol/code/vue-devui-theme/node_modules/@vue/compiler-core/dist/compiler-core.cjs.js:19:19) ...Copy the code

There are some differences. The error occurred in the Build Bundles phase, and now this build Bundles error is successful:

✓ building client + server bundles...
Copy the code

But the Render Pages phase failed:

✖ rendering pages...
Copy the code

This involves the knowledge of SSR construction of Vitepress.

By reading the Vitepress source code, we know that when we execute the VitePress build docs command, the build process is actually divided into two steps:

  1. callbundleMethod, usingviteforssrBuild, that is, in the build logbuilding client + server bundles...
  2. callrenderPageMethod, usingvue routertherouter.go(routePath)Render the page, which is in the build logrendering pages...

But when rendering the page, VitePress doesn’t know which file is wrong, so it can’t give detailed prompts to locate specific files.

This is where the intuition of an experienced programmer comes in.

The window variable does not exist because it is rendered on the server side, and there is no browser environment, just a nodeJS environment.

ReferenceError: window is not defined
Copy the code

But which file is causing the error?

Try a global search for the keyword window. There are 20 files that contain window:

Add the dot window. To narrow it down, there are 17 files that contain window.

By slowly analyzing each file, you can solve this problem.

The solution

This thorny problem was finally solved by Zcating.

Fix (build): Fixes problems with vitePress packaging

Zcating is a core member of devUI open source organization. He has been very active since last year when Ng Devui just started open source, and he has contributed 6 articles on RxJS principle analysis to our nuggets column. The first component of Vue DevUI component library, Button, is contributed by Zcating.

In addition to Button component, Zcating is also the owner of Modal/Overlay and other components. He not only frequently and actively examines codes, but also undertakes the design and development of Table, the most complex component of Vue DevUI.

Zcating is also running a public account: ZCX studio, welcome to pay attention to it

The main solutions include:

  1. defineinBrowserMethod that returns ahead of time where browser variables such as window are used
  2. Move code that contains browser variables such as window toonMountedLife cycle events

Interested partners can look at Zcating’s PR:

Fix (build): Fixes problems with vitePress packaging

Welcome to build DevUI open source project together

Our DevUI team has a number of open source projects, now we are recruiting contributor, welcome everyone to participate in open source! (If you are interested in DevUI, you can add devui-Official to our core development group.)

  • Ng DevUI: github.com/DevCloudFE/…
  • Vue DevUI: gitee.com/devui/vue-d…
  • DevUI Admin github.com/DevCloudFE/…

DevUI official website: Devui.design /

Also welcome to follow me and the village head “Vue DevUI Open Source Guide” series live!

The Vue DevUI Open Source Guide series is going to be split into two streams:

  1. Component design and implementation
  2. Component library engineering

So far [Component Design and Implementation] has completed 3 phases (not yet finished) :

  1. Vue DevUI Open Source Guide 01: Submit my first PR
  2. [I want to do open source] Vue DevUI open source guide 02: make a respectable Tree component
  3. Vue DevUI open Source Guide 03: Learn to “single test” will have a sense of security! Complete the Tree component!

[Component library Engineering] Has completed phase 2 (in progress) :

  1. Vue DevUI Open source guide 04: component library engineering construction project initialization, JSX support
  2. [I want to do open source] Vue DevUI open source guide 05: Open source component library document construction, VitePress in the process of using the pit experience, overcome these difficulties you will gain a lot!
  3. Vue DevUI Open Source Guide 06: Take you hand in hand to develop a scaffolding

Have reached a consensus with the village head teacherAs long as the village head teacher’s live broadcast room does not fall, as long as there are partners willing to participate in, this series will continue to do!

Let’s make a vuE3 open source component library from 0 to 1!

Every Friday night at 9 o ‘clock, we are in the village chief’s broadcast room, be there or be square!

Address of village head direct broadcast room