Docs

Author: aarondfrancis

.gitignore

@@ -7,3 +7,6 @@ yarn-error.log
 composer.lock
 bootstrap/cache/packages.php
 bootstrap/cache/services.php
+
+docs/*.blade.php
+docs/**/*.blade.php

docs/configuration.md

@@ -0,0 +1,62 @@
+
+# Configuration
+
+The Airdrop configuration file contains a reasonable starting point for most Laravel applications, but you'll want to customize it for your particular app.
+
+To publish this file, run `php artisan airdrop:install`  
+
+## Drivers
+
+The driver you choose determines how your built assets will be stashed and restored.
+
+By default, we only offer one driver: the Filesystem driver. It will store built assets as `.zip` on a disk of your choosing (usually a cloud provider).
+
+To read more about the various configuration options, head to the [Filesystem Driver](/drivers/filesystem) section.
+
+## Triggers
+
+The `triggers` section tells Airdrop how to calculate if your assets need to be rebuilt. We offer two different triggers out of the box: 
+- [Config Trigger](/triggers/config) than can trigger a build based on ENV vars (or any other config).
+- [File Trigger](/triggers/file) that triggers a build whenever a file changes.
+
+Each trigger has its own configuration that you can use to fine-tune your settings, but both come with reasonable defaults.
+
+You can have as many triggers as you want. You can also [build your own](/triggers/custom).
+
+## Outputs
+
+The `outputs` section of the config file defines which files are generated as the result of your build process.
+
+**Anything that is generated as a result of your build process should be included here.**
+
+config/airdrop.php{.filename}
+```php
+[
+        // ...
+       'outputs' => [
+        /*
+         * Files or folders that should be included.
+         */
+        'include' => [
+            // The mix-manifest file tells Laravel how to get your versioned assets.
+            public_path('mix-manifest.json'),
+
+            // Compiled CSS.
+            public_path('css'),
+
+            // Compiled JS.
+            public_path('js'),
+        ],
+
+        /*
+         * Files or folders that should be excluded or ignored.
+         */
+        'exclude' => [
+            //
+        ],
+    ]
+];
+```
+
+
+By default Airdrop will store your compiled CSS, JS, and your mix-manifest file. If Airdrop determines that a build is not necessary on the next deploy, these files will be pulled down and put in place as if they had just been built.

docs/deploying.md

@@ -0,0 +1,65 @@
+
+# Deploying
+
+To integrate Airdrop into your build process, you'll need to do a few things.
+
+## Adding the Airdrop Commands
+
+The first thing you'll need to do is run `php artisan airdrop:download` _before_ you build your assets. This is the command that will download and place your built assets, if they are available.
+
+The next thing you'll need to do is run `php artisan airdrop:upload` _after_ you build your assets. This command will store the built assets, if they aren't already stored.
+
+This will take care of downloading and uploading your assets, should that be required.
+
+Once you're done, your asset step will look something like this:
+
+```bash
+php artisan airdop:download
+npm run production
+php artisan airdrop:upload
+```
+
+## Skipping Asset Compilation
+
+The next (and last!) thing we need to change is the skipping of the compilation of assets if it isn't required.
+
+The FilesystemDriver creates a flag file called `.airdrop_skip` if the asset building step can be skipped, so we need to check for the existence of that file.
+
+### Laravel Mix
+If you're using Laravel Mix you can modify your `webpack.mix.js` file to see if that file exists, and return early if it does:
+
+```js
+// Exit early if assets don't need to be built.
+if (require('fs').existsSync('.airdrop_skip')) {
+    console.log("Assets already exist. Skipping compilation.");
+    process.exit(0);
+}
+
+// Rest of the file...
+``` 
+{data-filename="webpack.mix.js"}
+
+### Bash
+
+If you're not using Laravel Mix, or you want to skip several steps based on the existence of that file, you can do so using bash.
+
+```bash
+php artisan airdrop:download
+
+# Skip several steps if we can.
+if [ ! -f ".airdrop_skip" ]; then
+    nvm install
+    nvm use
+    yarn install --frozen-lockfile
+    npm run production
+fi
+
+php artisan airdrop:upload
+```
+
+Now we're skipping multiple potentially expensive commands based on the presence of the Airdrop skip file. 
+
+> Remember: If you change the path of the skip file in your configuration, you'll need to change it in your Mix / Bash file as well.
+
+
+

docs/drivers/custom.md

@@ -0,0 +1,49 @@
+# Building A Custom Driver
+
+If the [Filesystem](/drivers/filesystem) Driver isn't quite right for you, you can build your own quite easily.
+
+Your custom driver must extend the Hammerstone `BaseDriver`.
+
+CustomDriver.php{.filename}
+```php
+use Hammerstone\Airdrop\Drivers\BaseDriver;
+
+class CustomDriver extends BaseDriver 
+{
+    /**
+     * Called after building, to stash the files somewhere.
+     */
+    public function upload()
+    {
+        // @TODO
+    }
+
+    /**
+     * Called before building files, to see if we can skip that
+     * altogether and just download them.
+     */
+    public function download()
+    {
+        // @TODO
+    }
+}
+```
+
+The current hash will be available as a class property `$hash`, and the config for your driver will be available as `$config`.
+
+## Enabling Your Custom Driver
+
+To enable your driver, you'll need to add it to the `drivers` array in `airdrop.php`.
+
+config/airdrop.php{.filename}
+```php
+'drivers' => [
+    'custom' => [
+        // Use our new custom class as the driver.
+        'class' => CustomDriver::class,
+        
+        // Pass in any configuration you want.
+        'key' => 'value' 
+    ]
+],
+```

