docs: add trobleshooting

fi3ework · Jan 15, 2023 · 234695b · 234695b
1 parent 1c1d4b5
commit 234695b
Show file tree

Hide file tree

Showing 6 changed files with 455 additions and 88 deletions.
diff --git a/.gitignore b/.gitignore
@@ -106,4 +106,5 @@ dist
 #
 lib/
 playground-temp/
-packages/runtime/public/build/bundle.js
+packages/runtime/public/build/bundle.js
+docs/.vitepress/cache
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -4,21 +4,17 @@ export default defineConfig({
   lang: 'en-US',
   title: 'vite-plugin-checker',
   description: 'Vite plugin that provide checks of TypeScript, ESLint, vue-tsc, and more.',
-
   lastUpdated: true,
-
   themeConfig: {
+    outline: 'deep',
     sidebar: {
       '/': sidebar(),
     },
-
     editLink: {
       pattern: 'https://github.com/fi3ework/vite-plugin-checker/edit/main/docs/:path',
       text: 'Edit this page on GitHub',
     },
-
     socialLinks: [{ icon: 'github', link: 'https://github.com/fi3ework/vite-plugin-checker' }],
-
     footer: {
       message: 'Released under the MIT License.',
       copyright: 'Copyright fi3ework',
@@ -53,5 +49,10 @@ function sidebar() {
       collapsible: true,
       items: [{ text: 'Shared ', link: '/configuration/config' }],
     },
+    {
+      text: 'FAQs',
+      collapsible: true,
+      items: [{ text: 'Troubleshooting ', link: '/faq/troubleshooting' }],
+    },
   ]
 }
diff --git a/docs/faq/troubleshooting.md b/docs/faq/troubleshooting.md
@@ -0,0 +1,18 @@
+# Troubleshooting
+
+This section lists a few common gotchas, and bugs introduced in the past.
+Please skim through before [opening an issue](https://github.com/fi3ework/vite-plugin-checker/issues/new/choose).
+
+## HMR Issues
+
+### Hot Module Refresh does not work when integrating with backend
+
+When integrating with a [traditional backend](https://vitejs.dev/guide/backend-integration.html#backend-integration), in development mode, you need to inject vite-plugin-checker's runtime manually.
+
+```html
+<!-- if development -->
+<script type="module" src="http://localhost:5173/@vite/client"></script>
+<script type="module" src="http://localhost:5173/main.js"></script>
+<!-- add below for vite-plugin-checker -->
+<script type="module" src="http://localhost:5173/@vite-plugin-checker-runtime-entry"></script>
+```
diff --git a/docs/introduction/getting-started.md b/docs/introduction/getting-started.md
@@ -1,6 +1,6 @@
 # Getting Started
 
-1. Install plugin.
+1. Install plugin (pnpm recommended).
 
    ```bash
    pnpm add vite-plugin-checker -D
@@ -13,10 +13,6 @@
    npm i vite-plugin-checker -D
    ```
 
-::: warning
-If you are using [Vite 3](https://vitejs.dev/blog/announcing-vite3.html), the minimum version of `vite-plugin-checker` must be `^0.4.9`. See more at [#153](https://github.com/fi3ework/vite-plugin-checker/pull/153).
-:::
-
 2. Add plugin to Vite config file. Add the checker you need. We add TypeScript below as an example. See all available checkers [here](/checkers/overview).
 
    ```ts
@@ -28,7 +24,7 @@ If you are using [Vite 3](https://vitejs.dev/blog/announcing-vite3.html), the mi
    ```
 
 ::: tip
-If you'd prefer to not run the checkers during unit testing with vitest, you can alter the config based on that. Example:
+If you'd prefer to not run the checkers during unit testing with Vitest, you can alter the config based on that. Example:
 
 ```ts
 // vite.config.js

diff --git a/docs/package.json b/docs/package.json
@@ -4,7 +4,7 @@
   "dependencies": {
     "@vueuse/core": "^8.9.4",
     "body-scroll-lock": "4.0.0-beta.0",
-    "vitepress": "^1.0.0-alpha.4",
+    "vitepress": "^1.0.0-alpha.36",
     "vue": "^3.2.37"
   }
 }