work in progress, initial commit with a BIG thanks to @mgechev

Author: JohannesHoppe

.circleci/config.yml

@@ -0,0 +1,27 @@
+version: 2
+
+jobs:
+  build:
+
+    docker:
+      - image: circleci/node:12-browsers
+
+    steps:
+      - checkout
+
+      - restore_cache:
+          key: dependency-cache-{{ checksum "src/package.json" }}
+      - run: cd src && npm i --silent
+      - save_cache:
+          key: dependency-cache-{{ checksum "src/package.json" }}
+          paths:
+            - src/node_modules
+      - run: cd src && npm run build
+      - run: cd src && npm run test
+      - run: cd src/dist && sudo npm link
+
+      - run: sudo -E npm install -g @angular/cli@next
+      - run: sudo -E ng new your-angular-project --defaults
+      - run: cd your-angular-project && sudo -E npm link ngx-deploy-starter
+      - run: cd your-angular-project && sudo -E ng add ngx-deploy-starter
+      - run: cd your-angular-project && sudo -E ng deploy

.editorconfig

@@ -0,0 +1,13 @@
+# Editor configuration, see http://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

.gitignore

@@ -0,0 +1,27 @@
+node_modules
+.tmp
+.sass-cache
+.DS_Store
+.bash_history
+*.swp
+*.swo
+*.d.ts
+
+*.classpath
+*.project
+*.settings/
+*.classpath
+*.project
+*.settings/
+
+.vim/bundle
+nvim/autoload
+nvim/plugged
+nvim/doc
+nvim/swaps
+nvim/colors
+dist
+
+/src/mini-testdrive/404.html
+/src/mini-testdrive/CNAME
+.angulardoc.json

.vscode/tasks.json

@@ -0,0 +1,13 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "type": "npm",
+            "script": "build",
+            "path": "src/",
+            "label": "npm build"
+        }
+    ]
+}

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 John Doe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,51 @@
+# ngx-deploy-starter
+
+## About
+
+This is a sample project that helps you to implement your own __deployment builder__ for the Angular CLI.
+The groundwork of this starter was provided by Minko Gechev's [ngx-gh project](https://github.com/mgechev/ngx-gh).
+
+This project has the following purposes:
+
+1. To promote the adoption of `ng deploy`.
+2. To clarify various questions and to standardise the experience of the various builders.
+
+## Essential considerations
+
+These rules are open for discussion, of course.
+
+### 1. A deployment builder should always compile the project before the deployment
+
+To reduce the chances to deploy corrupted assets, it's important to build the app right before deploying it. ([source](https://github.com/angular-schule/website-articles/pull/3#discussion_r315802100))
+
+Currently there are existing deployment builders that only build in production mode.
+This might be not enough.
+There is also the approach not to perform the build step at all.
+
+**Our suggestion:**
+By default, a deployment builder compiles in `production` mode, but you can configure an other coniguration using the option `--configuration`.
+
+### 2. A deployment builder should have an interactive wizard after the "ng add".
+
+This wizard should ask all necessary questions and should persist the answers in the `angular.json` file.
+This feature is not implemented yet, but we are looking forward to your feedback.
+
+### 2. More to come
+
+What's bothers you about this example? We appreciate your feedback!
+
+
+## How to make your own deploy builder
+
+1. fork this repository
+2. adjust the `package.json`
+3. search and replace for the string `ngx-deploy-starter` and choose your own name.
+4. search and replace for the string `to the file system` and name your deploy target.
+5. add your deployment code to `src/engine/engine.ts`x
+
+
+You are free to customise this project according to your needs.
+Please keep the spirit of Open Source alive and use the MIT or a compatible license.
+
+## License
+Code released under the [MIT license](LICENSE).

docs/README_contributors.md