docs/drivers/filesystem.md

@@ -0,0 +1,46 @@
+# Filesystem Driver
+
+The Filesystem Driver is the default (and only!) driver that we ship with. It stores all of your built assets as a `.zip` on a filesystem of your choosing. 
+
+
+## Configuration
+
+If you'd like to change the configuration, you can do so in `airdrop.php`.
+
+config/aidrop.php{.filename}
+```php
+[
+    'drivers' => [
+        'default' => [
+            // The class responsible for implementing the stash and restore
+            // logic. Must extend BaseDriver.
+            'class' => FilesystemDriver::class,
+        
+            // The disk on which to store the built files.
+            'disk' => env('AIRDROP_REMOTE_DISK', 's3'),
+        
+            // The folder (if any) where you'd like your stashed assets to reside.
+            'remote_directory' => env('AIRDROP_REMOTE_DIR', 'airdrop'),
+        
+            // A writeable directory on the machine that builds the assets.
+            // Used to build up the ZIP file before stashing it.
+            'local_tmp_directory' => env('AIRDROP_LOCAL_TMP_DIR', storage_path('framework')),
+        
+            // The skip file is an empty file that will be created to
+            // indicate that asset building can be skipped.
+            'skip_file' => env('AIRDROP_SKIP_FILE', base_path('.airdrop_skip')),
+        ]
+    ],
+]
+
+```
+
+
+`disk` controls which disk your built files are stored on.
+
+`remote_directory` allows you to place all of your built assets in a subdirectory on your remote disk, to avoid cluttering up the root directory.
+
+`local_tmp_directory` is a place that Airdrop can use to create the `.zip` file before it is uploaded. Airdrop will clean up after itself, so nothing will be left behind once it's done.
+
+`skip_file` is the file we referenced in the [deploying](/deploying) section. It's used as a signal to other processes that the built files have been successfully restored, and they do not need to be built again.
+

docs/installation.md

@@ -2,11 +2,13 @@
 # Installation
 
 You can install the package via Composer
-```
+```console
 composer require hammerstone/airdrop
 ```
 
 Once the package is installed, you may optionally publish the config file by running 
-```
+```console
 php artisan airdop:install
 ```
+
+You'll likely want to publish the config file so that you can set up your triggers and outputs.

docs/manifest.json

@@ -0,0 +1,23 @@
+{
+    "basePath": "/airdrop/docs/local",
+    "assetUrl": "/airdrop/docs/local",
+    "navigation": {
+        "Overview": "/overview",
+        "Installation": "/installation",
+        "Configuration": "/configuration",
+        "Deploying": "/deploying",
+        "Triggers": {
+            "children": {
+                "Config Trigger": "/triggers/config",
+                "File Trigger": "/triggers/file",
+                "Custom": "/triggers/custom"
+            }
+        },
+        "Drivers": {
+            "children": {
+                "Filesystem": "/drivers/filesystem",
+                "Custom": "/drivers/custom"
+            }
+        }
+    }
+}

docs/navigation.json

@@ -1,6 +1,16 @@
 
-# Airdrop for Laravel Overview
+# Airdrop for Laravel
 
-![Logo](/img/logo.png)
+Hammerstone Airdrop for Laravel is a package that speeds up your code deploys by skipping your asset build step whenever possible.
 
-Hammerstone Airdrop for Laravel is a package that speeds up your deploys by skipping your asset build step whenever possible.
+When you're deploying your code, Airdrop will calculate a hash of everything needed to build your assets: installed packages, JS/CSS files, ENV vars, etc. 
+
+After Airdrop has calculated a hash for these inputs, it will check to see if it has ever built this exact configuration before. If it has, it will pull down the built assets and put them in place, letting you skip the expensive build step.
+
+![Flowchart](/flowchart.png){style="width: 698px"}
+
+This can reduce the time your deploys and CI runs take from minutes down to just a few seconds:
+
+<div class='flex justify-center my-4'>
+<blockquote class="twitter-tweet"><p lang="en" dir="ltr">We&#39;ve sped up our <a href="https://twitter.com/ChipperCI?ref_src=twsrc%5Etfw">@ChipperCI</a> pipeline quite a bit by not building our assets if nothing on the frontend has changed, but instead downloading them from S3 already built.<br><br>Usually takes 1-3 minutes to build the assets, we can pull them off of S3 in seconds! <a href="https://t.co/owdZOEcJwP">pic.twitter.com/owdZOEcJwP</a></p>&mdash; Aaron Francis (@aarondfrancis) <a href="https://twitter.com/aarondfrancis/status/1180161402188771328?ref_src=twsrc%5Etfw">October 4, 2019</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
+</div>