From 9b32276983730d7b87902ea9864552f63745fc42 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Mon, 15 Feb 2021 13:24:06 -0500 Subject: [PATCH] server plugin docs --- packages/cli/src/lib/server-interface.js | 7 +- .../src/plugins/server/plugin-livereload.js | 15 ++--- www/pages/plugins/index.md | 7 +- www/pages/plugins/resource.md | 2 +- www/pages/plugins/server.md | 64 +++++++++++++++++++ 5 files changed, 82 insertions(+), 13 deletions(-) create mode 100644 www/pages/plugins/server.md diff --git a/packages/cli/src/lib/server-interface.js b/packages/cli/src/lib/server-interface.js index 36019d567..aeaed6d7e 100644 --- a/packages/cli/src/lib/server-interface.js +++ b/packages/cli/src/lib/server-interface.js @@ -3,13 +3,16 @@ class ServerInterface { this.compilation = compilation; this.options = options; } + async start() { - return Promise.resolve(false); + return Promise.resolve(true); } + async stop() { - return Promise.resolve(false); + return Promise.resolve(true); } } + module.exports = { ServerInterface }; \ No newline at end of file diff --git a/packages/cli/src/plugins/server/plugin-livereload.js b/packages/cli/src/plugins/server/plugin-livereload.js index 102708f74..984d72c9b 100644 --- a/packages/cli/src/plugins/server/plugin-livereload.js +++ b/packages/cli/src/plugins/server/plugin-livereload.js @@ -6,21 +6,20 @@ const { ServerInterface } = require('../../lib/server-interface'); class LiveReloadServer extends ServerInterface { constructor(compilation, options = {}) { super(compilation, options); - } - async start() { this.liveReloadServer = livereload.createServer({ exts: ['html', 'css', 'js', 'md'], applyCSSLive: false // https://github.com/napcs/node-livereload/issues/33#issuecomment-693707006 }); - this.liveReloadServer.watch(this.compilation.context.userWorkspace, () => { - console.info(`Now watching directory "${this.compilation.context.userWorkspace}" for changes.`); - }); - return Promise.resolve(true); } - async stop() { - return Promise.resolve(false); + async start() { + const { userWorkspace } = this.compilation.context; + + this.liveReloadServer.watch(userWorkspace, () => { + console.info(`Now watching directory "${userWorkspace}" for changes.`); + return Promise.resolve(true); + }); } } diff --git a/www/pages/plugins/index.md b/www/pages/plugins/index.md index 9d6d5e0d9..1cdb7e6d1 100644 --- a/www/pages/plugins/index.md +++ b/www/pages/plugins/index.md @@ -24,7 +24,7 @@ Greenwood aims to cater to these use cases through two approaches: ### API Each plugin must return a function that has the following three properties:. - `name`: A string to give your plugin a name and used for error handling and troubleshooting. -- `type`: A string to specify to Greenwood the type of plugin. Right now the current supported plugin type `'resource'` +- `type`: A string to specify to Greenwood the type of plugin. Right now the current supported plugin type [`'resource'`](/plugins/resource/) and [`'plugin'`](/plugins/server/). - `provider`: A function that will be invoked by Greenwood that Can accept a `compilation` param that provides read-only access to parts of Greenwood's state and configuration that can be used by a plugin. Here is an example of creating a plugin in a _greenwood.config.js_. @@ -106,4 +106,7 @@ module.exports = { While each API has its own documentation section on the left sidebar of this page, here is a quick overview of the current set of Plugin APIs Greenwood supports. #### Resource Plugins -Resource plugins allow users to interact with the request and response lifecycles of files at a variety of different ways. These lifecycles provide the ability to do things like introduce new file types, to adding hosted 3rd party scripts to your site. \ No newline at end of file +[Resource plugins](/plugins/resource/) allow users to interact with the request and response lifecycles of files at a variety of different ways. These lifecycles provide the ability to do things like introduce new file types, to adding hosted 3rd party scripts to your site. + +#### Server Plugins +[Server plugins](/plugins/server/) allow developers to start and stop custom servers as part of the **serve** lifecycle of Greenwood. These lifecycles provide the ability to do things like start a GraphQL server, or reverse proy requests to a custom server. \ No newline at end of file diff --git a/www/pages/plugins/resource.md b/www/pages/plugins/resource.md index 74650e4e8..6ec2ee981 100644 --- a/www/pages/plugins/resource.md +++ b/www/pages/plugins/resource.md @@ -12,7 +12,7 @@ Resource plugins allow developers to interact with the request and response life - Introduce additional file types, like TypeScript ### API (Resource Interface) -Although JavaScript is loosely typed, a [resource "interface"](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/cli/src/lib/resource-interface.js) has been provided by Greenwood that you can use to start building our own resource plugins. Effectively you have to define two things: +Although JavaScript is loosely typed, a [resource "interface"](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/cli/src/lib/resource-interface.js) has been provided by Greenwood that you can use to start building your own resource plugins. Effectively you have to define two things: - `extensions`: The file types your plugin will operate on - `contentType`: A browser compatible contentType to ensure browsers correctly interpret you transformations diff --git a/www/pages/plugins/server.md b/www/pages/plugins/server.md new file mode 100644 index 000000000..d8e29108f --- /dev/null +++ b/www/pages/plugins/server.md @@ -0,0 +1,64 @@ +--- +label: 'Server' +menu: side +title: 'Server' +index: 3 +--- + +## Server + +Server plugins allow developers to start and stop custom servers as part of the serve lifecycle of Greenwood. These lifecycles provide the ability to do things like: +- Start a live reload server (like Greenwood does by default) +- Starting a GraphQL server +- Reverse proxy to help route external requests + +### API (Server Interface) +Although JavaScript is loosely typed, a [server "interface"](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/cli/src/lib/server-interface.js) has been provided by Greenwood that you can use to start building your own server plugins. Effectively you just have to provide two methods +- `start` - function to run to start your server +- `stop` - function to run to stop / teaddown your server + + +They can be used in a _greenwood.config.js_ just like any other plugin type. +```javascript +const pluginMyServerFoo = require('./plugin-my-server'); + +module.exports = { + + ... + + plugins: [ + pluginMyServer() + ] + +} +``` + +## Example +The below is an excerpt of [Greenwood's internal LiveReload server](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/cli/src/plugins/server/plugin-livereload.js) plugin. + +```javascript +class LiveReloadServer extends ServerInterface { + constructor(compilation, options = {}) { + super(compilation, options); + + this.liveReloadServer = livereload.createServer({ /* options */}); + } + + async start() { + const { userWorkspace } = this.compilation.context; + + return this.liveReloadServer.watch(userWorkspace, () => { + console.info(`Now watching directory "${userWorkspace}" for changes.`); + return Promise.resolve(true); + }); + } +} + +module.exports = (options = {}) => { + return { + type: 'server', + name: 'plugin-livereload', + provider: (compilation) => new LiveReloadServer(compilation, options) + } +}; +``` \ No newline at end of file