docs(recipes): add publicPath + external/static html file (#87)

matheus1lva · shellscape · commit 7aa36dae4cbd · 2019-01-14T07:57:22.000-05:00
* docs(recipes): add publicPath + external html file

* fix: typo

* refactor: reword

* chore: rename recipe
diff --git a/recipes/README.md b/recipes/README.md
@@ -8,6 +8,7 @@ Recipes are snippets of code and useful tidbits that may be helpful to developer
 [Custom Headers](./custom-headers.md)<br/>
 [Multi Entry Setup](./multi-entry.md)<br/>
 [Proxies](./proxies.md)<br/>
+[Static HTML File](./external-html.md)<br/>
 [Using a Dynamic Port](./dynamic-port.md)<br/>
 [Using an Internal IP Address](./internal-ip.md)<br/>
 [Watching Static Content](./watch-static-content.md)
diff --git a/recipes/static-html-files.md b/recipes/static-html-files.md
@@ -0,0 +1,66 @@
+## Static HTML Files
+
+When setting up an HTML file to bootstrap a Single Page Application users typically choose between two popular options:
+
+1. [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin)
+1. A static HTML file
+
+This recipe addresses setting up a static HTML file, rather than using a plugin to generate an HTML file to serve a bundle.
+
+### Meat and Potatoes
+
+To get started, your `webpack` configuration should be setup and building successfully. Once that's done, you'll need to create an HTML file somewhere in your project directory structure. Be sure to place the file _outside of the `output` directory_. 
+
+Let's use the following directory structure as an example:
+
+```
+/the-app
+  |_ dist
+  |_ js
+    |_ app.js
+  |_ static
+    |_ index.html
+```
+
+Where `/the-app/dist` is the `output` webpack output directory. A configuration for this example setup would then resemble the following:
+
+```js
+const path = require('path');
+const { WebpackPluginServe: Serve } = require('webpack-plugin-serve');
+const outputPath = path.resolve('./dist');
+
+module.exports = {
+  entry: ['./js/app.js', 'webpack-plugin-serve/client'],
+  output: {
+    filename: 'bundle.js'
+    path: outputPath
+  },
+  plugins: [
+    new Serve({
+      static: [outputPath, path.resolve('./static')]
+    })
+  ]
+}
+```
+
+An HTML file for this setup might resemble:
+
+```html
+<!doctype>
+<html>
+  <body>
+    <main></main>
+    <script src="/bundle.js"></script>
+  </body>
+</html>
+```
+
+### 🍰 Dessert
+
+Webpack provides for a multitude of different output configurations, and your needs will likely vary from the examples in this recipe. The important parts to assert are configured correctly are:
+
+- the `static` path(s) for `WebpackPluginServe. Any path(s) specified will be be accessible from the website root.
+- the `output.publicPath` property, which should be set if your build directory is within a directory specified in `static`
+- the `src` property for the `<script>` tag in the static HTML file. This needs to point to where the bundle is located, as defined by all other configuration. In this recipe, we're adding the `outputPath` as a static directory, so the bundle is served from the website root.
+
+
