feat: add serve command (#136)

Author: kiaking

bin/vitepress.js

@@ -31,6 +31,13 @@ if (!command || command === 'dev') {
       console.error(chalk.red(`build error:\n`), err)
       process.exit(1)
     })
+} else if (command === 'serve') {
+  require('../dist/node')
+    .serve(argv)
+    .catch((err) => {
+      console.error(chalk.red(`failed to start server. error:\n`), err)
+      process.exit(1)
+    })
 } else {
   console.log(chalk.red(`unknown command "${command}".`))
   process.exit(1)

docs/.vitepress/config.js

@@ -25,7 +25,8 @@ module.exports = {
             { text: 'What is VitePress?', link: '/' },
             { text: 'Getting Started', link: '/guide/getting-started' },
             { text: 'Configuration', link: '/guide/configuration' },
-            { text: 'Customization', link: '/guide/customization' }
+            { text: 'Customization', link: '/guide/customization' },
+            { text: 'Deploying', link: '/guide/deploy' }
           ]
         }
       ],

docs/guide/deploy.md

@@ -0,0 +1,49 @@
+# Deploying
+
+The following guides are based on some shared assumptions:
+
+- You are placing your docs inside the `docs` directory of your project;
+- You are using the default build output location (`.vitepress/dist`);
+- VuePress is installed as a local dependency in your project, and you have setup the following npm scripts:
+
+```json
+{
+  "scripts": {
+    "docs:build": "vuepress build docs",
+    "docs:serve": "vuepress serve docs"
+  }
+}
+```
+
+## Building The Docs
+
+You may run `yarn docs:build` command to build the docs.
+
+```bash
+$ yarn docs:build
+```
+
+By default, the build output will be placed at `.vitepress/dist`. You may deploy this `dist` folder to any of your preferred platforms.
+
+### Testing The Docs Locally
+
+Once you've built the docs, you may test them locally by running `yarn docs:serve` command.
+
+```bash
+$ yarn docs:build
+$ yarn docs:serve
+```
+
+The `serve` command will boot up local static web server that serves the files from `.vitepress/dist` at http://localhost:3000. It's an easy way to check if the production build looks OK in your local environment.
+
+You may configure the port of the server py passing `--port` flag as an argument.
+
+```json
+{
+  "scripts": {
+    "docs:serve": "vuepress serve docs --port 8080"
+  }
+}
+```
+
+Now the `docs:serve` method will launch the server at http://localhost:8080.

docs/guide/getting-started.md

@@ -32,7 +32,8 @@ This section will help you build a basic VuePress documentation site from ground
   {
     "scripts": {
       "docs:dev": "vitepress dev docs",
-      "docs:build": "vitepress build docs"
+      "docs:build": "vitepress build docs",
+      "docs:serve": "vitepress serve docs"
     }
   }
   ```
@@ -44,3 +45,7 @@ This section will help you build a basic VuePress documentation site from ground
   ```
 
   VitePress will start a hot-reloading development server at http://localhost:3000.
+
+By now, you should have a basic but functional VuePress documentation site.
+
+When your documentation site starts to take shape, be sure to read the [deployment guide](./deploy).

package.json

@@ -22,13 +22,14 @@
     "dev-watch": "node scripts/watchAndCopy",
     "build": "rimraf -rf dist && node scripts/copyShared && tsc -p src/client && tsc -p src/node && node scripts/copyClient",
     "lint": "yarn lint:js && yarn lint:ts",
-    "lint:js": "prettier --check --write \"{bin,scripts,src}/**/*.js\"",
-    "lint:ts": "prettier --check --write --parser typescript \"{src,types}/**/*.ts\"",
+    "lint:js": "prettier --check --write \"{bin,docs,scripts,src}/**/*.js\"",
+    "lint:ts": "prettier --check --write --parser typescript \"{src,docs,types}/**/*.ts\"",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
     "release": "bash scripts/release.sh",
     "docs": "run-p dev docs-dev",
     "docs-dev": "node ./bin/vitepress dev docs",
-    "docs-build": "yarn build && node ./bin/vitepress build docs"
+    "docs-build": "yarn build && node ./bin/vitepress build docs",
+    "docs-serve": "yarn docs-build && node ./bin/vitepress serve --root docs"
   },
   "engines": {
     "node": ">=10.0.0"
@@ -85,12 +86,16 @@
   },
   "devDependencies": {
     "@types/fs-extra": "^9.0.1",
+    "@types/koa": "^2.11.6",
+    "@types/koa-static": "^4.0.1",
     "@types/lru-cache": "^5.1.0",
     "@types/markdown-it": "^10.0.2",
     "@types/node": "^13.13.4",
     "@types/postcss-load-config": "^2.0.1",
     "chokidar": "^3.4.2",
     "conventional-changelog-cli": "^2.1.0",
+    "koa": "^2.13.0",
+    "koa-static": "^5.0.0",
     "lint-staged": "^10.3.0",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.0.5",

src/node/index.ts

@@ -1,3 +1,4 @@
 export * from './server'
 export * from './build/build'
+export * from './serve/serve'
 export * from './config'

src/node/serve/serve.ts

@@ -0,0 +1,21 @@
+import Koa from 'koa'
+import koaServe from 'koa-static'
+import { resolveConfig } from '../config'
+
+export interface ServeOptions {
+  root?: string
+  port?: number
+}
+
+export async function serve(options: ServeOptions = {}) {
+  const port = options.port !== undefined ? options.port : 3000
+  const site = await resolveConfig(options.root)
+
+  const app = new Koa()
+
+  app.use(koaServe(site.outDir))
+
+  app.listen(port)
+
+  console.log(`listening at http://localhost:${port}`)
+}

yarn.lock

@@ -209,7 +209,22 @@
   dependencies:
     "@types/koa" "*"
 
-"@types/koa@*", "@types/koa@^2.11.4":
+"@types/koa-send@*":
+  version "4.1.2"
+  resolved "https://registry.yarnpkg.com/@types/koa-send/-/koa-send-4.1.2.tgz#978f8267ad116d12ac6a18fecd8f34c5657e09ad"
+  integrity sha512-rfqKIv9bFds39Jxvsp8o3YJLnEQVPVriYA14AuO2OY65IHh/4UX4U/iMs5L0wATpcRmm1bbe0BNk23TRwx3VQQ==
+  dependencies:
+    "@types/koa" "*"
+
+"@types/koa-static@^4.0.1":
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/@types/koa-static/-/koa-static-4.0.1.tgz#b740d80a549b0a0a7a3b38918daecde88a7a50ec"
+  integrity sha512-SSpct5fEcAeRkBHa3RiwCIRfDHcD1cZRhwRF///ZfvRt8KhoqRrhK6wpDlYPk/vWHVFE9hPGqh68bhzsHkir4w==
+  dependencies:
+    "@types/koa" "*"
+    "@types/koa-send" "*"
+
+"@types/koa@*", "@types/koa@^2.11.4", "@types/koa@^2.11.6":
   version "2.11.6"
   resolved "https://registry.yarnpkg.com/@types/koa/-/koa-2.11.6.tgz#b7030caa6b44af801c2aea13ba77d74aff7484d5"
   integrity sha512-BhyrMj06eQkk04C97fovEDQMpLpd2IxCB4ecitaXwOKGq78Wi2tooaDOWOFGajPk8IkQOAtMppApgSVkYe1F/A==