@@ -0,0 +1,133 @@
+# ngx-deploy-starter: README for contributors
+
+## How to start <a name="start"></a>
+
+tl;dr – execute this:
+
+```
+cd src
+npm i
+npm run build
+npm test
+```
+
+
+## Local development <a name="local-dev"></a>
+
+If you want to try the latest package locally without installing it from NPM, use the following instructions.
+This may be useful when you want to try the latest non-published version of this library or you want to make a contribution.
+
+Follow the instructions for [checking and updating the Angular CLI version](#angular-cli) and then link the package.
+
+
+### 1. Angular CLI <a name="angular-cli"></a>
+
+1. Install the next version of the Angular CLI.
+
+   ```sh
+   npm install -g @angular/cli@next
+   ```
+
+2. Run `ng version`, make sure you have installed Angular CLI v8.3.0-next.0 or greater.
+
+3. Update your existing project using the command:
+
+   ```sh
+   ng update @angular/cli @angular/core --next=true
+   ```
+
+
+### 2. npm link
+
+Use the following instructions to make `ngx-deploy-starter` available locally via `npm link`.
+
+1. Clone the project
+
+   ```sh
+   git clone https://github.com/angular-schule/ngx-deploy-starter.git
+   cd ngx-deploy-starter
+   ```
+
+2. Install the dependencies
+
+   ```sh
+   cd src
+   npm install
+   ```
+
+3. Build the project:
+
+   ```sh
+   npm run build
+   ```
+
+4. Create a local npm link:
+
+   ```sh
+   cd dist
+   npm link
+   ```
+
+Read more about the `link` feature in the [official NPM documentation](https://docs.npmjs.com/cli/link).
+
+
+### 3. Adding to an Angular project -- ng add <a name="local-dev-add"></a>
+
+Once you have completed the previous steps to `npm link` the local copy of `ngx-deploy-starter`, follow these steps to use it in a local Angular project.
+
+1. Enter the project directory
+
+   ```sh
+   cd your-angular-project
+   ```
+
+2. Add the local version of `ngx-deploy-starter`.
+
+   ```sh
+   npm link ngx-deploy-starter
+   ```
+
+3. Now execute the `ng-add` schematic.
+
+   ```sh
+   ng add ngx-deploy-starter
+   ```
+
+4. You can now deploy your angular app to GitHub pages.
+
+   ```sh
+   ng run your-angular-project:deploy
+   ```
+
+5. You can remove the link later by running `npm unlink`
+
+
+### 4. Testing <a name="testing"></a>
+
+Testing is done with [Jest](https://jestjs.io/).
+To run the tests:
+
+```sh
+cd ngx-deploy-starter/src
+npm test
+```
+
+
+
+
+
+## Testing the standalone CLI
+
+To quickly test the file `engine.ts` directly, the standalone mode is the best option.
+Use VSCode and debug the task `Launch Standalone Program`.
+
+
+## Publish to NPM
+
+```
+cd ngx-deploy-starter/src
+npm run build
+npm run test
+npm publish dist
+npm dist-tag add [email protected] next
+```

src/README.md

@@ -0,0 +1,43 @@
+# ngx-deploy-starter
+
+**Deploy your Angular app to the file system directly from the Angular CLI! 🚀**
+
+
+## Usage
+
+Add `ngx-deploy-starter` to your project.
+
+```bash
+ng add ngx-deploy-starter
+```
+
+Deploy your project to the file system.
+
+```
+ng deploy [options]
+```
+
+
+## Options
+
+The following options are also available.
+
+#### --target-dir
+ * __optional__
+ * Default: `~/example-folder` (string)
+ * Example:
+    * `ng deploy` -- App is "deployed" to the example folder (if existing)
+    * `ng deploy --target-/var/www/html` -- App is "deployed" to another folder
+
+
+#### --configuration
+ * __optional__
+ * Default: `production` (string)
+ * Example:
+    * `ng deploy` -- Angular project is build in production mode
+    * `ng deploy --configuration=qs` -- Angular project is using the configuration `qs` (this configuration must exist in the `angular.json` file)
+
+A named build target, as specified in the `configurations` section of `angular.json`.
+Each named target is accompanied by a configuration of option defaults for that target.
+Same as `ng build --configuration=XXX`.
+

src/builders.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "@angular-devkit/architect/src/builders-schema.json",
+  "builders": {
+    "deploy": {
+      "implementation": "./deploy/builder",
+      "schema": "./deploy/schema.json",
+      "description": "Deploy builder"
+    }
+  }
+}

src/collection.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Add ngx-deploy-starter deploy schematic",
+      "factory": "./ng-add#ngAdd"
+    }
+  }
+}