Document the build system

Author: marshallswain

docs/2.0-major-release.md

@@ -4,63 +4,9 @@ The biggest change in Feathers-Vuex 2.0 is that it has been refactored with Type
 
 Your project does NOT require to be written in TypeScript.  The `dist` is compiled to ES6.
 
-## Trying it out
+## Fixing the build for older Vue-CLI Apps
 
-I accidentally published `[email protected]` with a `pre` tag on npm, **you have to install the specific version number to get the latest code.**  To find out which is the most-recently published version, run `npm view feathers-vuex` and look at the `pre` tag.  You can ignore the `next` and `pegasus` tags.  Those were accidents that happened because I publish a lot of packages.  :)
-
-To try the latest code.
-
-```console
-npm view feathers-vuex
-```
-
-The end of the output looks something like this:
-
-```console
-dist-tags:
-latest: 1.7.0         next: 1.7.0-pre.37    pegasus: 1.7.0-pre.1  pre: 2.0.0-pre.54
-```
-
-Now use the latest `pre` tag:
-
-```console
-npm i [email protected]
-
-# or with yarn
-yarn add [email protected]
-```
-
-## My TypeScript experience
-
-Initially, I wasn't a fan of TypeScript.  I'm turned off by the steeper learning curve it introduces to writing code.
-
-What I do like is the tooling.  It's like having an assistant that alerts you to stupid moves before you have to accidentally discover them yourself.  I'm only able to appreciate it for one reason: you can use directives to tell it to ignore lines or files, similar to ESLint. The tooling will then shut up and let me write JavaScript.  TypeScript has been quite beneficial to allowing me to better see how to refactor and get rid of a huge monkey patch.  It's down to a few lines of code, now.
-
-I imagine I will like TypeScript more when there's first-class support for it built into Vue.  I imagine how powerful it will be in an entire Vue project.  It's one of the reasons that I'm REALLY excited about the new VueJS 3.0 API (The new function-based syntax is way more exciting, though. It's going to let me write some really pretty, well-organized code :)
-
-But that's enough about TypeScript.
-
-## Where I need assistance: the build
-
-The build system has been my only frustration with switching to TypeScript.  Transpiling from TypeScript to JavaScript only to be transpiled by Babel (or whichever) into another form of JavaScript... has proven to be frustrating.  I could really use some help in this area.
-
-My original intent was to target the build to ES5.  But there are some weird errors that show up when classes get transpiled into old Javascript code.  Classes don't quite behave the same after transpiling.  Things were so inconsistent that I couldn't write down any useful notes to tell you what I was experiencing.  The only clarity I got out of the experience was that it was frustrating.  ;)
-
-I found that the simplest way around my frustration was to target ES6.  I found next that Vue's default build assumes packages in the `node_modules` folder to be compiled to ES5.  So you'll run into this error:
-
-```text
-TypeError : Class constructor BaseModel cannot be invoked without 'new'
-```
-
-This error was fixed by adding `feathers-vuex` to the `transpileDependencies` in the `vue.config.js` file:
-
-```js
-module.exports = {
-  transpileDependencies: ['feathers-vuex']
-}
-```
-
-It felt like everything was solved until I ran the production build.  There were more errors.  I finally copied the `feathers-vuex` folder from `node_modules` into a `src/libs` folder in my project.  Voila!  It all works.  So I'm currently running this code in production by using a shell script to copy it inside my project.
+As of October 2019, up-to-date Vue-CLI apps are able to properly build and use `feathers-vuex` after adding `transpileDependencies`.  For apps based on older modules, I've found the simplest solution to be to copy the `feathers-vuex` module into `src/libs` inside your project.  Create a `copy-deps.sh` file in the root of your project and setup the following:
 
 ```bash
 rm -rf src/libs
@@ -70,7 +16,7 @@ mkdir src/libs
 cp -r node_modules/feathers-vuex/dist src/libs/feathers-vuex
 ```
 
-Then in my `package.json` scripts:
+Then in `package.json`, create a script that uses the `copy-deps.sh` file:
 
 ```json
 {
@@ -81,26 +27,7 @@ Then in my `package.json` scripts:
 }
 ```
 
-I don't consider the above solution to be a pretty one.  I likely will not publish 2.0 until a solution is discovered which doesn't required copying from `node_modules`.  I know it's got to be simple.  It's has something to do with transpile settings for `node_modules`.  I just haven't found it yet.
-
-## Quasar Build
-
-For Quasar apps, `transpileDependencies` can be updated in `quasar.conf.js` under build as
-
-```
-  build: {
-    transpileDependencies: ['feathers-vuex']
-  }
-```
-
-## Nuxt Build
-By default with Nuxt, the build server doesn't understand the word import, which is ES6 module syntax. You have to tell Nuxt in the config which node_modules to transpile from ES6 to ES5. (I tried avoiding this situation, but double transpilation while implementing classes can cause major issues at deployment time.) . Thankfully, the fix is easy in nuxt.config.js:
-
-```
-build: {
-    transpile: ['feathers-vuex'],
-}
-```
+It's not the prettiest solution, but it works well and is the simplest for older apps.
 
 ## Here's what's new in `feathers-vuex`
 

docs/api-overview.md

@@ -54,6 +54,8 @@ npm install feathers-vuex --save
 yarn add feathers-vuex
 ```
 
+IMPORTANT: Feathers-Vuex is (and requires to be) published in ES6 format for full compatibility with JS classes.  If your project uses Babel, it must be configured properly.  See the [Project Configuration](#projectconfiguration) section for more information.
+
 ### With feathers-socketio
 
 A realtime-transport like Socket.io or Primus is required in order to take advantage of the real-time socket events built into Feathers-Vuex. The `feathers-hooks-common` package, specified below, is not required to work with Feathers-Vuex.
@@ -78,6 +80,39 @@ npm i @feathersjs/feathers @feathersjs/rest-client @feathersjs/authentication-cl
 yarn add @feathersjs/feathers @feathersjs/rest-client @feathersjs/authentication-client feathers-hooks-common feathers-vuex
 ```
 
+## Project Configuration
+
+### Vue-CLI
+
+If your project runs on Vue-CLI, add the following to your `vue.config.js` file:
+
+```js
+module.exports = {
+  transpileDependencies: ['feathers-vuex']
+}
+```
+
+## Quasar
+
+For Quasar apps, `transpileDependencies` can be updated in `quasar.conf.js` under build as
+
+```
+build: {
+  transpileDependencies: ['feathers-vuex']
+}
+```
+
+## Nuxt
+
+If your project uses Nuxt, add the following to your `nuxt.config.js` file:
+
+```
+build: {
+  transpile: ['feathers-vuex'],
+}
+```
+
+
 ## Setup
 
 Using Feathers-Vuex happens in these steps: